documentation including an API diagram

diff --git a/alembic/environment.py b/alembic/environment.py
index 716de62f01ba575534f1130d80b218ab37e74dea..d562add6c12b18e97b1d9c83c6d64db773b42412 100644 (file)
--- a/alembic/environment.py
+++ b/alembic/environment.py
@@ -5,7 +5,15 @@ from alembic import util
 from contextlib import contextmanager
 
 class EnvironmentContext(object):
-    """Represent the state made available to an env.py script."""
+    """Represent the state made available to 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.
+    
+    """
 
     _migration_context = None
     _default_opts = None
@@ -150,11 +158,20 @@ class EnvironmentContext(object):
             sqlalchemy_module_prefix="sa.",
             **kw
         ):
-        """Configure the migration environment.
-
-        The important thing needed here is first a way to figure out
-        what kind of "dialect" is in use.   The second is to pass
-        an actual database connection, if one is required.
+        """Configure a :class:`.MigrationContext` within this
+        :class:`.EnvironmentContext` which will provide database connectivity
+        and other configuration to a series of migration scripts.
+        
+        Many methods on :class:`.EnvironmentContext` require that 
+        this method has been called in order to function, as they
+        ultimately need to have database access or at least access
+        to the dialect in use.  Those which do are documented as such.
+        
+        The important thing needed by :meth:`.configure` is a
+        means to determine what kind of database dialect is in use.  
+        An actual connection to that database is needed only if
+        the :class:`.MigrationContext` is to be used in 
+        "online" mode.
 
         If the :meth:`.is_offline_mode` function returns ``True``,
         then no connection is needed here.  Otherwise, the
@@ -420,11 +437,6 @@ class EnvironmentContext(object):
         If :meth:`.EnvironmentContext.configure` has not been called yet, raises
         an exception.
 
-        Generally, env.py scripts should access this via
-        the ``alembic.context`` object, which is an instance of
-        :class:`.MigrationContext` placed there for the duration 
-        of the env.py script's usage.
-
         """
         if self._migration_context is None:
             raise Exception("No context has been configured yet.")

diff --git a/alembic/operations.py b/alembic/operations.py
index 7d59c41c1df8b509cd65c4ad41fb0fd1a5511475..18b8e69294ff6986548d9e28d640a1a1aadf9e62 100644 (file)
--- a/alembic/operations.py
+++ b/alembic/operations.py
@@ -13,9 +13,23 @@ class Operations(object):
     Each operation corresponds to some schema migration operation,
     executed against a particular :class:`.MigrationContext`.
     
+    Normally, the :class:`.MigrationContext` is created
+    within an ``env.py`` script via the
+    :meth:`.EnvironmentContext.configure` method.  However,
+    the :class:`.Operations` object can also be used without
+    actually using the :class:`.EnvironmentContext` 
+    class - only :class:`.MigrationContext`, which represents
+    connectivity to a single database, is needed
+    to use the directives.
+    
     """
     def __init__(self, migration_context):
-        """Construct a new :class:`.Operations`"""
+        """Construct a new :class:`.Operations`
+        
+        :param migration_context: a :class:`.MigrationContext` 
+         instance.
+         
+        """
         self.migration_context = migration_context
         self.impl = migration_context.impl
 

diff --git a/docs/build/api.rst b/docs/build/api.rst
index 8541cbf78e2910c14c22398fd42caf8c534e9663..3abc955695ecf8e253a2d9bebeb9c28090bdc1e1 100644 (file)
--- a/docs/build/api.rst
+++ b/docs/build/api.rst
@@ -5,18 +5,51 @@ API Details
 This section describes some key functions used within the migration process, particularly those referenced within
 a migration environment's ``env.py`` file.
 
+Overview
+========
+
+The three main objects in use are the :class:`.EnvironmentContext`, :class:`.MigrationContext`,
+and :class:`.Operations` classes, pictured below.
+
+.. image:: api_overview.png
+
+An Alembic command begins by instantiating an :class:`.EnvironmentContext` object, then
+making it available via the ``alembic.context`` datamember.  The ``env.py``
+script, representing a user-configurable migration environment, is then 
+invoked.   The ``env.py`` script is then responsible for calling upon the
+:meth:`.EnvironmentContext.configure`, whose job it is to create 
+a :class:`.MigrationContext` object. 
+
+Before this method is called, there's not
+yet any database connection or dialect-specific state set up.  While 
+many methods on :class:`.EnvironmentContext` are usable at this stage,
+those which require database access, or at least access to the kind 
+of database dialect in use, are not.   Once the 
+:meth:`.EnvironmentContext.configure` method is called, the :class:`.EnvironmentContext`
+is said to be *configured* with database connectivity, available via
+a new :class:`.MigrationContext` object.   The :class:`.MigrationContext`
+is associated with the :class:`.EnvironmentContext` object
+via the :attr:`.EnvironmentContext.migration_context` datamember.
+
+Finally, ``env.py`` calls upon the :meth:`.EnvironmentContext.run_migrations`
+method.   Within this method, a new :class:`.Operations` object, which
+provides an API for individual database migration operations, is established
+within the ``alembic.op`` datamember.   The :class:`.Operations` object
+uses the :class:`.MigrationContext` object ultimately as a source of 
+database connectivity, though in such a way that it does not care if the
+:class:`.MigrationContext` is talking to a real database or just writing
+out SQL to a file.
+
 env.py Directives
 =================
 
-The :mod:`alembic.environment` module contains API features that are generally used within
-``env.py`` files.
+This section covers the objects that are generally used within an 
+``env.py`` environmental configuration script.   Alembic normally generates
+this script for you; it is however made available locally within the migrations
+environment so that it can be customized.
 
-The central object in use is the :class:`.EnvironmentContext` object.   This object is 
-made present when the ``env.py`` script calls upon the :meth:`.EnvironmentContext.configure`
-method for the first time.  Before this function is called, there's not
-yet any database connection or dialect-specific state set up, and those
-functions which require this state will raise an exception when used,
-until :meth:`.EnvironmentContext.configure` is called successfully.
+In particular, the key method used within ``env.py`` is :meth:`.EnvironmentContext.configure`,
+which establishes all the details about how the database will be accessed.
 
 
 .. autofunction:: sqlalchemy.engine.engine_from_config
@@ -27,7 +60,6 @@ until :meth:`.EnvironmentContext.configure` is called successfully.
 .. automodule:: alembic.migration
     :members:
 
-
 Commands
 =========
 

diff --git a/docs/build/api_overview.png b/docs/build/api_overview.png
new file mode 100644 (file)
index 0000000..1ad7993
Binary files /dev/null and b/docs/build/api_overview.png differ

diff --git a/docs/build/assets/api_overview.graffle b/docs/build/assets/api_overview.graffle
new file mode 100644 (file)
index 0000000..b363d52
--- /dev/null
+++ b/docs/build/assets/api_overview.graffle
@@ -0,0 +1,1181 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+       <key>ActiveLayerIndex</key>
+       <integer>0</integer>
+       <key>AutoAdjust</key>
+       <true/>
+       <key>CanvasColor</key>
+       <dict>
+               <key>w</key>
+               <string>1</string>
+       </dict>
+       <key>CanvasOrigin</key>
+       <string>{0, 0}</string>
+       <key>CanvasScale</key>
+       <real>1</real>
+       <key>ColumnAlign</key>
+       <integer>1</integer>
+       <key>ColumnSpacing</key>
+       <real>36</real>
+       <key>CreationDate</key>
+       <string>2012-01-24 16:51:07 -0500</string>
+       <key>Creator</key>
+       <string>classic</string>
+       <key>DisplayScale</key>
+       <string>1 in = 1 in</string>
+       <key>GraphDocumentVersion</key>
+       <integer>5</integer>
+       <key>GraphicsList</key>
+       <array>
+               <dict>
+                       <key>Class</key>
+                       <string>LineGraphic</string>
+                       <key>Head</key>
+                       <dict>
+                               <key>ID</key>
+                               <integer>2048</integer>
+                       </dict>
+                       <key>ID</key>
+                       <integer>2051</integer>
+                       <key>Points</key>
+                       <array>
+                               <string>{165, 221.6}</string>
+                               <string>{109, 221.6}</string>
+                       </array>
+                       <key>Style</key>
+                       <dict>
+                               <key>stroke</key>
+                               <dict>
+                                       <key>HeadArrow</key>
+                                       <string>StickArrow</string>
+                                       <key>Pattern</key>
+                                       <integer>1</integer>
+                                       <key>TailArrow</key>
+                                       <string>0</string>
+                               </dict>
+                       </dict>
+                       <key>Tail</key>
+                       <dict>
+                               <key>ID</key>
+                               <integer>33</integer>
+                       </dict>
+               </dict>
+               <dict>
+                       <key>Class</key>
+                       <string>TableGroup</string>
+                       <key>Graphics</key>
+                       <array>
+                               <dict>
+                                       <key>Bounds</key>
+                                       <string>{{19, 207.6}, {90, 14}}</string>
+                                       <key>Class</key>
+                                       <string>ShapedGraphic</string>
+                                       <key>FitText</key>
+                                       <string>Vertical</string>
+                                       <key>Flow</key>
+                                       <string>Resize</string>
+                                       <key>ID</key>
+                                       <integer>2049</integer>
+                                       <key>Shape</key>
+                                       <string>Rectangle</string>
+                                       <key>Style</key>
+                                       <dict>
+                                               <key>fill</key>
+                                               <dict>
+                                                       <key>GradientAngle</key>
+                                                       <real>304</real>
+                                                       <key>GradientCenter</key>
+                                                       <string>{-0.294118, -0.264706}</string>
+                                               </dict>
+                                       </dict>
+                                       <key>Text</key>
+                                       <dict>
+                                               <key>Text</key>
+                                               <string>{\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360
+{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc
+
+\f0\b\fs24 \cf0 Config}</string>
+                                       </dict>
+                                       <key>TextPlacement</key>
+                                       <integer>0</integer>
+                               </dict>
+                               <dict>
+                                       <key>Bounds</key>
+                                       <string>{{19, 221.6}, {90, 14}}</string>
+                                       <key>Class</key>
+                                       <string>ShapedGraphic</string>
+                                       <key>FitText</key>
+                                       <string>Vertical</string>
+                                       <key>Flow</key>
+                                       <string>Resize</string>
+                                       <key>ID</key>
+                                       <integer>2050</integer>
+                                       <key>Shape</key>
+                                       <string>Rectangle</string>
+                                       <key>Style</key>
+                                       <dict>
+                                               <key>fill</key>
+                                               <dict>
+                                                       <key>GradientAngle</key>
+                                                       <real>304</real>
+                                                       <key>GradientCenter</key>
+                                                       <string>{-0.294118, -0.264706}</string>
+                                               </dict>
+                                       </dict>
+                                       <key>Text</key>
+                                       <dict>
+                                               <key>Align</key>
+                                               <integer>0</integer>
+                                               <key>Text</key>
+                                               <string>{\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360
+{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
+
+\f0\fs24 \cf0 ConfigParser}</string>
+                                       </dict>
+                                       <key>TextPlacement</key>
+                                       <integer>0</integer>
+                               </dict>
+                       </array>
+                       <key>GridH</key>
+                       <array>
+                               <integer>2049</integer>
+                               <integer>2050</integer>
+                               <array/>
+                       </array>
+                       <key>GroupConnect</key>
+                       <string>YES</string>
+                       <key>ID</key>
+                       <integer>2048</integer>
+               </dict>
+               <dict>
+                       <key>Class</key>
+                       <string>LineGraphic</string>
+                       <key>Head</key>
+                       <dict>
+                               <key>ID</key>
+                               <integer>2042</integer>
+                       </dict>
+                       <key>ID</key>
+                       <integer>2046</integer>
+                       <key>OrthogonalBarAutomatic</key>
+                       <true/>
+                       <key>OrthogonalBarPosition</key>
+                       <real>28.725006103515625</real>
+                       <key>Points</key>
+                       <array>
+                               <string>{304, 198.756}</string>
+                               <string>{385.25, 157}</string>
+                       </array>
+                       <key>Style</key>
+                       <dict>
+                               <key>stroke</key>
+                               <dict>
+                                       <key>HeadArrow</key>
+                                       <string>StickArrow</string>
+                                       <key>LineType</key>
+                                       <integer>2</integer>
+                                       <key>Pattern</key>
+                                       <integer>1</integer>
+                                       <key>TailArrow</key>
+                                       <string>0</string>
+                               </dict>
+                       </dict>
+                       <key>Tail</key>
+                       <dict>
+                               <key>ID</key>
+                               <integer>33</integer>
+                       </dict>
+               </dict>
+               <dict>
+                       <key>Class</key>
+                       <string>LineGraphic</string>
+                       <key>Head</key>
+                       <dict>
+                               <key>ID</key>
+                               <integer>2043</integer>
+                       </dict>
+                       <key>ID</key>
+                       <integer>2044</integer>
+                       <key>OrthogonalBarAutomatic</key>
+                       <true/>
+                       <key>OrthogonalBarPosition</key>
+                       <real>52.850021362304688</real>
+                       <key>Points</key>
+                       <array>
+                               <string>{433.496, 294.6}</string>
+                               <string>{454.25, 177}</string>
+                       </array>
+                       <key>Style</key>
+                       <dict>
+                               <key>stroke</key>
+                               <dict>
+                                       <key>HeadArrow</key>
+                                       <string>StickArrow</string>
+                                       <key>LineType</key>
+                                       <integer>2</integer>
+                                       <key>Pattern</key>
+                                       <integer>1</integer>
+                                       <key>TailArrow</key>
+                                       <string>0</string>
+                               </dict>
+                       </dict>
+                       <key>Tail</key>
+                       <dict>
+                               <key>ID</key>
+                               <integer>38</integer>
+                       </dict>
+               </dict>
+               <dict>
+                       <key>Bounds</key>
+                       <string>{{385.25, 172}, {69, 14}}</string>
+                       <key>Class</key>
+                       <string>ShapedGraphic</string>
+                       <key>FitText</key>
+                       <string>YES</string>
+                       <key>Flow</key>
+                       <string>Resize</string>
+                       <key>ID</key>
+                       <integer>2043</integer>
+                       <key>Magnets</key>
+                       <array>
+                               <string>{0.5, -0.142857}</string>
+                       </array>
+                       <key>Shape</key>
+                       <string>Rectangle</string>
+                       <key>Style</key>
+                       <dict>
+                               <key>fill</key>
+                               <dict>
+                                       <key>Draws</key>
+                                       <string>NO</string>
+                               </dict>
+                               <key>shadow</key>
+                               <dict>
+                                       <key>Draws</key>
+                                       <string>NO</string>
+                               </dict>
+                               <key>stroke</key>
+                               <dict>
+                                       <key>Draws</key>
+                                       <string>NO</string>
+                               </dict>
+                       </dict>
+                       <key>Text</key>
+                       <dict>
+                               <key>Text</key>
+                               <string>{\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360
+{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc\pardirnatural
+
+\f0\fs24 \cf0 alembic.op}</string>
+                       </dict>
+                       <key>Wrap</key>
+                       <string>NO</string>
+               </dict>
+               <dict>
+                       <key>Bounds</key>
+                       <string>{{385.25, 149.6}, {94, 14}}</string>
+                       <key>Class</key>
+                       <string>ShapedGraphic</string>
+                       <key>FitText</key>
+                       <string>YES</string>
+                       <key>Flow</key>
+                       <string>Resize</string>
+                       <key>ID</key>
+                       <integer>2042</integer>
+                       <key>Magnets</key>
+                       <array>
+                               <string>{0.49734, 0.0285711}</string>
+                       </array>
+                       <key>Shape</key>
+                       <string>Rectangle</string>
+                       <key>Style</key>
+                       <dict>
+                               <key>fill</key>
+                               <dict>
+                                       <key>Draws</key>
+                                       <string>NO</string>
+                               </dict>
+                               <key>shadow</key>
+                               <dict>
+                                       <key>Draws</key>
+                                       <string>NO</string>
+                               </dict>
+                               <key>stroke</key>
+                               <dict>
+                                       <key>Draws</key>
+                                       <string>NO</string>
+                               </dict>
+                       </dict>
+                       <key>Text</key>
+                       <dict>
+                               <key>Text</key>
+                               <string>{\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360
+{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc\pardirnatural
+
+\f0\fs24 \cf0 alembic.context}</string>
+                       </dict>
+                       <key>Wrap</key>
+                       <string>NO</string>
+               </dict>
+               <dict>
+                       <key>Class</key>
+                       <string>LineGraphic</string>
+                       <key>Head</key>
+                       <dict>
+                               <key>ID</key>
+                               <integer>2038</integer>
+                       </dict>
+                       <key>ID</key>
+                       <integer>2040</integer>
+                       <key>Points</key>
+                       <array>
+                               <string>{166.088, 336.6}</string>
+                               <string>{105.686, 336.6}</string>
+                       </array>
+                       <key>Style</key>
+                       <dict>
+                               <key>stroke</key>
+                               <dict>
+                                       <key>HeadArrow</key>
+                                       <string>StickArrow</string>
+                                       <key>Pattern</key>
+                                       <integer>1</integer>
+                                       <key>TailArrow</key>
+                                       <string>0</string>
+                               </dict>
+                       </dict>
+                       <key>Tail</key>
+                       <dict>
+                               <key>ID</key>
+                               <integer>41</integer>
+                       </dict>
+               </dict>
+               <dict>
+                       <key>Bounds</key>
+                       <string>{{19, 294.6}, {86.1858, 84}}</string>
+                       <key>Class</key>
+                       <string>ShapedGraphic</string>
+                       <key>ID</key>
+                       <integer>2038</integer>
+                       <key>Shape</key>
+                       <string>Cylinder</string>
+                       <key>Text</key>
+                       <dict>
+                               <key>Text</key>
+                               <string>{\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360
+{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc\pardirnatural
+
+\f0\fs24 \cf0 database}</string>
+                       </dict>
+               </dict>
+               <dict>
+                       <key>Bounds</key>
+                       <string>{{227.597, 278.569}, {55, 12}}</string>
+                       <key>Class</key>
+                       <string>ShapedGraphic</string>
+                       <key>FitText</key>
+                       <string>YES</string>
+                       <key>ID</key>
+                       <integer>51</integer>
+                       <key>Line</key>
+                       <dict>
+                               <key>ID</key>
+                               <integer>50</integer>
+                               <key>Offset</key>
+                               <real>-20</real>
+                               <key>Position</key>
+                               <real>0.40689659118652344</real>
+                               <key>RotationType</key>
+                               <integer>0</integer>
+                       </dict>
+                       <key>Shape</key>
+                       <string>Rectangle</string>
+                       <key>Style</key>
+                       <dict>
+                               <key>shadow</key>
+                               <dict>
+                                       <key>Draws</key>
+                                       <string>NO</string>
+                               </dict>
+                               <key>stroke</key>
+                               <dict>
+                                       <key>Draws</key>
+                                       <string>NO</string>
+                               </dict>
+                       </dict>
+                       <key>Text</key>
+                       <dict>
+                               <key>Align</key>
+                               <integer>0</integer>
+                               <key>Text</key>
+                               <string>{\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360
+{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
+
+\f0\fs20 \cf0 &lt;&lt;uses&gt;&gt;}</string>
+                       </dict>
+               </dict>
+               <dict>
+                       <key>Class</key>
+                       <string>LineGraphic</string>
+                       <key>Head</key>
+                       <dict>
+                               <key>ID</key>
+                               <integer>41</integer>
+                       </dict>
+                       <key>ID</key>
+                       <integer>50</integer>
+                       <key>Points</key>
+                       <array>
+                               <string>{234.897, 263.6}</string>
+                               <string>{235.389, 315.6}</string>
+                       </array>
+                       <key>Style</key>
+                       <dict>
+                               <key>stroke</key>
+                               <dict>
+                                       <key>HeadArrow</key>
+                                       <string>StickArrow</string>
+                                       <key>Pattern</key>
+                                       <integer>1</integer>
+                                       <key>TailArrow</key>
+                                       <string>0</string>
+                               </dict>
+                       </dict>
+                       <key>Tail</key>
+                       <dict>
+                               <key>ID</key>
+                               <integer>33</integer>
+                       </dict>
+               </dict>
+               <dict>
+                       <key>Bounds</key>
+                       <string>{{308.265, 310.6}, {55, 12}}</string>
+                       <key>Class</key>
+                       <string>ShapedGraphic</string>
+                       <key>FitText</key>
+                       <string>YES</string>
+                       <key>ID</key>
+                       <integer>49</integer>
+                       <key>Line</key>
+                       <dict>
+                               <key>ID</key>
+                               <integer>9</integer>
+                               <key>Offset</key>
+                               <real>-20</real>
+                               <key>Position</key>
+                               <real>0.5199354887008667</real>
+                               <key>RotationType</key>
+                               <integer>0</integer>
+                       </dict>
+                       <key>Shape</key>
+                       <string>Rectangle</string>
+                       <key>Style</key>
+                       <dict>
+                               <key>shadow</key>
+                               <dict>
+                                       <key>Draws</key>
+                                       <string>NO</string>
+                               </dict>
+                               <key>stroke</key>
+                               <dict>
+                                       <key>Draws</key>
+                                       <string>NO</string>
+                               </dict>
+                       </dict>
+                       <key>Text</key>
+                       <dict>
+                               <key>Align</key>
+                               <integer>0</integer>
+                               <key>Text</key>
+                               <string>{\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360
+{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
+
+\f0\fs20 \cf0 &lt;&lt;uses&gt;&gt;}</string>
+                       </dict>
+               </dict>
+               <dict>
+                       <key>Class</key>
+                       <string>LineGraphic</string>
+                       <key>Head</key>
+                       <dict>
+                               <key>ID</key>
+                               <integer>41</integer>
+                       </dict>
+                       <key>ID</key>
+                       <integer>9</integer>
+                       <key>Points</key>
+                       <array>
+                               <string>{368.99, 336.6}</string>
+                               <string>{305.088, 336.6}</string>
+                       </array>
+                       <key>Style</key>
+                       <dict>
+                               <key>stroke</key>
+                               <dict>
+                                       <key>HeadArrow</key>
+                                       <string>StickArrow</string>
+                                       <key>Pattern</key>
+                                       <integer>1</integer>
+                                       <key>TailArrow</key>
+                                       <string>0</string>
+                               </dict>
+                       </dict>
+                       <key>Tail</key>
+                       <dict>
+                               <key>ID</key>
+                               <integer>38</integer>
+                       </dict>
+               </dict>
+               <dict>
+                       <key>Class</key>
+                       <string>TableGroup</string>
+                       <key>Graphics</key>
+                       <array>
+                               <dict>
+                                       <key>Bounds</key>
+                                       <string>{{166.088, 315.6}, {139, 14}}</string>
+                                       <key>Class</key>
+                                       <string>ShapedGraphic</string>
+                                       <key>FitText</key>
+                                       <string>Vertical</string>
+                                       <key>Flow</key>
+                                       <string>Resize</string>
+                                       <key>ID</key>
+                                       <integer>42</integer>
+                                       <key>Shape</key>
+                                       <string>Rectangle</string>
+                                       <key>Style</key>
+                                       <dict>
+                                               <key>fill</key>
+                                               <dict>
+                                                       <key>GradientAngle</key>
+                                                       <real>304</real>
+                                                       <key>GradientCenter</key>
+                                                       <string>{-0.294118, -0.264706}</string>
+                                               </dict>
+                                       </dict>
+                                       <key>Text</key>
+                                       <dict>
+                                               <key>Text</key>
+                                               <string>{\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360
+{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc
+
+\f0\b\fs24 \cf0 MigrationContext}</string>
+                                       </dict>
+                                       <key>TextPlacement</key>
+                                       <integer>0</integer>
+                               </dict>
+                               <dict>
+                                       <key>Bounds</key>
+                                       <string>{{166.088, 329.6}, {139, 28}}</string>
+                                       <key>Class</key>
+                                       <string>ShapedGraphic</string>
+                                       <key>FitText</key>
+                                       <string>Vertical</string>
+                                       <key>Flow</key>
+                                       <string>Resize</string>
+                                       <key>ID</key>
+                                       <integer>44</integer>
+                                       <key>Shape</key>
+                                       <string>Rectangle</string>
+                                       <key>Style</key>
+                                       <dict>
+                                               <key>fill</key>
+                                               <dict>
+                                                       <key>GradientAngle</key>
+                                                       <real>304</real>
+                                                       <key>GradientCenter</key>
+                                                       <string>{-0.294118, -0.264706}</string>
+                                               </dict>
+                                       </dict>
+                                       <key>Text</key>
+                                       <dict>
+                                               <key>Align</key>
+                                               <integer>0</integer>
+                                               <key>Text</key>
+                                               <string>{\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360
+{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural\pardirnatural
+
+\f0\fs24 \cf0 connection\
+run_migrations()}</string>
+                                       </dict>
+                                       <key>TextPlacement</key>
+                                       <integer>0</integer>
+                               </dict>
+                       </array>
+                       <key>GridH</key>
+                       <array>
+                               <integer>42</integer>
+                               <integer>44</integer>
+                               <array/>
+                       </array>
+                       <key>GroupConnect</key>
+                       <string>YES</string>
+                       <key>ID</key>
+                       <integer>41</integer>
+               </dict>
+               <dict>
+                       <key>Class</key>
+                       <string>TableGroup</string>
+                       <key>Graphics</key>
+                       <array>
+                               <dict>
+                                       <key>Bounds</key>
+                                       <string>{{368.99, 294.6}, {139, 14}}</string>
+                                       <key>Class</key>
+                                       <string>ShapedGraphic</string>
+                                       <key>FitText</key>
+                                       <string>Vertical</string>
+                                       <key>Flow</key>
+                                       <string>Resize</string>
+                                       <key>ID</key>
+                                       <integer>39</integer>
+                                       <key>Shape</key>
+                                       <string>Rectangle</string>
+                                       <key>Style</key>
+                                       <dict>
+                                               <key>fill</key>
+                                               <dict>
+                                                       <key>GradientAngle</key>
+                                                       <real>304</real>
+                                                       <key>GradientCenter</key>
+                                                       <string>{-0.294118, -0.264706}</string>
+                                               </dict>
+                                       </dict>
+                                       <key>Text</key>
+                                       <dict>
+                                               <key>Text</key>
+                                               <string>{\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360
+{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc
+
+\f0\b\fs24 \cf0 Operations}</string>
+                                       </dict>
+                                       <key>TextPlacement</key>
+                                       <integer>0</integer>
+                               </dict>
+                               <dict>
+                                       <key>Bounds</key>
+                                       <string>{{368.99, 308.6}, {139, 70}}</string>
+                                       <key>Class</key>
+                                       <string>ShapedGraphic</string>
+                                       <key>FitText</key>
+                                       <string>Vertical</string>
+                                       <key>Flow</key>
+                                       <string>Resize</string>
+                                       <key>ID</key>
+                                       <integer>40</integer>
+                                       <key>Shape</key>
+                                       <string>Rectangle</string>
+                                       <key>Style</key>
+                                       <dict>
+                                               <key>fill</key>
+                                               <dict>
+                                                       <key>GradientAngle</key>
+                                                       <real>304</real>
+                                                       <key>GradientCenter</key>
+                                                       <string>{-0.294118, -0.264706}</string>
+                                               </dict>
+                                       </dict>
+                                       <key>Text</key>
+                                       <dict>
+                                               <key>Align</key>
+                                               <integer>0</integer>
+                                               <key>Text</key>
+                                               <string>{\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360
+{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
+
+\f0\fs24 \cf0 migration_context\
+create_table()\
+alter_column()\
+add_column()\
+drop_column()}</string>
+                                       </dict>
+                                       <key>TextPlacement</key>
+                                       <integer>0</integer>
+                               </dict>
+                       </array>
+                       <key>GridH</key>
+                       <array>
+                               <integer>39</integer>
+                               <integer>40</integer>
+                               <array/>
+                       </array>
+                       <key>GroupConnect</key>
+                       <string>YES</string>
+                       <key>ID</key>
+                       <integer>38</integer>
+               </dict>
+               <dict>
+                       <key>Class</key>
+                       <string>TableGroup</string>
+                       <key>Graphics</key>
+                       <array>
+                               <dict>
+                                       <key>Bounds</key>
+                                       <string>{{165, 179.6}, {139, 14}}</string>
+                                       <key>Class</key>
+                                       <string>ShapedGraphic</string>
+                                       <key>FitText</key>
+                                       <string>Vertical</string>
+                                       <key>Flow</key>
+                                       <string>Resize</string>
+                                       <key>ID</key>
+                                       <integer>34</integer>
+                                       <key>Shape</key>
+                                       <string>Rectangle</string>
+                                       <key>Style</key>
+                                       <dict>
+                                               <key>fill</key>
+                                               <dict>
+                                                       <key>GradientAngle</key>
+                                                       <real>304</real>
+                                                       <key>GradientCenter</key>
+                                                       <string>{-0.294118, -0.264706}</string>
+                                               </dict>
+                                       </dict>
+                                       <key>Text</key>
+                                       <dict>
+                                               <key>Text</key>
+                                               <string>{\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360
+{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc
+
+\f0\b\fs24 \cf0 EnvironmentContext}</string>
+                                       </dict>
+                                       <key>TextPlacement</key>
+                                       <integer>0</integer>
+                               </dict>
+                               <dict>
+                                       <key>Bounds</key>
+                                       <string>{{165, 193.6}, {139, 70}}</string>
+                                       <key>Class</key>
+                                       <string>ShapedGraphic</string>
+                                       <key>FitText</key>
+                                       <string>Vertical</string>
+                                       <key>Flow</key>
+                                       <string>Resize</string>
+                                       <key>ID</key>
+                                       <integer>35</integer>
+                                       <key>Shape</key>
+                                       <string>Rectangle</string>
+                                       <key>Style</key>
+                                       <dict>
+                                               <key>fill</key>
+                                               <dict>
+                                                       <key>GradientAngle</key>
+                                                       <real>304</real>
+                                                       <key>GradientCenter</key>
+                                                       <string>{-0.294118, -0.264706}</string>
+                                               </dict>
+                                       </dict>
+                                       <key>Text</key>
+                                       <dict>
+                                               <key>Align</key>
+                                               <integer>0</integer>
+                                               <key>Text</key>
+                                               <string>{\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360
+{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
+
+\f0\fs24 \cf0 migration_context\
+configure()\
+run_migrations()\
+begin_transaction()\
+is_offline_mode()}</string>
+                                       </dict>
+                                       <key>TextPlacement</key>
+                                       <integer>0</integer>
+                               </dict>
+                       </array>
+                       <key>GridH</key>
+                       <array>
+                               <integer>34</integer>
+                               <integer>35</integer>
+                               <array/>
+                       </array>
+                       <key>GroupConnect</key>
+                       <string>YES</string>
+                       <key>ID</key>
+                       <integer>33</integer>
+               </dict>
+               <dict>
+                       <key>Bounds</key>
+                       <string>{{153.176, 149.6}, {164.824, 255}}</string>
+                       <key>Class</key>
+                       <string>ShapedGraphic</string>
+                       <key>ID</key>
+                       <integer>2036</integer>
+                       <key>Shape</key>
+                       <string>Rectangle</string>
+                       <key>Style</key>
+                       <dict>
+                               <key>fill</key>
+                               <dict>
+                                       <key>Draws</key>
+                                       <string>NO</string>
+                               </dict>
+                               <key>shadow</key>
+                               <dict>
+                                       <key>Draws</key>
+                                       <string>NO</string>
+                                       <key>Fuzziness</key>
+                                       <real>0.0</real>
+                               </dict>
+                               <key>stroke</key>
+                               <dict>
+                                       <key>Color</key>
+                                       <dict>
+                                               <key>b</key>
+                                               <string>0.191506</string>
+                                               <key>g</key>
+                                               <string>0.389204</string>
+                                               <key>r</key>
+                                               <string>0.744565</string>
+                                       </dict>
+                                       <key>CornerRadius</key>
+                                       <real>5</real>
+                                       <key>Pattern</key>
+                                       <integer>1</integer>
+                               </dict>
+                       </dict>
+                       <key>Text</key>
+                       <dict>
+                               <key>Align</key>
+                               <integer>0</integer>
+                               <key>Text</key>
+                               <string>{\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360
+{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural\pardirnatural
+
+\f0\fs24 \cf0 env.py script}</string>
+                       </dict>
+                       <key>TextPlacement</key>
+                       <integer>0</integer>
+                       <key>Wrap</key>
+                       <string>NO</string>
+               </dict>
+               <dict>
+                       <key>Bounds</key>
+                       <string>{{343.99, 259.266}, {189, 145.334}}</string>
+                       <key>Class</key>
+                       <string>ShapedGraphic</string>
+                       <key>ID</key>
+                       <integer>2032</integer>
+                       <key>Shape</key>
+                       <string>Rectangle</string>
+                       <key>Style</key>
+                       <dict>
+                               <key>fill</key>
+                               <dict>
+                                       <key>Draws</key>
+                                       <string>NO</string>
+                               </dict>
+                               <key>shadow</key>
+                               <dict>
+                                       <key>Draws</key>
+                                       <string>NO</string>
+                                       <key>Fuzziness</key>
+                                       <real>0.0</real>
+                               </dict>
+                               <key>stroke</key>
+                               <dict>
+                                       <key>Color</key>
+                                       <dict>
+                                               <key>b</key>
+                                               <string>0.191506</string>
+                                               <key>g</key>
+                                               <string>0.389204</string>
+                                               <key>r</key>
+                                               <string>0.744565</string>
+                                       </dict>
+                                       <key>CornerRadius</key>
+                                       <real>5</real>
+                                       <key>Pattern</key>
+                                       <integer>1</integer>
+                               </dict>
+                       </dict>
+                       <key>Text</key>
+                       <dict>
+                               <key>Align</key>
+                               <integer>0</integer>
+                               <key>Text</key>
+                               <string>{\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360
+{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural\pardirnatural
+
+\f0\fs24 \cf0 migration script}</string>
+                       </dict>
+                       <key>TextPlacement</key>
+                       <integer>0</integer>
+                       <key>Wrap</key>
+                       <string>NO</string>
+               </dict>
+               <dict>
+                       <key>Bounds</key>
+                       <string>{{138.176, 127.6}, {420.824, 293.4}}</string>
+                       <key>Class</key>
+                       <string>ShapedGraphic</string>
+                       <key>ID</key>
+                       <integer>2037</integer>
+                       <key>Shape</key>
+                       <string>Rectangle</string>
+                       <key>Style</key>
+                       <dict>
+                               <key>fill</key>
+                               <dict>
+                                       <key>Draws</key>
+                                       <string>NO</string>
+                               </dict>
+                               <key>shadow</key>
+                               <dict>
+                                       <key>Draws</key>
+                                       <string>NO</string>
+                                       <key>Fuzziness</key>
+                                       <real>0.0</real>
+                               </dict>
+                               <key>stroke</key>
+                               <dict>
+                                       <key>Color</key>
+                                       <dict>
+                                               <key>b</key>
+                                               <string>0.191506</string>
+                                               <key>g</key>
+                                               <string>0.389204</string>
+                                               <key>r</key>
+                                               <string>0.744565</string>
+                                       </dict>
+                                       <key>CornerRadius</key>
+                                       <real>5</real>
+                                       <key>Pattern</key>
+                                       <integer>1</integer>
+                               </dict>
+                       </dict>
+                       <key>Text</key>
+                       <dict>
+                               <key>Align</key>
+                               <integer>0</integer>
+                               <key>Text</key>
+                               <string>{\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf360
+{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural\pardirnatural
+
+\f0\fs24 \cf0 alembic command}</string>
+                       </dict>
+                       <key>TextPlacement</key>
+                       <integer>0</integer>
+                       <key>Wrap</key>
+                       <string>NO</string>
+               </dict>
+       </array>
+       <key>GridInfo</key>
+       <dict/>
+       <key>GuidesLocked</key>
+       <string>NO</string>
+       <key>GuidesVisible</key>
+       <string>YES</string>
+       <key>HPages</key>
+       <integer>1</integer>
+       <key>ImageCounter</key>
+       <integer>1</integer>
+       <key>IsPalette</key>
+       <string>NO</string>
+       <key>KeepToScale</key>
+       <false/>
+       <key>Layers</key>
+       <array>
+               <dict>
+                       <key>Lock</key>
+                       <string>NO</string>
+                       <key>Name</key>
+                       <string>Layer 1</string>
+                       <key>Print</key>
+                       <string>YES</string>
+                       <key>View</key>
+                       <string>YES</string>
+               </dict>
+       </array>
+       <key>LayoutInfo</key>
+       <dict/>
+       <key>LinksVisible</key>
+       <string>NO</string>
+       <key>MagnetsVisible</key>
+       <string>NO</string>
+       <key>MasterSheet</key>
+       <string>Master 1</string>
+       <key>MasterSheets</key>
+       <array>
+               <dict>
+                       <key>ActiveLayerIndex</key>
+                       <integer>0</integer>
+                       <key>AutoAdjust</key>
+                       <true/>
+                       <key>CanvasColor</key>
+                       <dict>
+                               <key>w</key>
+                               <string>1</string>
+                       </dict>
+                       <key>CanvasOrigin</key>
+                       <string>{0, 0}</string>
+                       <key>CanvasScale</key>
+                       <real>1</real>
+                       <key>ColumnAlign</key>
+                       <integer>1</integer>
+                       <key>ColumnSpacing</key>
+                       <real>36</real>
+                       <key>DisplayScale</key>
+                       <string>1 in = 1 in</string>
+                       <key>GraphicsList</key>
+                       <array/>
+                       <key>GridInfo</key>
+                       <dict/>
+                       <key>HPages</key>
+                       <integer>1</integer>
+                       <key>IsPalette</key>
+                       <string>NO</string>
+                       <key>KeepToScale</key>
+                       <false/>
+                       <key>Layers</key>
+                       <array>
+                               <dict>
+                                       <key>Lock</key>
+                                       <string>NO</string>
+                                       <key>Name</key>
+                                       <string>Layer 1</string>
+                                       <key>Print</key>
+                                       <string>YES</string>
+                                       <key>View</key>
+                                       <string>YES</string>
+                               </dict>
+                       </array>
+                       <key>LayoutInfo</key>
+                       <dict/>
+                       <key>Orientation</key>
+                       <integer>2</integer>
+                       <key>OutlineStyle</key>
+                       <string>Basic</string>
+                       <key>RowAlign</key>
+                       <integer>1</integer>
+                       <key>RowSpacing</key>
+                       <real>36</real>
+                       <key>SheetTitle</key>
+                       <string>Master 1</string>
+                       <key>UniqueID</key>
+                       <integer>1</integer>
+                       <key>VPages</key>
+                       <integer>1</integer>
+               </dict>
+       </array>
+       <key>ModificationDate</key>
+       <string>2012-01-24 17:14:19 -0500</string>
+       <key>Modifier</key>
+       <string>classic</string>
+       <key>NotesVisible</key>
+       <string>NO</string>
+       <key>Orientation</key>
+       <integer>2</integer>
+       <key>OriginVisible</key>
+       <string>NO</string>
+       <key>OutlineStyle</key>
+       <string>Basic</string>
+       <key>PageBreaks</key>
+       <string>YES</string>
+       <key>PrintInfo</key>
+       <dict>
+               <key>NSBottomMargin</key>
+               <array>
+                       <string>coded</string>
+                       <string>BAtzdHJlYW10eXBlZIHoA4QBQISEhAhOU051bWJlcgCEhAdOU1ZhbHVlAISECE5TT2JqZWN0AIWEASqEhAFklwCG</string>
+               </array>
+               <key>NSLeftMargin</key>
+               <array>
+                       <string>coded</string>
+                       <string>BAtzdHJlYW10eXBlZIHoA4QBQISEhAhOU051bWJlcgCEhAdOU1ZhbHVlAISECE5TT2JqZWN0AIWEASqEhAFklwCG</string>
+               </array>
+               <key>NSPaperSize</key>
+               <array>
+                       <string>size</string>
+                       <string>{612, 792}</string>
+               </array>
+               <key>NSRightMargin</key>
+               <array>
+                       <string>coded</string>
+                       <string>BAtzdHJlYW10eXBlZIHoA4QBQISEhAhOU051bWJlcgCEhAdOU1ZhbHVlAISECE5TT2JqZWN0AIWEASqEhAFklwCG</string>
+               </array>
+               <key>NSTopMargin</key>
+               <array>
+                       <string>coded</string>
+                       <string>BAtzdHJlYW10eXBlZIHoA4QBQISEhAhOU051bWJlcgCEhAdOU1ZhbHVlAISECE5TT2JqZWN0AIWEASqEhAFklwCG</string>
+               </array>
+       </dict>
+       <key>ReadOnly</key>
+       <string>NO</string>
+       <key>RowAlign</key>
+       <integer>1</integer>
+       <key>RowSpacing</key>
+       <real>36</real>
+       <key>SheetTitle</key>
+       <string>Canvas 1</string>
+       <key>SmartAlignmentGuidesActive</key>
+       <string>YES</string>
+       <key>SmartDistanceGuidesActive</key>
+       <string>YES</string>
+       <key>UniqueID</key>
+       <integer>1</integer>
+       <key>UseEntirePage</key>
+       <true/>
+       <key>VPages</key>
+       <integer>1</integer>
+       <key>WindowInfo</key>
+       <dict>
+               <key>CurrentSheet</key>
+               <string>0</string>
+               <key>DrawerOpen</key>
+               <false/>
+               <key>DrawerTab</key>
+               <string>Outline</string>
+               <key>DrawerWidth</key>
+               <real>209</real>
+               <key>FitInWindow</key>
+               <false/>
+               <key>Frame</key>
+               <string>{{335, 186}, {760, 817}}</string>
+               <key>ShowRuler</key>
+               <false/>
+               <key>ShowStatusBar</key>
+               <true/>
+               <key>VisibleRegion</key>
+               <string>{{-84, 0}, {745, 703}}</string>
+               <key>Zoom</key>
+               <string>1</string>
+       </dict>
+</dict>
+</plist>

diff --git a/docs/build/ops.rst b/docs/build/ops.rst
index dc2cc4bfc72b989a0c4d44e6a17158bfa2ab3149..e9d5bf0c9272e706f6206f6846a07b40961afc7c 100644 (file)
--- a/docs/build/ops.rst
+++ b/docs/build/ops.rst
@@ -10,22 +10,28 @@ The directives here are used within user-defined migration files,
 within the ``upgrade()`` and ``downgrade()`` functions, as well as 
 any functions further invoked by those.  
 
-A key design philosophy to the :mod:`alembic.op` functions is that
+All directives exist as methods on a class called :class:`.Operations`.
+When migration scripts are run, this object is made available
+to the script via the ``alembic.op`` datamember, which is
+a *proxy* to an actual instance of :class:`.Operations`.
+
+A key design philosophy to the :mod:`alembic.operations` methods is that
 to the greatest degree possible, they internally generate the 
 appropriate SQLAlchemy metadata, typically involving
 :class:`~sqlalchemy.schema.Table` and :class:`~sqlalchemy.schema.Constraint`
 objects.  This so that migration instructions can be 
 given in terms of just the string names and/or flags involved.   
 The exceptions to this
-rule include the :func:`.op.add_column` and :func:`.op.create_table`
+rule include the :meth:`~.Operations.add_column` and :func:`~.Operations.create_table`
 directives, which require full :class:`~sqlalchemy.schema.Column`
 objects, though the table metadata is still generated here.
 
-The functions here all require that a :class:`.Context` has been
-configured within the ``env.py`` script.  Under normal circumstances
-this is always the case, as the migration scripts are invoked via
-the :func:`.context.run_migrations` function which ultimately
-is derived from the :class:`.Context` object.
+The functions here all require that a :class:`.MigrationContext` has been
+configured within the ``env.py`` script first, which is typically
+via :meth:`.EnvironmentContext.configure`.   Under normal
+circumstances they are called from an actual migration script, which
+itself would be invoked by the :meth:`.EnvironmentContext.run_migrations`
+method.
 
 
 .. automodule:: alembic.operations