clarify the Uuid datatype handles Python uuid objects by default

Change-Id: I28147bfb4eb0762e9482d4f38bc1d89355152ad4
References: #9573

diff --git a/lib/sqlalchemy/sql/sqltypes.py b/lib/sqlalchemy/sql/sqltypes.py
index 4583948704f33975beb8d5b84a6536a5a4aaeb5f..553b07442f35cdced27ffc14a76dd283855098c5 100644 (file)
--- a/lib/sqlalchemy/sql/sqltypes.py
+++ b/lib/sqlalchemy/sql/sqltypes.py
@@ -3555,6 +3555,36 @@ class Uuid(TypeEngine[_UUID_RETURN]):
     "native" mode enabled by default allows these types will be used on those
     backends.
 
+    In its default mode of use, the :class:`_sqltypes.Uuid` datatype expects
+    **Python uuid objects**, from the Python
+    `uuid <https://docs.python.org/3/library/uuid.html>`_
+    module::
+
+        import uuid
+
+        from sqlalchemy import Uuid
+        from sqlalchemy import Table, Column, MetaData, String
+
+
+        metadata_obj = MetaData()
+
+        t = Table(
+            "t",
+            metadata_obj,
+            Column('uuid_data', Uuid, primary_key=True),
+            Column("other_data", String)
+        )
+
+        with engine.begin() as conn:
+            conn.execute(
+                t.insert(),
+                {"uuid_data": uuid.uuid4(), "other_data", "some data"}
+            )
+
+    To have the :class:`_sqltypes.Uuid` datatype work with string-based
+    Uuids (e.g. 32 character hexadecimal strings), pass the
+    :paramref:`_sqltypes.Uuid.as_uuid` parameter with the value ``False``.
+
     .. versionadded:: 2.0
 
     .. seealso::