From 0dc731c331c1324d3264223987eb4ca62575a030 Mon Sep 17 00:00:00 2001 From: Federico Caselli Date: Thu, 4 Apr 2024 20:56:39 +0200 Subject: [PATCH] Highlite composide mode that's more type checker friently Change-Id: I9c7d79f31ab5e7a7f63aca4ba42c93f346acdefe References: #11232 (cherry picked from commit 585a582db0c3a3271659bd48e13abe42eb67ac13) --- doc/build/changelog/changelog_20.rst | 2 +- doc/build/orm/composites.rst | 39 ++++++++++++++++++---------- 2 files changed, 26 insertions(+), 15 deletions(-) diff --git a/doc/build/changelog/changelog_20.rst b/doc/build/changelog/changelog_20.rst index 7678463b43..973a480fe2 100644 --- 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 b0ddb9ea48..2fc62cbfd0 100644 --- 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 ` or - fully :ref:`imperative ` 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 ` or +fully :ref:`imperative ` 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, -- 2.47.2