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 efb997560a81c13b053aa7a6907e3af6e2d44cb5..4c1e365ef7d2940f54552f8f2fa485690fda62fe 100644 (file)
--- 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 b7d0bee43138851ce3b44722f8cc9f08266d7d77..19fabe9f8352884d447bbd11b1ae32cfc2951395 100644 (file)
--- 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 ec09c61dfd31aea43655a435fa516838ff64a2f0..a2c10c1bb341945e3b246e7ba956f901fa9b4e36 100644 (file)
--- 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.