From: Federico Caselli Date: Mon, 4 Dec 2023 20:14:45 +0000 (+0100) Subject: Document limitation in dataclass mapping styles X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1669ae65da251bfe7c8afb9b6a983bec81e8ac1b;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git Document limitation in dataclass mapping styles Document that using default and init=False on a dataclass field mapped imperatively or using imperative table will not work. Change-Id: Id2e27e4f7f0cafc60be3f97b7945983360c0a7d2 References: #9879 --- diff --git a/doc/build/orm/cascades.rst b/doc/build/orm/cascades.rst index efb997560a..4c1e365ef7 100644 --- a/doc/build/orm/cascades.rst +++ b/doc/build/orm/cascades.rst @@ -303,7 +303,7 @@ directives described at :ref:`passive_deletes` should be used. .. warning:: Note that the ORM's "delete" and "delete-cascade" behavior applies **only** to the use of the :meth:`_orm.Session.delete` method to mark - individual ORM instances for deletion within the :term:`unit-of-work` process. + individual ORM instances for deletion within the :term:`unit of work` process. It does **not** apply to "bulk" deletes, which would be emitted using the :func:`_sql.delete` construct as illustrated at :ref:`orm_queryguide_update_delete_where`. See diff --git a/doc/build/orm/dataclasses.rst b/doc/build/orm/dataclasses.rst index b7d0bee431..19fabe9f83 100644 --- a/doc/build/orm/dataclasses.rst +++ b/doc/build/orm/dataclasses.rst @@ -705,6 +705,15 @@ which itself is specified within the ``__mapper_args__`` dictionary, so that it is passed to the constructor for :class:`_orm.Mapper`. An alternative to this approach is in the next example. + +.. warning:: + Declaring a dataclass ``field()`` setting a ``default`` together with ``init=False`` + will not work as would be expected with a totally plain dataclass, + since the SQLAlchemy class instrumentation will replace + the default value set on the class by the dataclass creation process. + Use ``default_factory`` instead. This adaptation is done automatically when + making use of :ref:`orm_declarative_native_dataclasses`. + .. _orm_declarative_dataclasses_declarative_table: Mapping pre-existing dataclasses using Declarative-style fields @@ -909,6 +918,9 @@ variables:: mapper_registry.map_imperatively(Address, address) +The same warning mentioned in :ref:`orm_declarative_dataclasses_imperative_table` +applies when using this mapping style. + .. _orm_declarative_attrs_imperative_table: Applying ORM mappings to an existing attrs class diff --git a/doc/build/orm/queryguide/dml.rst b/doc/build/orm/queryguide/dml.rst index ec09c61dfd..a2c10c1bb3 100644 --- a/doc/build/orm/queryguide/dml.rst +++ b/doc/build/orm/queryguide/dml.rst @@ -995,7 +995,7 @@ For a DELETE, an example of deleting rows based on criteria:: .. warning:: Please read the following section :ref:`orm_queryguide_update_delete_caveats` for important notes regarding how the functionality of ORM-Enabled UPDATE and DELETE - diverges from that of ORM :term:`unit-of-work` features, such + diverges from that of ORM :term:`unit of work` features, such as using the :meth:`_orm.Session.delete` method to delete individual objects. @@ -1004,7 +1004,7 @@ For a DELETE, an example of deleting rows based on criteria:: Important Notes and Caveats for ORM-Enabled Update and Delete ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The ORM-enabled UPDATE and DELETE features bypass ORM :term:`unit-of-work` +The ORM-enabled UPDATE and DELETE features bypass ORM :term:`unit of work` automation in favor of being able to emit a single UPDATE or DELETE statement that matches multiple rows at once without complexity.