- 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
(cherry picked from commit 339e2c13b0fc8e95a47d00c0f8fc5afc4b6dff9a)

diff --git a/lib/sqlalchemy/sql/schema.py b/lib/sqlalchemy/sql/schema.py
index 66996145fdb875fb21948b7a0a561734d117043b..38884e98e8c066dfde1c290394f96404b6cb8852 100644 (file)
--- a/lib/sqlalchemy/sql/schema.py
+++ b/lib/sqlalchemy/sql/schema.py
@@ -3482,6 +3482,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`