From: Mike Bayer Date: Sun, 3 Apr 2022 14:39:19 +0000 (-0400) Subject: clarify alternative mapping example X-Git-Tag: rel_2_0_0b1~379 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1dffb7cedeb009ca6c532db558bd0588dd846957;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git clarify alternative mapping example this second example is not part of the doctest steps, clarify that it's not part of code examples to be present in execution steps. Add an extra registry + declarative base on top so that even if someone does run it, the Base will have been reset and the examples will continue to work (noting that column order in statements may change, but probably nothing else). Fixes: #7891 Change-Id: Icb1ba310230841e502185d9d0cadd3c18d467292 --- diff --git a/doc/build/tutorial/metadata.rst b/doc/build/tutorial/metadata.rst index afaf9d6100..6444ed692e 100644 --- a/doc/build/tutorial/metadata.rst +++ b/doc/build/tutorial/metadata.rst @@ -443,6 +443,9 @@ This form is called :ref:`hybrid table `, and it consists of assigning to the ``.__table__`` attribute directly, rather than having the declarative process generate it:: + mapper_registry = registry() + Base = mapper_registry.generate_base() + class User(Base): __table__ = user_table @@ -459,6 +462,15 @@ than having the declarative process generate it:: def __repr__(self): return f"Address({self.email_address!r})" +.. note:: The above example is an **alternative form** to the mapping that's + first illustrated previously at :ref:`tutorial_declaring_mapped_classes`. + This example is for illustrative purposes only, and is not part of this + tutorial's "doctest" steps, and as such does not need to be run for readers + who are executing code examples. The mapping here and the one at + :ref:`tutorial_declaring_mapped_classes` produce equivalent mappings, but in + general one would use only **one** of these two forms for particular mapped + class. + The above two classes are equivalent to those which we declared in the previous mapping example.