- add another note re: 339e2c13b0fc8e95a47d00c0f8fc5afc4b6dff9a

which clarifies that ForeignKey circumvents this logic as a
"convenience".   issue #3978 is updated to address trying to make
this consistent.

Change-Id: I089acaa89f11b7a6310c2bf32916e26eb62ab9c0
(cherry picked from commit 8f830d78ba1d68ea3e10006e10e65ddb571f45ee)

diff --git a/lib/sqlalchemy/sql/schema.py b/lib/sqlalchemy/sql/schema.py
index 38884e98e8c066dfde1c290394f96404b6cb8852..8f2bec4daada04e3cf4c55b9fd608cf6766fd67d 100644 (file)
--- a/lib/sqlalchemy/sql/schema.py
+++ b/lib/sqlalchemy/sql/schema.py
@@ -3495,6 +3495,18 @@ class MetaData(SchemaItem):
                 schema-qualified name, e.g.
                 ``my_metadata.tables["some_schema.my_table"]``.
 
+                The current behavior of the :class:`.ForeignKey` object is to
+                circumvent this restriction, where it can locate a table given
+                the table name alone, where the schema will be assumed to be
+                present from this value as specified on the owning
+                :class:`.MetaData` collection.  However, this implies  that a
+                table qualified with BLANK_SCHEMA cannot currently be referred
+                to by string name from :class:`.ForeignKey`.    Other parts of
+                SQLAlchemy such as Declarative may not have similar behaviors
+                built in, however may do so in a future release, along with a
+                consistent method of referring to a table in BLANK_SCHEMA.
+
+
            .. seealso::
 
                 :paramref:`.Table.schema`