From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Fri, 23 Jun 2023 14:45:12 +0000 (-0400)
Subject: add explicit warning re: mapped_column.default
X-Git-Tag: rel_2_0_17~1
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=4baaf5a813c2d9ab58787c57aac10ac52e55b9c1;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

add explicit warning re: mapped_column.default

Change-Id: I3ac7133323a02cb70e20de2fd96cc31842ead4f1
References: #9936
References: #10009
---

diff --git a/lib/sqlalchemy/orm/_orm_constructors.py b/lib/sqlalchemy/orm/_orm_constructors.py
index fab93f6824..b5586350d0 100644
--- a/lib/sqlalchemy/orm/_orm_constructors.py
+++ b/lib/sqlalchemy/orm/_orm_constructors.py
@@ -246,6 +246,15 @@ def mapped_column(
      :class:`_sql.Insert` construct would use in any case, leading to the same
      end result.
 
+     .. note:: When using Core level column defaults that are callables to
+        be interpreted by the underlying :class:`_schema.Column` in conjunction
+        with :ref:`ORM-mapped dataclasses
+        <orm_declarative_native_dataclasses>`, especially those that are
+        :ref:`context-aware default functions <context_default_functions>`,
+        **the** :paramref:`_orm.mapped_column.insert_default` **parameter must
+        be used instead**.  This is necessary to disambiguate the callable from
+        being interpreted as a dataclass level default.
+
     :param insert_default: Passed directly to the
      :paramref:`_schema.Column.default` parameter; will supersede the value
      of :paramref:`_orm.mapped_column.default` when present, however