establish mypy / typing approach for v2.0

large patch to get ORM / typing efforts started.
this is to support adding new test cases to mypy,
support dropping sqlalchemy2-stubs entirely from the
test suite, validate major ORM typing reorganization
to eliminate the need for the mypy plugin.

* New declarative approach which uses annotation
  introspection, fixes: #7535
* Mapped[] is now at the base of all ORM constructs
  that find themselves in classes, to support direct
  typing without plugins
* Mypy plugin updated for new typing structures
* Mypy test suite broken out into "plugin" tests vs.
  "plain" tests, and enhanced to better support test
  structures where we assert that various objects are
  introspected by the type checker as we expect.
  as we go forward with typing, we will
  add new use cases to "plain" where we can assert that
  types are introspected as we expect.
* For typing support, users will be much more exposed to the
  class names of things.  Add these all to "sqlalchemy" import
  space.
* Column(ForeignKey()) no longer needs to be `@declared_attr`
  if the FK refers to a remote table
* composite() attributes mapped to a dataclass no longer
  need to implement a `__composite_values__()` method
* with_variant() accepts multiple dialect names

Change-Id: I22797c0be73a8fbbd2d6f5e0c0b7258b17fe145d
Fixes: #7535
Fixes: #7551
References: #6810

1 files changed, 390 insertions, 354 deletions

diff --git a/lib/sqlalchemy/sql/schema.py b/lib/sqlalchemy/sql/schema.py
index a04fad05d..9387ae030 100644
--- a/lib/sqlalchemy/sql/schema.py
+++ b/lib/sqlalchemy/sql/schema.py
@@ -31,9 +31,12 @@ as components in SQL expressions.
 import collections
 import typing
 from typing import Any
+from typing import Dict
+from typing import List
 from typing import MutableMapping
 from typing import Optional
 from typing import overload
+from typing import Sequence as _typing_Sequence
 from typing import Type
 from typing import TypeVar
 from typing import Union
@@ -52,6 +55,7 @@ from .elements import ClauseElement
 from .elements import ColumnClause
 from .elements import ColumnElement
 from .elements import quoted_name
+from .elements import SQLCoreOperations
 from .elements import TextClause
 from .selectable import TableClause
 from .type_api import to_instance
@@ -64,9 +68,12 @@ from ..util.typing import Literal
 
 if typing.TYPE_CHECKING:
     from .type_api import TypeEngine
+    from ..engine import Connection
+    from ..engine import Engine
 
 _T = TypeVar("_T", bound="Any")
 _ServerDefaultType = Union["FetchedValue", str, TextClause, ColumnElement]
+_TAB = TypeVar("_TAB", bound="Table")
 
 RETAIN_SCHEMA = util.symbol("retain_schema")
 
@@ -188,313 +195,6 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
 
         :ref:`metadata_describing` - Introduction to database metadata
 
-    Constructor arguments are as follows:
-
-    :param name: The name of this table as represented in the database.
-
-        The table name, along with the value of the ``schema`` parameter,
-        forms a key which uniquely identifies this :class:`_schema.Table`
-        within
-        the owning :class:`_schema.MetaData` collection.
-        Additional calls to :class:`_schema.Table` with the same name,
-        metadata,
-        and schema name will return the same :class:`_schema.Table` object.
-
-        Names which contain no upper case characters
-        will be treated as case insensitive names, and will not be quoted
-        unless they are a reserved word or contain special characters.
-        A name with any number of upper case characters is considered
-        to be case sensitive, and will be sent as quoted.
-
-        To enable unconditional quoting for the table name, specify the flag
-        ``quote=True`` to the constructor, or use the :class:`.quoted_name`
-        construct to specify the name.
-
-    :param metadata: a :class:`_schema.MetaData`
-        object which will contain this
-        table.  The metadata is used as a point of association of this table
-        with other tables which are referenced via foreign key.  It also
-        may be used to associate this table with a particular
-        :class:`.Connection` or :class:`.Engine`.
-
-    :param \*args: Additional positional arguments are used primarily
-        to add the list of :class:`_schema.Column`
-        objects contained within this
-        table. Similar to the style of a CREATE TABLE statement, other
-        :class:`.SchemaItem` constructs may be added here, including
-        :class:`.PrimaryKeyConstraint`, and
-        :class:`_schema.ForeignKeyConstraint`.
-
-    :param autoload: Defaults to ``False``, unless
-        :paramref:`_schema.Table.autoload_with`
-        is set in which case it defaults to ``True``;
-        :class:`_schema.Column` objects
-        for this table should be reflected from the database, possibly
-        augmenting objects that were explicitly specified.
-        :class:`_schema.Column` and other objects explicitly set on the
-        table will replace corresponding reflected objects.
-
-        .. deprecated:: 1.4
-
-            The autoload parameter is deprecated and will be removed in
-            version 2.0.  Please use the
-            :paramref:`_schema.Table.autoload_with` parameter, passing an
-            engine or connection.
-
-        .. seealso::
-
-            :ref:`metadata_reflection_toplevel`
-
-    :param autoload_replace: Defaults to ``True``; when using
-        :paramref:`_schema.Table.autoload`
-        in conjunction with :paramref:`_schema.Table.extend_existing`,
-        indicates
-        that :class:`_schema.Column` objects present in the already-existing
-        :class:`_schema.Table`
-        object should be replaced with columns of the same
-        name retrieved from the autoload process.   When ``False``, columns
-        already present under existing names will be omitted from the
-        reflection process.
-
-        Note that this setting does not impact :class:`_schema.Column` objects
-        specified programmatically within the call to :class:`_schema.Table`
-        that
-        also is autoloading; those :class:`_schema.Column` objects will always
-        replace existing columns of the same name when
-        :paramref:`_schema.Table.extend_existing` is ``True``.
-
-        .. seealso::
-
-            :paramref:`_schema.Table.autoload`
-
-            :paramref:`_schema.Table.extend_existing`
-
-    :param autoload_with: An :class:`_engine.Engine` or
-        :class:`_engine.Connection` object,
-        or a :class:`_reflection.Inspector` object as returned by
-        :func:`_sa.inspect`
-        against one, with which this :class:`_schema.Table`
-        object will be reflected.
-        When set to a non-None value, the autoload process will take place
-        for this table against the given engine or connection.
-
-    :param extend_existing: When ``True``, indicates that if this
-        :class:`_schema.Table` is already present in the given
-        :class:`_schema.MetaData`,
-        apply further arguments within the constructor to the existing
-        :class:`_schema.Table`.
-
-        If :paramref:`_schema.Table.extend_existing` or
-        :paramref:`_schema.Table.keep_existing` are not set,
-        and the given name
-        of the new :class:`_schema.Table` refers to a :class:`_schema.Table`
-        that is
-        already present in the target :class:`_schema.MetaData` collection,
-        and
-        this :class:`_schema.Table`
-        specifies additional columns or other constructs
-        or flags that modify the table's state, an
-        error is raised.  The purpose of these two mutually-exclusive flags
-        is to specify what action should be taken when a
-        :class:`_schema.Table`
-        is specified that matches an existing :class:`_schema.Table`,
-        yet specifies
-        additional constructs.
-
-        :paramref:`_schema.Table.extend_existing`
-        will also work in conjunction
-        with :paramref:`_schema.Table.autoload` to run a new reflection
-        operation against the database, even if a :class:`_schema.Table`
-        of the same name is already present in the target
-        :class:`_schema.MetaData`; newly reflected :class:`_schema.Column`
-        objects
-        and other options will be added into the state of the
-        :class:`_schema.Table`, potentially overwriting existing columns
-        and options of the same name.
-
-        As is always the case with :paramref:`_schema.Table.autoload`,
-        :class:`_schema.Column` objects can be specified in the same
-        :class:`_schema.Table`
-        constructor, which will take precedence.  Below, the existing
-        table ``mytable`` will be augmented with :class:`_schema.Column`
-        objects
-        both reflected from the database, as well as the given
-        :class:`_schema.Column`
-        named "y"::
-
-            Table("mytable", metadata,
-                        Column('y', Integer),
-                        extend_existing=True,
-                        autoload_with=engine
-                    )
-
-        .. seealso::
-
-            :paramref:`_schema.Table.autoload`
-
-            :paramref:`_schema.Table.autoload_replace`
-
-            :paramref:`_schema.Table.keep_existing`
-
-
-    :param implicit_returning: True by default - indicates that
-        RETURNING can be used by default to fetch newly inserted primary key
-        values, for backends which support this.  Note that
-        :func:`_sa.create_engine` also provides an ``implicit_returning``
-        flag.
-
-    :param include_columns: A list of strings indicating a subset of
-        columns to be loaded via the ``autoload`` operation; table columns who
-        aren't present in this list will not be represented on the resulting
-        ``Table`` object. Defaults to ``None`` which indicates all columns
-        should be reflected.
-
-    :param resolve_fks: Whether or not to reflect :class:`_schema.Table`
-        objects
-        related to this one via :class:`_schema.ForeignKey` objects, when
-        :paramref:`_schema.Table.autoload` or
-        :paramref:`_schema.Table.autoload_with` is
-        specified.   Defaults to True.  Set to False to disable reflection of
-        related tables as :class:`_schema.ForeignKey`
-        objects are encountered; may be
-        used either to save on SQL calls or to avoid issues with related tables
-        that can't be accessed. Note that if a related table is already present
-        in the :class:`_schema.MetaData` collection, or becomes present later,
-        a
-        :class:`_schema.ForeignKey` object associated with this
-        :class:`_schema.Table` will
-        resolve to that table normally.
-
-        .. versionadded:: 1.3
-
-        .. seealso::
-
-            :paramref:`.MetaData.reflect.resolve_fks`
-
-
-    :param info: Optional data dictionary which will be populated into the
-        :attr:`.SchemaItem.info` attribute of this object.
-
-    :param keep_existing: When ``True``, indicates that if this Table
-        is already present in the given :class:`_schema.MetaData`, ignore
-        further arguments within the constructor to the existing
-        :class:`_schema.Table`, and return the :class:`_schema.Table`
-        object as
-        originally created. This is to allow a function that wishes
-        to define a new :class:`_schema.Table` on first call, but on
-        subsequent calls will return the same :class:`_schema.Table`,
-        without any of the declarations (particularly constraints)
-        being applied a second time.
-
-        If :paramref:`_schema.Table.extend_existing` or
-        :paramref:`_schema.Table.keep_existing` are not set,
-        and the given name
-        of the new :class:`_schema.Table` refers to a :class:`_schema.Table`
-        that is
-        already present in the target :class:`_schema.MetaData` collection,
-        and
-        this :class:`_schema.Table`
-        specifies additional columns or other constructs
-        or flags that modify the table's state, an
-        error is raised.  The purpose of these two mutually-exclusive flags
-        is to specify what action should be taken when a
-        :class:`_schema.Table`
-        is specified that matches an existing :class:`_schema.Table`,
-        yet specifies
-        additional constructs.
-
-        .. seealso::
-
-            :paramref:`_schema.Table.extend_existing`
-
-    :param listeners: A list of tuples of the form ``(<eventname>, <fn>)``
-        which will be passed to :func:`.event.listen` upon construction.
-        This alternate hook to :func:`.event.listen` allows the establishment
-        of a listener function specific to this :class:`_schema.Table` before
-        the "autoload" process begins.  Historically this has been intended
-        for use with the :meth:`.DDLEvents.column_reflect` event, however
-        note that this event hook may now be associated with the
-        :class:`_schema.MetaData` object directly::
-
-            def listen_for_reflect(table, column_info):
-                "handle the column reflection event"
-                # ...
-
-            t = Table(
-                'sometable',
-                autoload_with=engine,
-                listeners=[
-                    ('column_reflect', listen_for_reflect)
-                ])
-
-        .. seealso::
-
-            :meth:`_events.DDLEvents.column_reflect`
-
-    :param must_exist: When ``True``, indicates that this Table must already
-        be present in the given :class:`_schema.MetaData` collection, else
-        an exception is raised.
-
-    :param prefixes:
-        A list of strings to insert after CREATE in the CREATE TABLE
-        statement.  They will be separated by spaces.
-
-    :param quote: Force quoting of this table's name on or off, corresponding
-        to ``True`` or ``False``.  When left at its default of ``None``,
-        the column identifier will be quoted according to whether the name is
-        case sensitive (identifiers with at least one upper case character are
-        treated as case sensitive), or if it's a reserved word.  This flag
-        is only needed to force quoting of a reserved word which is not known
-        by the SQLAlchemy dialect.
-
-        .. note:: setting this flag to ``False`` will not provide
-           case-insensitive behavior for table reflection; table reflection
-           will always search for a mixed-case name in a case sensitive
-           fashion.  Case insensitive names are specified in SQLAlchemy only
-           by stating the name with all lower case characters.
-
-    :param quote_schema: same as 'quote' but applies to the schema identifier.
-
-    :param schema: The schema name for this table, which is required if
-        the table resides in a schema other than the default selected schema
-        for the engine's database connection.  Defaults to ``None``.
-
-        If the owning :class:`_schema.MetaData` of this :class:`_schema.Table`
-        specifies its
-        own :paramref:`_schema.MetaData.schema` parameter,
-        then that schema name will
-        be applied to this :class:`_schema.Table`
-        if the schema parameter here is set
-        to ``None``.  To set a blank schema name on a :class:`_schema.Table`
-        that
-        would otherwise use the schema set on the owning
-        :class:`_schema.MetaData`,
-        specify the special symbol :attr:`.BLANK_SCHEMA`.
-
-        .. versionadded:: 1.0.14  Added the :attr:`.BLANK_SCHEMA` symbol to
-           allow a :class:`_schema.Table`
-           to have a blank schema name even when the
-           parent :class:`_schema.MetaData` specifies
-           :paramref:`_schema.MetaData.schema`.
-
-        The quoting rules for the schema name are the same as those for the
-        ``name`` parameter, in that quoting is applied for reserved words or
-        case-sensitive names; to enable unconditional quoting for the schema
-        name, specify the flag ``quote_schema=True`` to the constructor, or use
-        the :class:`.quoted_name` construct to specify the name.
-
-    :param comment: Optional string that will render an SQL comment on table
-         creation.
-
-         .. versionadded:: 1.2 Added the :paramref:`_schema.Table.comment`
-            parameter
-            to :class:`_schema.Table`.
-
-    :param \**kw: Additional keyword arguments not mentioned above are
-        dialect specific, and passed in the form ``<dialectname>_<argname>``.
-        See the documentation regarding an individual dialect at
-        :ref:`dialect_toplevel` for detail on documented arguments.
-
     """
 
     __visit_name__ = "table"
@@ -547,13 +247,21 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
         else:
             return (self,)
 
-    @util.deprecated_params(
-        mustexist=(
-            "1.4",
-            "Deprecated alias of :paramref:`_schema.Table.must_exist`",
-        ),
-    )
-    def __new__(cls, *args, **kw):
+    if not typing.TYPE_CHECKING:
+        # typing tools seem to be inconsistent in how they handle
+        # __new__, so suggest this pattern for classes that use
+        # __new__.  apply typing to the __init__ method normally
+        @util.deprecated_params(
+            mustexist=(
+                "1.4",
+                "Deprecated alias of :paramref:`_schema.Table.must_exist`",
+            ),
+        )
+        def __new__(cls, *args: Any, **kw: Any) -> Any:
+            return cls._new(*args, **kw)
+
+    @classmethod
+    def _new(cls, *args, **kw):
         if not args and not kw:
             # python3k pickle seems to call this
             return object.__new__(cls)
@@ -607,14 +315,323 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
                 with util.safe_reraise():
                     metadata._remove_table(name, schema)
 
-    def __init__(self, *args, **kw):
-        """Constructor for :class:`_schema.Table`.
+    def __init__(
+        self,
+        name: str,
+        metadata: "MetaData",
+        *args: SchemaItem,
+        **kw: Any,
+    ):
+        r"""Constructor for :class:`_schema.Table`.
 
-        This method is a no-op.   See the top-level
-        documentation for :class:`_schema.Table`
-        for constructor arguments.
 
-        """
+        :param name: The name of this table as represented in the database.
+
+            The table name, along with the value of the ``schema`` parameter,
+            forms a key which uniquely identifies this :class:`_schema.Table`
+            within
+            the owning :class:`_schema.MetaData` collection.
+            Additional calls to :class:`_schema.Table` with the same name,
+            metadata,
+            and schema name will return the same :class:`_schema.Table` object.
+
+            Names which contain no upper case characters
+            will be treated as case insensitive names, and will not be quoted
+            unless they are a reserved word or contain special characters.
+            A name with any number of upper case characters is considered
+            to be case sensitive, and will be sent as quoted.
+
+            To enable unconditional quoting for the table name, specify the flag
+            ``quote=True`` to the constructor, or use the :class:`.quoted_name`
+            construct to specify the name.
+
+        :param metadata: a :class:`_schema.MetaData`
+            object which will contain this
+            table.  The metadata is used as a point of association of this table
+            with other tables which are referenced via foreign key.  It also
+            may be used to associate this table with a particular
+            :class:`.Connection` or :class:`.Engine`.
+
+        :param \*args: Additional positional arguments are used primarily
+            to add the list of :class:`_schema.Column`
+            objects contained within this
+            table. Similar to the style of a CREATE TABLE statement, other
+            :class:`.SchemaItem` constructs may be added here, including
+            :class:`.PrimaryKeyConstraint`, and
+            :class:`_schema.ForeignKeyConstraint`.
+
+        :param autoload: Defaults to ``False``, unless
+            :paramref:`_schema.Table.autoload_with`
+            is set in which case it defaults to ``True``;
+            :class:`_schema.Column` objects
+            for this table should be reflected from the database, possibly
+            augmenting objects that were explicitly specified.
+            :class:`_schema.Column` and other objects explicitly set on the
+            table will replace corresponding reflected objects.
+
+            .. deprecated:: 1.4
+
+                The autoload parameter is deprecated and will be removed in
+                version 2.0.  Please use the
+                :paramref:`_schema.Table.autoload_with` parameter, passing an
+                engine or connection.
+
+            .. seealso::
+
+                :ref:`metadata_reflection_toplevel`
+
+        :param autoload_replace: Defaults to ``True``; when using
+            :paramref:`_schema.Table.autoload`
+            in conjunction with :paramref:`_schema.Table.extend_existing`,
+            indicates
+            that :class:`_schema.Column` objects present in the already-existing
+            :class:`_schema.Table`
+            object should be replaced with columns of the same
+            name retrieved from the autoload process.   When ``False``, columns
+            already present under existing names will be omitted from the
+            reflection process.
+
+            Note that this setting does not impact :class:`_schema.Column` objects
+            specified programmatically within the call to :class:`_schema.Table`
+            that
+            also is autoloading; those :class:`_schema.Column` objects will always
+            replace existing columns of the same name when
+            :paramref:`_schema.Table.extend_existing` is ``True``.
+
+            .. seealso::
+
+                :paramref:`_schema.Table.autoload`
+
+                :paramref:`_schema.Table.extend_existing`
+
+        :param autoload_with: An :class:`_engine.Engine` or
+            :class:`_engine.Connection` object,
+            or a :class:`_reflection.Inspector` object as returned by
+            :func:`_sa.inspect`
+            against one, with which this :class:`_schema.Table`
+            object will be reflected.
+            When set to a non-None value, the autoload process will take place
+            for this table against the given engine or connection.
+
+        :param extend_existing: When ``True``, indicates that if this
+            :class:`_schema.Table` is already present in the given
+            :class:`_schema.MetaData`,
+            apply further arguments within the constructor to the existing
+            :class:`_schema.Table`.
+
+            If :paramref:`_schema.Table.extend_existing` or
+            :paramref:`_schema.Table.keep_existing` are not set,
+            and the given name
+            of the new :class:`_schema.Table` refers to a :class:`_schema.Table`
+            that is
+            already present in the target :class:`_schema.MetaData` collection,
+            and
+            this :class:`_schema.Table`
+            specifies additional columns or other constructs
+            or flags that modify the table's state, an
+            error is raised.  The purpose of these two mutually-exclusive flags
+            is to specify what action should be taken when a
+            :class:`_schema.Table`
+            is specified that matches an existing :class:`_schema.Table`,
+            yet specifies
+            additional constructs.
+
+            :paramref:`_schema.Table.extend_existing`
+            will also work in conjunction
+            with :paramref:`_schema.Table.autoload` to run a new reflection
+            operation against the database, even if a :class:`_schema.Table`
+            of the same name is already present in the target
+            :class:`_schema.MetaData`; newly reflected :class:`_schema.Column`
+            objects
+            and other options will be added into the state of the
+            :class:`_schema.Table`, potentially overwriting existing columns
+            and options of the same name.
+
+            As is always the case with :paramref:`_schema.Table.autoload`,
+            :class:`_schema.Column` objects can be specified in the same
+            :class:`_schema.Table`
+            constructor, which will take precedence.  Below, the existing
+            table ``mytable`` will be augmented with :class:`_schema.Column`
+            objects
+            both reflected from the database, as well as the given
+            :class:`_schema.Column`
+            named "y"::
+
+                Table("mytable", metadata,
+                            Column('y', Integer),
+                            extend_existing=True,
+                            autoload_with=engine
+                        )
+
+            .. seealso::
+
+                :paramref:`_schema.Table.autoload`
+
+                :paramref:`_schema.Table.autoload_replace`
+
+                :paramref:`_schema.Table.keep_existing`
+
+
+        :param implicit_returning: True by default - indicates that
+            RETURNING can be used by default to fetch newly inserted primary key
+            values, for backends which support this.  Note that
+            :func:`_sa.create_engine` also provides an ``implicit_returning``
+            flag.
+
+        :param include_columns: A list of strings indicating a subset of
+            columns to be loaded via the ``autoload`` operation; table columns who
+            aren't present in this list will not be represented on the resulting
+            ``Table`` object. Defaults to ``None`` which indicates all columns
+            should be reflected.
+
+        :param resolve_fks: Whether or not to reflect :class:`_schema.Table`
+            objects
+            related to this one via :class:`_schema.ForeignKey` objects, when
+            :paramref:`_schema.Table.autoload` or
+            :paramref:`_schema.Table.autoload_with` is
+            specified.   Defaults to True.  Set to False to disable reflection of
+            related tables as :class:`_schema.ForeignKey`
+            objects are encountered; may be
+            used either to save on SQL calls or to avoid issues with related tables
+            that can't be accessed. Note that if a related table is already present
+            in the :class:`_schema.MetaData` collection, or becomes present later,
+            a
+            :class:`_schema.ForeignKey` object associated with this
+            :class:`_schema.Table` will
+            resolve to that table normally.
+
+            .. versionadded:: 1.3
+
+            .. seealso::
+
+                :paramref:`.MetaData.reflect.resolve_fks`
+
+
+        :param info: Optional data dictionary which will be populated into the
+            :attr:`.SchemaItem.info` attribute of this object.
+
+        :param keep_existing: When ``True``, indicates that if this Table
+            is already present in the given :class:`_schema.MetaData`, ignore
+            further arguments within the constructor to the existing
+            :class:`_schema.Table`, and return the :class:`_schema.Table`
+            object as
+            originally created. This is to allow a function that wishes
+            to define a new :class:`_schema.Table` on first call, but on
+            subsequent calls will return the same :class:`_schema.Table`,
+            without any of the declarations (particularly constraints)
+            being applied a second time.
+
+            If :paramref:`_schema.Table.extend_existing` or
+            :paramref:`_schema.Table.keep_existing` are not set,
+            and the given name
+            of the new :class:`_schema.Table` refers to a :class:`_schema.Table`
+            that is
+            already present in the target :class:`_schema.MetaData` collection,
+            and
+            this :class:`_schema.Table`
+            specifies additional columns or other constructs
+            or flags that modify the table's state, an
+            error is raised.  The purpose of these two mutually-exclusive flags
+            is to specify what action should be taken when a
+            :class:`_schema.Table`
+            is specified that matches an existing :class:`_schema.Table`,
+            yet specifies
+            additional constructs.
+
+            .. seealso::
+
+                :paramref:`_schema.Table.extend_existing`
+
+        :param listeners: A list of tuples of the form ``(<eventname>, <fn>)``
+            which will be passed to :func:`.event.listen` upon construction.
+            This alternate hook to :func:`.event.listen` allows the establishment
+            of a listener function specific to this :class:`_schema.Table` before
+            the "autoload" process begins.  Historically this has been intended
+            for use with the :meth:`.DDLEvents.column_reflect` event, however
+            note that this event hook may now be associated with the
+            :class:`_schema.MetaData` object directly::
+
+                def listen_for_reflect(table, column_info):
+                    "handle the column reflection event"
+                    # ...
+
+                t = Table(
+                    'sometable',
+                    autoload_with=engine,
+                    listeners=[
+                        ('column_reflect', listen_for_reflect)
+                    ])
+
+            .. seealso::
+
+                :meth:`_events.DDLEvents.column_reflect`
+
+        :param must_exist: When ``True``, indicates that this Table must already
+            be present in the given :class:`_schema.MetaData` collection, else
+            an exception is raised.
+
+        :param prefixes:
+            A list of strings to insert after CREATE in the CREATE TABLE
+            statement.  They will be separated by spaces.
+
+        :param quote: Force quoting of this table's name on or off, corresponding
+            to ``True`` or ``False``.  When left at its default of ``None``,
+            the column identifier will be quoted according to whether the name is
+            case sensitive (identifiers with at least one upper case character are
+            treated as case sensitive), or if it's a reserved word.  This flag
+            is only needed to force quoting of a reserved word which is not known
+            by the SQLAlchemy dialect.
+
+            .. note:: setting this flag to ``False`` will not provide
+            case-insensitive behavior for table reflection; table reflection
+            will always search for a mixed-case name in a case sensitive
+            fashion.  Case insensitive names are specified in SQLAlchemy only
+            by stating the name with all lower case characters.
+
+        :param quote_schema: same as 'quote' but applies to the schema identifier.
+
+        :param schema: The schema name for this table, which is required if
+            the table resides in a schema other than the default selected schema
+            for the engine's database connection.  Defaults to ``None``.
+
+            If the owning :class:`_schema.MetaData` of this :class:`_schema.Table`
+            specifies its
+            own :paramref:`_schema.MetaData.schema` parameter,
+            then that schema name will
+            be applied to this :class:`_schema.Table`
+            if the schema parameter here is set
+            to ``None``.  To set a blank schema name on a :class:`_schema.Table`
+            that
+            would otherwise use the schema set on the owning
+            :class:`_schema.MetaData`,
+            specify the special symbol :attr:`.BLANK_SCHEMA`.
+
+            .. versionadded:: 1.0.14  Added the :attr:`.BLANK_SCHEMA` symbol to
+            allow a :class:`_schema.Table`
+            to have a blank schema name even when the
+            parent :class:`_schema.MetaData` specifies
+            :paramref:`_schema.MetaData.schema`.
+
+            The quoting rules for the schema name are the same as those for the
+            ``name`` parameter, in that quoting is applied for reserved words or
+            case-sensitive names; to enable unconditional quoting for the schema
+            name, specify the flag ``quote_schema=True`` to the constructor, or use
+            the :class:`.quoted_name` construct to specify the name.
+
+        :param comment: Optional string that will render an SQL comment on table
+            creation.
+
+            .. versionadded:: 1.2 Added the :paramref:`_schema.Table.comment`
+                parameter
+                to :class:`_schema.Table`.
+
+        :param \**kw: Additional keyword arguments not mentioned above are
+            dialect specific, and passed in the form ``<dialectname>_<argname>``.
+            See the documentation regarding an individual dialect at
+            :ref:`dialect_toplevel` for detail on documented arguments.
+
+        """  # noqa E501
+
         # __init__ is overridden to prevent __new__ from
         # calling the superclass constructor.
 
@@ -1203,7 +1220,7 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause[_T]):
     ) -> None:
         ...
 
-    def __init__(self, *args, **kwargs):
+    def __init__(self, *args: Any, **kwargs: Any):
         r"""
         Construct a new ``Column`` object.
 
@@ -2179,18 +2196,18 @@ class ForeignKey(DialectKWArgs, SchemaItem):
 
     def __init__(
         self,
-        column,
-        _constraint=None,
-        use_alter=False,
-        name=None,
-        onupdate=None,
-        ondelete=None,
-        deferrable=None,
-        initially=None,
-        link_to_name=False,
-        match=None,
-        info=None,
-        **dialect_kw,
+        column: Union[str, Column, SQLCoreOperations],
+        _constraint: Optional["ForeignKeyConstraint"] = None,
+        use_alter: bool = False,
+        name: Optional[str] = None,
+        onupdate: Optional[str] = None,
+        ondelete: Optional[str] = None,
+        deferrable: Optional[bool] = None,
+        initially: Optional[bool] = None,
+        link_to_name: bool = False,
+        match: Optional[str] = None,
+        info: Optional[Dict[Any, Any]] = None,
+        **dialect_kw: Any,
     ):
         r"""
         Construct a column-level FOREIGN KEY.
@@ -2337,7 +2354,7 @@ class ForeignKey(DialectKWArgs, SchemaItem):
         )
         return self._schema_item_copy(fk)
 
-    def _get_colspec(self, schema=None, table_name=None):
+    def _get_colspec(self, schema=None, table_name=None, _is_copy=False):
         """Return a string based 'column specification' for this
         :class:`_schema.ForeignKey`.
 
@@ -2357,6 +2374,14 @@ class ForeignKey(DialectKWArgs, SchemaItem):
             else:
                 return "%s.%s" % (table_name, colname)
         elif self._table_column is not None:
+            if self._table_column.table is None:
+                if _is_copy:
+                    raise exc.InvalidRequestError(
+                        f"Can't copy ForeignKey object which refers to "
+                        f"non-table bound Column {self._table_column!r}"
+                    )
+                else:
+                    return self._table_column.key
             return "%s.%s" % (
                 self._table_column.table.fullname,
                 self._table_column.key,
@@ -3858,6 +3883,7 @@ class ForeignKeyConstraint(ColumnCollectionConstraint):
                     if target_table is not None
                     and x._table_key() == x.parent.table.key
                     else None,
+                    _is_copy=True,
                 )
                 for x in self.elements
             ],
@@ -4331,10 +4357,10 @@ class MetaData(SchemaItem):
 
     def __init__(
         self,
-        schema=None,
-        quote_schema=None,
-        naming_convention=None,
-        info=None,
+        schema: Optional[str] = None,
+        quote_schema: Optional[bool] = None,
+        naming_convention: Optional[Dict[str, str]] = None,
+        info: Optional[Dict[Any, Any]] = None,
     ):
         """Create a new MetaData object.
 
@@ -4465,7 +4491,7 @@ class MetaData(SchemaItem):
         self._sequences = {}
         self._fk_memos = collections.defaultdict(list)
 
-    tables = None
+    tables: Dict[str, Table]
     """A dictionary of :class:`_schema.Table`
     objects keyed to their name or "table key".
 
@@ -4483,10 +4509,10 @@ class MetaData(SchemaItem):
 
     """
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return "MetaData()"
 
-    def __contains__(self, table_or_key):
+    def __contains__(self, table_or_key: Union[str, Table]) -> bool:
         if not isinstance(table_or_key, str):
             table_or_key = table_or_key.key
         return table_or_key in self.tables
@@ -4530,20 +4556,20 @@ class MetaData(SchemaItem):
         self._schemas = state["schemas"]
         self._fk_memos = state["fk_memos"]
 
-    def clear(self):
+    def clear(self) -> None:
         """Clear all Table objects from this MetaData."""
 
         dict.clear(self.tables)
         self._schemas.clear()
         self._fk_memos.clear()
 
-    def remove(self, table):
+    def remove(self, table: Table) -> None:
         """Remove the given Table object from this MetaData."""
 
         self._remove_table(table.name, table.schema)
 
     @property
-    def sorted_tables(self):
+    def sorted_tables(self) -> List[Table]:
         """Returns a list of :class:`_schema.Table` objects sorted in order of
         foreign key dependency.
 
@@ -4599,14 +4625,14 @@ class MetaData(SchemaItem):
 
     def reflect(
         self,
-        bind,
-        schema=None,
-        views=False,
-        only=None,
-        extend_existing=False,
-        autoload_replace=True,
-        resolve_fks=True,
-        **dialect_kwargs,
+        bind: Union["Engine", "Connection"],
+        schema: Optional[str] = None,
+        views: bool = False,
+        only: Optional[_typing_Sequence[str]] = None,
+        extend_existing: bool = False,
+        autoload_replace: bool = True,
+        resolve_fks: bool = True,
+        **dialect_kwargs: Any,
     ):
         r"""Load all available table definitions from the database.
 
@@ -4754,7 +4780,12 @@ class MetaData(SchemaItem):
                 except exc.UnreflectableTableError as uerr:
                     util.warn("Skipping table %s: %s" % (name, uerr))
 
-    def create_all(self, bind, tables=None, checkfirst=True):
+    def create_all(
+        self,
+        bind: Union["Engine", "Connection"],
+        tables: Optional[_typing_Sequence[Table]] = None,
+        checkfirst: bool = True,
+    ):
         """Create all tables stored in this metadata.
 
         Conditional by default, will not attempt to recreate tables already
@@ -4777,7 +4808,12 @@ class MetaData(SchemaItem):
             ddl.SchemaGenerator, self, checkfirst=checkfirst, tables=tables
         )
 
-    def drop_all(self, bind, tables=None, checkfirst=True):
+    def drop_all(
+        self,
+        bind: Union["Engine", "Connection"],
+        tables: Optional[_typing_Sequence[Table]] = None,
+        checkfirst: bool = True,
+    ):
         """Drop all tables stored in this metadata.
 
         Conditional by default, will not attempt to drop tables not present in