diff options
-rw-r--r-- | alembic/runtime/environment.py | 23 | ||||
-rw-r--r-- | docs/build/api/overview.rst | 19 |
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 |