Highlite composide mode that's more type checker friently

Change-Id: I9c7d79f31ab5e7a7f63aca4ba42c93f346acdefe
References: #11232
(cherry picked from commit 585a582db0c3a3271659bd48e13abe42eb67ac13)

diff --git a/doc/build/changelog/changelog_20.rst b/doc/build/changelog/changelog_20.rst
index 7678463b438b66516d2f2d7d47b66cf1d8c2971d..973a480fe233633246c3fbb857d528f99a712216 100644 (file)
--- a/doc/build/changelog/changelog_20.rst
+++ b/doc/build/changelog/changelog_20.rst
@@ -126,7 +126,7 @@
         :ref:`change_6980` failed to accommodate for the ``.copy()`` method, which
         will lose the variant mappings that are set up. This becomes an issue for
         the very specific case of a "schema" type, which includes types such as
-        :class:`.Enum` and :class:`.ARRAY`, when they are then used in the context
+        :class:`.Enum` and :class:`_types.ARRAY`, when they are then used in the context
         of an ORM Declarative mapping with mixins where copying of types comes into
         play.  The variant mapping is now copied as well.
 

diff --git a/doc/build/orm/composites.rst b/doc/build/orm/composites.rst
index b0ddb9ea4888057ed55abdef0f953517cc2187ac..2fc62cbfd01588a8ca0ef08c743db100b410ce99 100644 (file)
--- a/doc/build/orm/composites.rst
+++ b/doc/build/orm/composites.rst
@@ -63,6 +63,12 @@ of the columns to be generated, in this case the names; the
         def __repr__(self):
             return f"Vertex(start={self.start}, end={self.end})"
 
+.. tip:: In the example above the columns that represent the composites
+    (``x1``, ``y1``, etc.) are also accessible on the class but are not
+    correctly understood by type checkers.
+    If accessing the single columns is important they can be explicitly declared,
+    as shown in :ref:`composite_with_typing`.
+
 The above mapping would correspond to a CREATE TABLE statement as:
 
 .. sourcecode:: pycon+sql
@@ -184,12 +190,13 @@ using a :func:`_orm.mapped_column` construct, a :class:`_schema.Column`,
 or the string name of an existing mapped column.   The following examples
 illustrate an equivalent mapping as that of the main section above.
 
-* Map columns directly, then pass to composite
+Map columns directly, then pass to composite
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-  Here we pass the existing :func:`_orm.mapped_column` instances to the
-  :func:`_orm.composite` construct, as in the non-annotated example below
-  where we also pass the ``Point`` class as the first argument to
-  :func:`_orm.composite`::
+Here we pass the existing :func:`_orm.mapped_column` instances to the
+:func:`_orm.composite` construct, as in the non-annotated example below
+where we also pass the ``Point`` class as the first argument to
+:func:`_orm.composite`::
 
     from sqlalchemy import Integer
     from sqlalchemy.orm import mapped_column, composite
@@ -207,11 +214,14 @@ illustrate an equivalent mapping as that of the main section above.
         start = composite(Point, x1, y1)
         end = composite(Point, x2, y2)
 
-* Map columns directly, pass attribute names to composite
+.. _composite_with_typing:
+
+Map columns directly, pass attribute names to composite
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-  We can write the same example above using more annotated forms where we have
-  the option to pass attribute names to :func:`_orm.composite` instead of
-  full column constructs::
+We can write the same example above using more annotated forms where we have
+the option to pass attribute names to :func:`_orm.composite` instead of
+full column constructs::
 
     from sqlalchemy.orm import mapped_column, composite, Mapped
 
@@ -228,12 +238,13 @@ illustrate an equivalent mapping as that of the main section above.
         start: Mapped[Point] = composite("x1", "y1")
         end: Mapped[Point] = composite("x2", "y2")
 
-* Imperative mapping and imperative table
+Imperative mapping and imperative table
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-  When using :ref:`imperative table <orm_imperative_table_configuration>` or
-  fully :ref:`imperative <orm_imperative_mapping>` mappings, we have access
-  to :class:`_schema.Column` objects directly.  These may be passed to
-  :func:`_orm.composite` as well, as in the imperative example below::
+When using :ref:`imperative table <orm_imperative_table_configuration>` or
+fully :ref:`imperative <orm_imperative_mapping>` mappings, we have access
+to :class:`_schema.Column` objects directly.  These may be passed to
+:func:`_orm.composite` as well, as in the imperative example below::
 
      mapper_registry.map_imperatively(
          Vertex,