PYTHON-2252 Add examples and documentation for new UUID behavior

bson/binary.py

@@ -69,6 +69,8 @@ class UuidRepresentation:
     code. When decoding a BSON binary field with a UUID subtype, a
     :class:`~bson.binary.Binary` instance will be returned instead of a
     :class:`uuid.UUID` instance.
+
+    See :ref:`unspecified-representation-details` for details.
 
     .. versionadded:: 3.11
     """
@@ -79,6 +81,8 @@ class UuidRepresentation:
     :class:`uuid.UUID` instances will automatically be encoded to
     and decoded from BSON binary, using RFC-4122 byte order with
     binary subtype :data:`UUID_SUBTYPE`.
+
+    See :ref:`standard-representation-details` for details.
 
     .. versionadded:: 3.11
     """
@@ -89,6 +93,8 @@ class UuidRepresentation:
     :class:`uuid.UUID` instances will automatically be encoded to
     and decoded from BSON binary, using RFC-4122 byte order with
     binary subtype :data:`OLD_UUID_SUBTYPE`.
+
+    See :ref:`python-legacy-representation-details` for details.
 
     .. versionadded:: 3.11
     """
@@ -99,6 +105,8 @@ class UuidRepresentation:
     :class:`uuid.UUID` instances will automatically be encoded to
     and decoded from BSON binary subtype :data:`OLD_UUID_SUBTYPE`,
     using the Java driver's legacy byte order.
+
+    See :ref:`java-legacy-representation-details` for details.
 
     .. versionadded:: 3.11
     """
@@ -109,6 +117,8 @@ class UuidRepresentation:
     :class:`uuid.UUID` instances will automatically be encoded to
     and decoded from BSON binary subtype :data:`OLD_UUID_SUBTYPE`,
     using the C# driver's legacy byte order.
+
+    See :ref:`csharp-legacy-representation-details` for details.
 
     .. versionadded:: 3.11
     """
@@ -220,6 +230,7 @@ def from_uuid(cls, uuid, uuid_representation=UuidRepresentation.STANDARD):
           - `uuid_representation`: A member of
             :class:`~bson.binary.UuidRepresentation`. Default:
             :const:`~bson.binary.UuidRepresentation.STANDARD`.
+            See :ref:`handling-uuid-data-example` for details.
 
         .. versionadded:: 3.11
         """
@@ -236,7 +247,8 @@ def from_uuid(cls, uuid, uuid_representation=UuidRepresentation.STANDARD):
                 "UuidRepresentation.UNSPECIFIED. UUIDs can be manually "
                 "converted to bson.Binary instances using "
                 "bson.Binary.from_uuid() or a different UuidRepresentation "
-                "can be configured.")
+                "can be configured. See the documentation for "
+                "UuidRepresentation for more information.")
 
         subtype = OLD_UUID_SUBTYPE
         if uuid_representation == UuidRepresentation.PYTHON_LEGACY:
@@ -266,6 +278,7 @@ def as_uuid(self, uuid_representation=UuidRepresentation.STANDARD):
           - `uuid_representation`: A member of
             :class:`~bson.binary.UuidRepresentation`. Default:
             :const:`~bson.binary.UuidRepresentation.STANDARD`.
+            See :ref:`handling-uuid-data-example` for details.
 
         .. versionadded:: 3.11
         """

bson/codec_options.py

@@ -218,7 +218,10 @@ class CodecOptions(_options_base):
         naive. Defaults to ``False``.
       - `uuid_representation`: The BSON representation to use when encoding
         and decoding instances of :class:`~uuid.UUID`. Defaults to
-        :data:`~bson.binary.PYTHON_LEGACY`.
+        :data:`~bson.binary.UuidRepresentation.PYTHON_LEGACY`. New
+        applications should consider setting this to
+        :data:`~bson.binary.UuidRepresentation.STANDARD` for cross language
+        compatibility. See :ref:`handling-uuid-data-example` for details.
       - `unicode_decode_error_handler`: The error handler to apply when
         a Unicode-related error occurs during BSON decoding that would
         otherwise raise :exc:`UnicodeDecodeError`. Valid options include

doc/examples/index.rst

@@ -32,3 +32,4 @@ MongoDB, you can start it like so:
    tailable
    tls
    encryption
+   uuid