clarify role of `__allow_unmapped__`

A different note will be needed in the 1.4 version
of these docs.

Fixes: #8845
Change-Id: I48651c64d511684077c80a317349dd230424b575

diff --git a/doc/build/changelog/migration_20.rst b/doc/build/changelog/migration_20.rst
index ab481f5d912c17ee1031b0edcf0499548ba8f814..61a527464e514e8786446b403aea2c56592a2f68 100644 (file)
--- a/doc/build/changelog/migration_20.rst
+++ b/doc/build/changelog/migration_20.rst
@@ -453,7 +453,7 @@ SQLAlchemy 2.0 has new support for runtime interpretation of :pep:`484` typing a
 on ORM models.   A requirement of these annotations is that they must make use
 of the :class:`_orm.Mapped` generic container.  Annotations which don't use
 :class:`_orm.Mapped` which link to constructs such as :func:`_orm.relationship`
-will raise errors, as they suggest mis-configurations.
+will raise errors in Python, as they suggest mis-configurations.
 
 SQLAlchemy applications that use the :ref:`Mypy plugin <mypy_toplevel>` with
 explicit annotations that don't use :class:`_orm.Mapped` in their annotations
@@ -490,6 +490,13 @@ the ``__allow_unmapped__`` attribute may be used on the class or any
 subclasses, which will cause the annotations in these cases to be
 ignored completely by the new Declarative system.
 
+.. note:: The ``__allow_unmapped__`` directive applies **only** to the
+   *runtime* behavior of the ORM.  It does not affect the behavior of
+   Mypy, and the above mapping as written still requires that the Mypy
+   plugin be installed.   For fully 2.0 style ORM models that will type
+   correctly under Mypy *without* a plugin, follow the migration steps
+   at :ref:`whatsnew_20_orm_typing_migration`.
+
 The example below illustrates the application of ``__allow_unmapped__``
 to the Declarative ``Base`` class, where it will take effect for all classes
 that descend from ``Base``::

diff --git a/doc/build/changelog/whatsnew_20.rst b/doc/build/changelog/whatsnew_20.rst
index a2def39f1856e33f4e75a1afbd77f0a663d7478d..97b4e93a0f71fe3b6345b839f2ef0690c2bf1a74 100644 (file)
--- a/doc/build/changelog/whatsnew_20.rst
+++ b/doc/build/changelog/whatsnew_20.rst
@@ -408,6 +408,8 @@ as-needed, per-attribute basis for those attributes where specific types are
 helpful; non-annotated attributes that use :func:`_orm.mapped_column` will be
 typed as ``Any`` at the instance level.
 
+.. _whatsnew_20_orm_typing_migration:
+
 Migrating an Existing Mapping
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^