From eb0802f79a16772fdf5edb1c45a5210ee0926137 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C3=A9n=C3=A9dikt=20Tran?=
 <10796600+picnixz@users.noreply.github.com>
Date: Sun, 6 Apr 2025 13:28:33 +0200
Subject: [PATCH 1/3] add UUIDv7 timestamp recipes

---
 Doc/library/uuid.rst | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/Doc/library/uuid.rst b/Doc/library/uuid.rst
index 13c00d22ef0299..f10f97038cc169 100644
--- a/Doc/library/uuid.rst
+++ b/Doc/library/uuid.rst
@@ -121,8 +121,10 @@ which relays any information about the UUID's safety, using this enumeration:
      - The last 48 bits of the UUID. Only relevant to version 1.
 
    * - .. attribute:: UUID.time
-     - The 60-bit timestamp for version 1 and 6,
-       or the 48-bit timestamp for version 7.
+     - The 60-bit timestamp as a count of 100-nanosecond intervals since
+       Gregorian epoch (1582-10-15 00:00:00) for versions 1 and 6, or the
+       48-bit timestamp in milliseconds since Unix epoch (1970-01-01 00:00:00)
+       for version 7.
 
    * - .. attribute:: UUID.clock_seq
      - The 14-bit sequence number. Only relevant to versions 1 and 6.
@@ -434,6 +436,14 @@ Here are some examples of typical usage of the :mod:`uuid` module::
    >>> uuid.MAX
    UUID('ffffffff-ffff-ffff-ffff-ffffffffffff')
 
+   >>> # get UUIDv7 creation (local) time as a timestamp in millisecond
+   >>> u = uuid.uuid7()
+   >>> u.time  # doctest: +SKIP
+   1743936859822
+   >>> # get UUIDv7 creation (local) time as a datetime object
+   >>> datetime.fromtimestamp(u.time / 1000)  # doctest: +SKIP
+   datetime.datetime(...)
+
 
 .. _uuid-cli-example:
 

From 963f6320a6a1fffafeabd48414a2e980d1134b06 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C3=A9n=C3=A9dikt=20Tran?=
 <10796600+picnixz@users.noreply.github.com>
Date: Mon, 7 Apr 2025 17:07:48 +0200
Subject: [PATCH 2/3] explicitly import `datetime`

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
---
 Doc/library/uuid.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Doc/library/uuid.rst b/Doc/library/uuid.rst
index f10f97038cc169..fea306f050b664 100644
--- a/Doc/library/uuid.rst
+++ b/Doc/library/uuid.rst
@@ -441,7 +441,8 @@ Here are some examples of typical usage of the :mod:`uuid` module::
    >>> u.time  # doctest: +SKIP
    1743936859822
    >>> # get UUIDv7 creation (local) time as a datetime object
-   >>> datetime.fromtimestamp(u.time / 1000)  # doctest: +SKIP
+   >>> import datetime as dt
+   >>> dt.datetime.fromtimestamp(u.time / 1000)  # doctest: +SKIP
    datetime.datetime(...)
 
 

From d74dc13baf89eff340db137d860d276b27ff4649 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C3=A9n=C3=A9dikt=20Tran?=
 <10796600+picnixz@users.noreply.github.com>
Date: Mon, 7 Apr 2025 17:07:55 +0200
Subject: [PATCH 3/3] Update Doc/library/uuid.rst

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
---
 Doc/library/uuid.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Doc/library/uuid.rst b/Doc/library/uuid.rst
index fea306f050b664..75ea27c7d39b18 100644
--- a/Doc/library/uuid.rst
+++ b/Doc/library/uuid.rst
@@ -436,7 +436,7 @@ Here are some examples of typical usage of the :mod:`uuid` module::
    >>> uuid.MAX
    UUID('ffffffff-ffff-ffff-ffff-ffffffffffff')
 
-   >>> # get UUIDv7 creation (local) time as a timestamp in millisecond
+   >>> # get UUIDv7 creation (local) time as a timestamp in milliseconds
    >>> u = uuid.uuid7()
    >>> u.time  # doctest: +SKIP
    1743936859822