From: Mike Bayer Date: Sat, 19 Nov 2022 18:10:31 +0000 (-0500) Subject: clarify role of `__allow_unmapped__` X-Git-Tag: rel_2_0_0b4~48 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=46e6693cb3db445f18aa25d5e4ca613504bd12b3;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git 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 ab481f5d91..61a527464e 100644 --- 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 ` 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 a2def39f18..97b4e93a0f 100644 --- 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^