From 020e7e3fe6f21e2fc726ac08783923424157951c Mon Sep 17 00:00:00 2001
From: Weilin Du <108666168+LamentXU123@users.noreply.github.com>
Date: Mon, 18 Aug 2025 19:24:19 +0800
Subject: [PATCH] gh-137847: Add examples for UUIDv6-8 (GH-137848) (cherry
 picked from commit 63fffb15f5e6b32c8e15eee40edae653eb0f6688)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Weilin Du <108666168+LamentXU123@users.noreply.github.com>
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
---
 Doc/library/uuid.rst | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/Doc/library/uuid.rst b/Doc/library/uuid.rst
index 6698e6d3f43c43..aa4f1bf940bc5c 100644
--- a/Doc/library/uuid.rst
+++ b/Doc/library/uuid.rst
@@ -411,7 +411,7 @@ Here are some examples of typical usage of the :mod:`uuid` module::
    >>> import uuid
 
    >>> # make a UUID based on the host ID and current time
-   >>> uuid.uuid1()
+   >>> uuid.uuid1()  # doctest: +SKIP
    UUID('a8098c1a-f86e-11da-bd1a-00112444be1e')
 
    >>> # make a UUID using an MD5 hash of a namespace UUID and a name
@@ -449,15 +449,24 @@ Here are some examples of typical usage of the :mod:`uuid` module::
    >>> uuid.MAX
    UUID('ffffffff-ffff-ffff-ffff-ffffffffffff')
 
+   >>> # same as UUIDv1 but with fields reordered to improve DB locality
+   >>> uuid.uuid6()  # doctest: +SKIP
+   UUID('1f0799c0-98b9-62db-92c6-a0d365b91053')
+
    >>> # get UUIDv7 creation (local) time as a timestamp in milliseconds
    >>> u = uuid.uuid7()
    >>> u.time  # doctest: +SKIP
    1743936859822
+
    >>> # get UUIDv7 creation (local) time as a datetime object
    >>> import datetime as dt
    >>> dt.datetime.fromtimestamp(u.time / 1000)  # doctest: +SKIP
    datetime.datetime(...)
 
+   >>> # make a UUID with custom blocks
+   >>> uuid.uuid8(0x12345678, 0x9abcdef0, 0x11223344)
+   UUID('00001234-5678-8ef0-8000-000011223344')
+
 
 .. _uuid-cli-example: