almost obliterate the concept of "implicit execution" from the docs, move it only

to the "engines and connections" chapter nobody reads, put big green "note:"
boxes with the word "discouraged" in them for "bound metadata", "implicit execution",
"threadlocal strategy"

1 files changed, 13 insertions, 4 deletions

diff --git a/lib/sqlalchemy/schema.py b/lib/sqlalchemy/schema.py
index 367b6e0b2..ada16b71d 100644
--- a/lib/sqlalchemy/schema.py
+++ b/lib/sqlalchemy/schema.py
@@ -2477,11 +2477,20 @@ class MetaData(SchemaItem):
         return self._bind is not None
 
     def bind(self):
-        """An Engine or Connection to which this MetaData is bound.
+        """An :class:`.Engine` or :class:`.Connection` to which this
+        :class:`.MetaData` is bound.
 
-        This property may be assigned an ``Engine`` or ``Connection``, or
-        assigned a string or URL to automatically create a basic ``Engine``
-        for this bind with ``create_engine()``.
+        Typically, a :class:`.Engine` is assigned to this attribute
+        so that "implicit execution" may be used, or alternatively
+        as a means of providing engine binding information to an
+        ORM :class:`.Session` object::
+
+            engine = create_engine("someurl://")
+            metadata.bind = engine
+
+        .. seealso::
+
+           :ref:`dbengine_implicit` - background on "bound metadata"
 
         """
         return self._bind