From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Fri, 20 Jan 2023 18:34:07 +0000 (-0500)
Subject: clarify __table__, local_table
X-Git-Tag: rel_2_0_0~22
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2f91dd79310657814ad28b6ef64f91fff7a007c9;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

clarify __table__, local_table

These are typed as FromClause, make sure this is stated up front
indicating Table as a subset of possible object types.

Change-Id: I15961a69d3655600249e3cfe6c4b3372f97d4485
References: #9130
---

diff --git a/lib/sqlalchemy/orm/decl_api.py b/lib/sqlalchemy/orm/decl_api.py
index 844628443a..ecd81c7ed5 100644
--- a/lib/sqlalchemy/orm/decl_api.py
+++ b/lib/sqlalchemy/orm/decl_api.py
@@ -709,9 +709,13 @@ class DeclarativeBase(
         """
 
         __table__: ClassVar[FromClause]
-        """The :class:`_schema.Table` to which a particular subclass is
+        """The :class:`_sql.FromClause` to which a particular subclass is
         mapped.
 
+        This is usually an instance of :class:`_schema.Table` but may also
+        refer to other kinds of :class:`_sql.FromClause` such as
+        :class:`_sql.Subquery`, depending on how the class is mapped.
+
         .. seealso::
 
             :ref:`orm_declarative_metadata`
@@ -818,9 +822,13 @@ class DeclarativeBaseNoMeta(inspection.Inspectable[Mapper[Any]]):
     """
 
     __table__: Optional[FromClause]
-    """The :class:`_schema.Table` to which a particular subclass is
+    """The :class:`_sql.FromClause` to which a particular subclass is
     mapped.
 
+    This is usually an instance of :class:`_schema.Table` but may also
+    refer to other kinds of :class:`_sql.FromClause` such as
+    :class:`_sql.Subquery`, depending on how the class is mapped.
+
     .. seealso::
 
         :ref:`orm_declarative_metadata`
diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py
index 9c2c9acf1e..141b5c27a4 100644
--- a/lib/sqlalchemy/orm/mapper.py
+++ b/lib/sqlalchemy/orm/mapper.py
@@ -257,15 +257,15 @@ class Mapper(
           this argument is automatically passed as the declared class
           itself.
 
-        :param local_table: The :class:`_schema.Table` or other selectable
-           to which the class is mapped.  May be ``None`` if
-           this mapper inherits from another mapper using single-table
-           inheritance.   When using Declarative, this argument is
-           automatically passed by the extension, based on what
-           is configured via the ``__table__`` argument or via the
-           :class:`_schema.Table`
-           produced as a result of the ``__tablename__``
-           and :class:`_schema.Column` arguments present.
+        :param local_table: The :class:`_schema.Table` or other
+           :class:`_sql.FromClause` (i.e. selectable) to which the class is
+           mapped. May be ``None`` if this mapper inherits from another mapper
+           using single-table inheritance. When using Declarative, this
+           argument is automatically passed by the extension, based on what is
+           configured via the :attr:`_orm.DeclarativeBase.__table__` attribute
+           or via the :class:`_schema.Table` produced as a result of
+           the :attr:`_orm.DeclarativeBase.__tablename__` attribute being
+           present.
 
         :param polymorphic_abstract: Indicates this class will be mapped in a
             polymorphic hierarchy, but not directly instantiated. The class is