- 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

diff --git a/lib/sqlalchemy/sql/schema.py b/lib/sqlalchemy/sql/schema.py
index 9a8f06c9e4c767f10c80a7a76ef4d2f2393e8baf..b7d6743be6102f79b1830214cfee224615691fc6 100644 (file)
--- a/lib/sqlalchemy/sql/schema.py
+++ b/lib/sqlalchemy/sql/schema.py
@@ -3523,6 +3523,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`