From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Fri, 31 Mar 2023 12:46:53 +0000 (-0400)
Subject: clarify the Uuid datatype handles Python uuid objects by default
X-Git-Tag: rel_2_0_8~7
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=f35a3f15321bd16cdc9cce69468cb50555b96a6b;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

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 4583948704..553b07442f 100644
--- 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::