bpo-22807: Expose platform UUID generation safety information. (#138)

bpo-22807: Expose platform UUID generation safety information.

1 files changed, 30 insertions, 1 deletions

diff --git a/Doc/library/uuid.rst b/Doc/library/uuid.rst
index edbf832..ea9ea7d 100644
--- a/Doc/library/uuid.rst
+++ b/Doc/library/uuid.rst
@@ -19,8 +19,30 @@ If all you want is a unique ID, you should probably call :func:`uuid1` or
 a UUID containing the computer's network address.  :func:`uuid4` creates a
 random UUID.
 
+Depending on support from the underlying platform, :func:`uuid1` may or may
+not return a "safe" UUID.  A safe UUID is one which is generated using
+synchronization methods that ensure no two processes can obtain the same
+UUID.  All instances of :class:`UUID` have an :attr:`is_safe` attribute
+which relays any information about the UUID's safety, using this enumeration:
 
-.. class:: UUID(hex=None, bytes=None, bytes_le=None, fields=None, int=None, version=None)
+.. class:: SafeUUID
+
+   .. versionadded:: 3.7
+
+   .. attribute:: SafeUUID.safe
+
+      The UUID was generated by the platform in a multiprocessing-safe way.
+
+   .. attribute:: SafeUUID.unsafe
+
+      The UUID was not generated in a multiprocessing-safe way.
+
+   .. attribute:: SafeUUID.unknown
+
+      The platform does not provide information on whether the UUID was
+      generated safely or not.
+
+.. class:: UUID(hex=None, bytes=None, bytes_le=None, fields=None, int=None, version=None, *, is_safe=SafeUUID.unknown)
 
    Create a UUID from either a string of 32 hexadecimal digits, a string of 16
    bytes as the *bytes* argument, a string of 16 bytes in little-endian order as
@@ -120,6 +142,13 @@ random UUID.
    The UUID version number (1 through 5, meaningful only when the variant is
    :const:`RFC_4122`).
 
+.. attribute:: UUID.is_safe
+
+   An enumeration of :class:`SafeUUID` which indicates whether the platform
+   generated the UUID in a multiprocessing-safe way.
+
+   .. versionadded:: 3.7
+
 The :mod:`uuid` module defines the following functions: