- add a note to MetaData.schema indicating that the Table

will be cataloged in the .tables collection with its fully
qualified name.   Fixes #3978

Change-Id: I65fa063918efc22658e93c39a0680cb83553dec8

1 files changed, 13 insertions, 0 deletions

diff --git a/lib/sqlalchemy/sql/schema.py b/lib/sqlalchemy/sql/schema.py
index cf12ce965..9a8f06c9e 100644
--- a/lib/sqlalchemy/sql/schema.py
+++ b/lib/sqlalchemy/sql/schema.py
@@ -3510,6 +3510,19 @@ class MetaData(SchemaItem):
            even when this parameter is present, use the :attr:`.BLANK_SCHEMA`
            symbol.
 
+           .. note::
+
+                As refered above, the :paramref:`.MetaData.schema` parameter
+                only refers to the **default value** that will be applied to
+                the :paramref:`.Table.schema` parameter of an incoming
+                :class:`.Table` object.   It does not refer to how the
+                :class:`.Table` is catalogued within the :class:`.MetaData`,
+                which remains consistent vs. a :class:`.MetaData` collection
+                that does not define this parameter.  The :class:`.Table`
+                within the :class:`.MetaData` will still be keyed based on its
+                schema-qualified name, e.g.
+                ``my_metadata.tables["some_schema.my_table"]``.
+
            .. seealso::
 
                 :paramref:`.Table.schema`