Issue #26267: Improve uuid.UUID documentation

* Document how comparison of UUID objects work
* Document str(uuid) returns the braceless standard form
* Add a test for comparison of a UUID object with a non-UUID object

Patch by Ammar Askar.

2 files changed, 11 insertions, 0 deletions

diff --git a/Doc/library/uuid.rst b/Doc/library/uuid.rst
index 53cbd6c770..91dbca2edd 100644
--- a/Doc/library/uuid.rst
+++ b/Doc/library/uuid.rst
@@ -45,6 +45,13 @@ random UUID.
    variant and version number set according to RFC 4122, overriding bits in the
    given *hex*, *bytes*, *bytes_le*, *fields*, or *int*.
 
+   Comparison of UUID objects are made by way of comparing their
+   :attr:`UUID.int` attributes.  Comparison with a non-UUID object
+   raises a :exc:`TypeError`.
+
+   ``str(uuid)`` returns a string in the form
+   ``12345678-1234-5678-1234-567812345678`` where the 32 hexadecimal digits
+   represent the UUID.
 
 :class:`UUID` instances have these read-only attributes:
 
diff --git a/Lib/test/test_uuid.py b/Lib/test/test_uuid.py
index e34d8e6257..47248f92c7 100644
--- a/Lib/test/test_uuid.py
+++ b/Lib/test/test_uuid.py
@@ -292,6 +292,10 @@ class TestUUID(unittest.TestCase):
         badtype(lambda: setattr(u, 'clock_seq_low', 0))
         badtype(lambda: setattr(u, 'node', 0))
 
+        # Comparison with a non-UUID object
+        badtype(lambda: u < object())
+        badtype(lambda: u > object())
+
     def test_getnode(self):
         node1 = uuid.getnode()
         self.assertTrue(0 < node1 < (1 << 48), '%012x' % node1)