clarify role of `__allow_unmapped__`

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

Fixes: #8845
Change-Id: I48651c64d511684077c80a317349dd230424b575
(cherry picked from commit 46e6693cb3db445f18aa25d5e4ca613504bd12b3)

diff --git a/doc/build/changelog/migration_20.rst b/doc/build/changelog/migration_20.rst
index b33a5b0e67682291932eed3ef910092543c0b9e2..f7009a28d579b8fef668a6c3ef42c5f5c154c5e6 100644 (file)
--- a/doc/build/changelog/migration_20.rst
+++ b/doc/build/changelog/migration_20.rst
@@ -387,7 +387,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
@@ -424,6 +424,15 @@ 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, see the section named
+   "Migrating an Existing Mapping" in the "What's New in SQLAlchemy 2.0?"
+   document of the SQLAlchemy 2.0 documentation; this is the SQLAlchemy
+   1.4 documentation.
+
 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``::