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 844628443a659cf96050b661cd72f645ca07962d..ecd81c7ed50be1bd7c2f3e322f21805bd0fef1b4 100644 (file)
--- 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 9c2c9acf1e5f8cb5f06f2c4dbd90ae9a6f34e053..141b5c27a4c519c4f15e46d0e1d99faaa8b8a1a9 100644 (file)
--- 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