Skip to content

gh-128427: Add uuid.NIL and uuid.MAX #128429

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hugovk merged 7 commits into from
Jan 27, 2025
Merged

gh-128427: Add uuid.NIL and uuid.MAX #128429

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
50c6294
Add `uuid.NIL` and `uuid.MAX`
ngnpope Jan 2, 2025
fc14200
Edits to documentation
ngnpope Jan 3, 2025
8b71df2
Edits to tests
ngnpope Jan 3, 2025
2fde894
More tweaks to test assertions
ngnpope Jan 6, 2025
ecf263a
Add comments to test assertions
ngnpope Jan 6, 2025
cba80bc
Empty commit to retrigger CI
ngnpope Jan 6, 2025
bf61ffe
Remove extra links
ngnpope Jan 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions Doc/library/uuid.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -289,6 +289,25 @@ of the :attr:`~UUID.variant` attribute:
Reserved for future definition.


The :mod:`uuid` module defines the special Nil and Max UUID values:


.. data:: NIL

A special form of UUID that is specified to have all 128 bits set to zero
according to :rfc:`RFC 9562, §5.9 <9562#section-5.9>`.
Copy link
Member

@hugovk hugovk Jan 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Linking directly to the section is helpful, perhaps we only need to mention the RFC number here? If so, we could update the same thing for uuid8 above.

Suggested change
according to :rfc:`RFC 9562, §5.9 <9562#section-5.9>`.
according to :rfc:`RFC 9562 <9562#section-5.9>`.


.. versionadded:: next


.. data:: MAX

A special form of UUID that is specified to have all 128 bits set to one
according to :rfc:`RFC 9562, §5.10 <9562#section-5.10>`.
Copy link
Member

@hugovk hugovk Jan 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
according to :rfc:`RFC 9562, §5.10 <9562#section-5.10>`.
according to :rfc:`RFC 9562 <9562#section-5.10>`.


.. versionadded:: next


.. seealso::

:rfc:`9562` - A Universally Unique IDentifier (UUID) URN Namespace
Expand Down Expand Up @@ -380,6 +399,14 @@ Here are some examples of typical usage of the :mod:`uuid` module::
>>> uuid.UUID(bytes=x.bytes)
UUID('00010203-0405-0607-0809-0a0b0c0d0e0f')

>>> # get the Nil UUID
>>> uuid.NIL
UUID('00000000-0000-0000-0000-000000000000')

>>> # get the Max UUID
>>> uuid.MAX
UUID('ffffffff-ffff-ffff-ffff-ffffffffffff')


.. _uuid-cli-example:

Expand Down
5 changes: 5 additions & 0 deletions Doc/whatsnew/3.14.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -665,6 +665,11 @@ uuid
in :rfc:`9562`.
(Contributed by Bénédikt Tran in :gh:`89083`.)

* :const:`uuid.NIL` and :const:`uuid.MAX` are now available to represent the
Nil and Max UUID formats as defined by :rfc:`9562`.
(Contributed by Nick Pope in :gh:`128427`.)


zipinfo
-------

Expand Down
41 changes: 41 additions & 0 deletions Lib/test/test_uuid.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,47 @@ def get_command_stdout(command, args):
class BaseTestUUID:
uuid = None

def test_nil_uuid(self):
nil_uuid = self.uuid.NIL

s = '00000000-0000-0000-0000-000000000000'
i = 0
self.assertEqual(nil_uuid, self.uuid.UUID(s))
self.assertEqual(nil_uuid, self.uuid.UUID(int=i))
self.assertEqual(nil_uuid.int, i)
self.assertEqual(str(nil_uuid), s)
# The Nil UUID falls within the range of the Apollo NCS variant as per
# RFC 9562.
# See https://www.rfc-editor.org/rfc/rfc9562.html#section-5.9-4
self.assertEqual(nil_uuid.variant, self.uuid.RESERVED_NCS)
# A version field of all zeros is "Unused" in RFC 9562, but the version
# field also only applies to the 10xx variant, i.e. the variant
# specified in RFC 9562. As such, because the Nil UUID falls under a
# different variant, its version is considered undefined.
# See https://www.rfc-editor.org/rfc/rfc9562.html#table2
self.assertIsNone(nil_uuid.version)

def test_max_uuid(self):
max_uuid = self.uuid.MAX

s = 'ffffffff-ffff-ffff-ffff-ffffffffffff'
i = (1 << 128) - 1
self.assertEqual(max_uuid, self.uuid.UUID(s))
self.assertEqual(max_uuid, self.uuid.UUID(int=i))
self.assertEqual(max_uuid.int, i)
self.assertEqual(str(max_uuid), s)
# The Max UUID falls within the range of the "yet-to-be defined" future
# UUID variant as per RFC 9562.
# See https://www.rfc-editor.org/rfc/rfc9562.html#section-5.10-4
self.assertEqual(max_uuid.variant, self.uuid.RESERVED_FUTURE)
# A version field of all ones is "Reserved for future definition" in
# RFC 9562, but the version field also only applies to the 10xx
# variant, i.e. the variant specified in RFC 9562. As such, because the
# Max UUID falls under a different variant, its version is considered
# undefined.
# See https://www.rfc-editor.org/rfc/rfc9562.html#table2
self.assertIsNone(max_uuid.version)

def test_safe_uuid_enum(self):
class CheckedSafeUUID(enum.Enum):
safe = 0
Expand Down
13 changes: 13 additions & 0 deletions Lib/uuid.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,14 @@
# make a UUID from a 16-byte string
>>> uuid.UUID(bytes=x.bytes)
UUID('00010203-0405-0607-0809-0a0b0c0d0e0f')

# get the Nil UUID
>>> uuid.NIL
UUID('00000000-0000-0000-0000-000000000000')

# get the Max UUID
>>> uuid.MAX
UUID('ffffffff-ffff-ffff-ffff-ffffffffffff')
"""

import os
Expand Down Expand Up @@ -799,5 +807,10 @@ def main():
NAMESPACE_OID = UUID('6ba7b812-9dad-11d1-80b4-00c04fd430c8')
NAMESPACE_X500 = UUID('6ba7b814-9dad-11d1-80b4-00c04fd430c8')

# RFC 9562 Sections 5.9 and 5.10 define the special Nil and Max UUID formats.

NIL = UUID('00000000-0000-0000-0000-000000000000')
MAX = UUID('ffffffff-ffff-ffff-ffff-ffffffffffff')

if __name__ == "__main__":
main()
1 change: 1 addition & 0 deletions Misc/ACKS
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1473,6 +1473,7 @@ Michael Pomraning
Martin Pool
Iustin Pop
Claudiu Popa
Nick Pope
John Popplewell
Matheus Vieira Portela
Davin Potts
Expand Down
2 changes: 2 additions & 0 deletions Misc/NEWS.d/next/Library/2025-01-02-20-34-04.gh-issue-128427.onPoQZ.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
:const:`uuid.NIL` and :const:`uuid.MAX` are now available to represent the Nil
and Max UUID formats as defined by :rfc:`9562`.
Loading