- try to explain this better

2 files changed, 29 insertions, 13 deletions

diff --git a/alembic/runtime/environment.py b/alembic/runtime/environment.py
index 3b04fea..7eb06ed 100644
--- a/alembic/runtime/environment.py
+++ b/alembic/runtime/environment.py
@@ -5,16 +5,23 @@ from .. import util
 
 class EnvironmentContext(util.ModuleClsProxy):
 
-    """Represent the state made available to an ``env.py`` script.
+    """A configurational facade made available in an ``env.py`` script.
 
-    :class:`.EnvironmentContext` is normally instantiated
-    by the commands present in the :mod:`alembic.command`
-    module.  From within an ``env.py`` script, the current
-    :class:`.EnvironmentContext` is available via the
-    ``alembic.context`` datamember.
+    The :class:`.EnvironmentContext` acts as a *facade* to the more
+    nuts-and-bolts objects of :class:`.MigrationContext` as well as certain
+    aspects of :class:`.Config`,
+    within the context of the ``env.py`` script that is invoked by
+    most Alembic commands.
 
-    :class:`.EnvironmentContext` is also a Python context
-    manager, that is, is intended to be used using the
+    :class:`.EnvironmentContext` is normally instantiated
+    when a command in :mod:`alembic.command` is run.  It then makes
+    itself available in the ``alembic.context`` module for the scope
+    of the command.   From within an ``env.py`` script, the current
+    :class:`.EnvironmentContext` is available by importing this module.
+
+    :class:`.EnvironmentContext` also supports programmatic usage.
+    At this level, it acts as a Python context manager, that is, is
+    intended to be used using the
     ``with:`` statement.  A typical use of :class:`.EnvironmentContext`::
 
         from alembic.config import Config
diff --git a/docs/build/api/overview.rst b/docs/build/api/overview.rst
index 048d1e6..3e6bec8 100644
--- a/docs/build/api/overview.rst
+++ b/docs/build/api/overview.rst
@@ -14,12 +14,21 @@ This module produces a :class:`.Config` object and passes it to the
 appropriate function in :ref:`alembic.command.toplevel`.   Functions within
 :ref:`alembic.command.toplevel` will typically instantiate an
 :class:`.ScriptDirectory` instance, which represents the collection of
-version files, and an :class:`.EnvironmentContext`, which represents a
-configurational object passed to the environment's ``env.py`` script.
+version files, and an :class:`.EnvironmentContext`, which is a configurational
+facade passed to the environment's ``env.py`` script.
 
-Within the execution of ``env.py``, a :class:`.MigrationContext`
-object is produced when the :meth:`.EnvironmentContext.configure`
-method is called.  :class:`.MigrationContext` is the gateway to the database
+The :class:`.EnvironmentContext` object is the primary object used within
+the ``env.py`` script, whose main purpose is that of a facade for creating and using
+a :class:`.MigrationContext` object, which is the actual migration engine
+that refers to a database implementation.   The primary method called
+on this object within an ``env.py`` script is the
+:meth:`.EnvironmentContext.configure` method, which sets up the
+:class:`.MigrationContext` with database connectivity and behavioral
+configuration.  It also supplies methods for transaction demarcation and
+migration running, but these methods ultimately call upon the
+:class:`.MigrationContext` that's been configured.
+
+:class:`.MigrationContext` is the gateway to the database
 for other parts of the application, and produces a :class:`.DefaultImpl`
 object which does the actual database communication, and knows how to
 create the specific SQL text of the various DDL directives such as