- move to 0.3 as we are changing APIrel_0_3_0

- [general] The focus of 0.3 is to clean up
  and more fully document the public API of Alembic,
  including better accessors on the MigrationContext
  and ScriptDirectory objects.  Methods that are
  not considered to be public on these objects have
  been underscored, and methods which should be public
  have been cleaned up and documented, including:

    MigrationContext.get_current_revision()
    ScriptDirectory.iterate_revisions()
    ScriptDirectory.get_current_head()
    ScriptDirectory.get_heads()
    ScriptDirectory.get_base()
    ScriptDirectory.generate_revision()

- [feature] Added a bit of autogenerate to the
  public API in the form of the function
  alembic.autogenerate.compare_metadata.

17 files changed, 581 insertions, 145 deletions

diff --git a/CHANGES b/CHANGES
index 7950a13..001bd6a 100644
--- a/CHANGES
+++ b/CHANGES
@@ -1,3 +1,24 @@
+0.3.0
+=====
+- [general] The focus of 0.3 is to clean up 
+  and more fully document the public API of Alembic,
+  including better accessors on the MigrationContext
+  and ScriptDirectory objects.  Methods that are
+  not considered to be public on these objects have
+  been underscored, and methods which should be public
+  have been cleaned up and documented, including:
+
+    MigrationContext.get_current_revision()
+    ScriptDirectory.iterate_revisions()
+    ScriptDirectory.get_current_head()
+    ScriptDirectory.get_heads()
+    ScriptDirectory.get_base()
+    ScriptDirectory.generate_revision()
+
+- [feature] Added a bit of autogenerate to the 
+  public API in the form of the function
+  alembic.autogenerate.compare_metadata.
+
 0.2.2
 =====
 - [feature] Informative error message when op.XYZ
@@ -196,7 +217,7 @@
   into a new schema.  For dev environments, the 
   dev installer should be building the whole DB from 
   scratch.  Or just use Postgresql, which is a much
-  better database for non-trivial schemas.  
+  better database for non-trivial schemas.
   Requests for full ALTER support on SQLite should be 
   reported to SQLite's bug tracker at 
   http://www.sqlite.org/src/wiki?name=Bug+Reports,
@@ -258,7 +279,7 @@
   by key, etc. for full support here.
 
 - Support for tables in remote schemas, 
-  i.e. "schemaname.tablename", is very poor.   
+  i.e. "schemaname.tablename", is very poor.
   Missing "schema" behaviors should be 
   reported as tickets, though in the author's
   experience, migrations typically proceed only
diff --git a/alembic/__init__.py b/alembic/__init__.py
index 7c50518..c1c253c 100644
--- a/alembic/__init__.py
+++ b/alembic/__init__.py
@@ -1,6 +1,6 @@
 from os import path
 
-__version__ = '0.2.2'
+__version__ = '0.3.0'
 
 package_dir = path.abspath(path.dirname(__file__))
 
diff --git a/alembic/autogenerate.py b/alembic/autogenerate.py
index ba0ecd9..5fa856c 100644
--- a/alembic/autogenerate.py
+++ b/alembic/autogenerate.py
@@ -11,10 +11,95 @@ import logging
 log = logging.getLogger(__name__)
 
 ###################################################
-# top level
+# public
+def compare_metadata(context, metadata):
+    """Compare a database schema to that given in a :class:`~sqlalchemy.schema.MetaData`
+    instance.
+    
+    The database connection is presented in the context
+    of a :class:`.MigrationContext` object, which 
+    provides database connectivity as well as optional
+    comparison functions to use for datatypes and
+    server defaults - see the "autogenerate" arguments
+    at :meth:`.EnvironmentContext.configure`
+    for details on these.
+    
+    The return format is a list of "diff" directives,
+    each representing individual differences::
+
+        from alembic.migration import MigrationContext
+        from alembic.autogenerate import compare_metadata
+        from sqlalchemy.schema import SchemaItem
+        from sqlalchemy.types import TypeEngine
+        from sqlalchemy import (create_engine, MetaData, Column, 
+                Integer, String, Table)
+        import pprint
+
+        engine = create_engine("sqlite://")
+
+        engine.execute('''
+            create table foo (
+                id integer not null primary key,
+                old_data varchar,
+                x integer
+            )''')
+
+        engine.execute('''
+            create table bar (
+                data varchar
+            )''')
+
+        metadata = MetaData()
+        Table('foo', metadata, 
+            Column('id', Integer, primary_key=True),
+            Column('data', Integer),
+            Column('x', Integer, nullable=False)
+        )
+        Table('bat', metadata, 
+            Column('info', String)
+        )
+
+        mc = MigrationContext.configure(engine.connect())
+
+        diff = compare_metadata(mc, metadata)
+        pprint.pprint(diff, indent=2, width=20)
+    
+    Output::
+    
+        [ ( 'add_table',
+            Table('bat', MetaData(bind=None), Column('info', String(), table=<bat>), schema=None)),
+          ( 'remove_table',
+            Table(u'bar', MetaData(bind=None), Column(u'data', VARCHAR(), table=<bar>), schema=None)),
+          ( 'add_column',
+            'foo',
+            Column('data', Integer(), table=<foo>)),
+          ( 'remove_column',
+            'foo',
+            Column(u'old_data', VARCHAR(), table=None)),
+          [ ( 'modify_nullable',
+              'foo',
+              u'x',
+              { 'existing_server_default': None,
+                'existing_type': INTEGER()},
+              True,
+              False)]]
+    
+    
+    :param context: a :class:`.MigrationContext`
+     instance.
+    :param metadata: a :class:`~sqlalchemy.schema.MetaData` 
+     instance.
+    
+    """
+    autogen_context, connection = _autogen_context(context, None)
+    diffs = []
+    _produce_net_changes(connection, metadata, diffs, autogen_context)
+    return diffs
 
+###################################################
+# top level
 
-def produce_migration_diffs(context, template_args, imports):
+def _produce_migration_diffs(context, template_args, imports):
     opts = context.opts
     metadata = opts['target_metadata']
     if metadata is None:
@@ -24,15 +109,9 @@ def produce_migration_diffs(context, template_args, imports):
                 "a MetaData object to the context." % (
                     context.script.env_py_location
                 ))
-    connection = context.bind
+    autogen_context, connection = _autogen_context(context, imports)
+
     diffs = []
-    autogen_context = {
-        'imports':imports,
-        'connection':connection,
-        'dialect':connection.dialect,
-        'context':context,
-        'opts':opts
-    }
     _produce_net_changes(connection, metadata, diffs, autogen_context)
     template_args[opts['upgrade_token']] = \
             _indent(_produce_upgrade_commands(diffs, autogen_context))
@@ -40,6 +119,16 @@ def produce_migration_diffs(context, template_args, imports):
             _indent(_produce_downgrade_commands(diffs, autogen_context))
     template_args['imports'] = "\n".join(sorted(imports))
 
+def _autogen_context(context, imports):
+    opts = context.opts
+    connection = context.bind
+    return {
+        'imports':imports,
+        'connection':connection,
+        'dialect':connection.dialect,
+        'context':context,
+        'opts':opts
+    }, connection
 
 def _indent(text):
     text = "### commands auto generated by Alembic - please adjust! ###\n" + text
@@ -178,7 +267,7 @@ def _compare_type(tname, cname, conn_col,
         log.info("Column '%s.%s' has no type within the model; can't compare" % (tname, cname))
         return
 
-    isdiff = autogen_context['context'].compare_type(conn_col, metadata_col)
+    isdiff = autogen_context['context']._compare_type(conn_col, metadata_col)
 
     if isdiff:
 
@@ -203,7 +292,7 @@ def _compare_server_default(tname, cname, conn_col, metadata_col,
     if conn_col_default is None and metadata_default is None:
         return False
     rendered_metadata_default = _render_server_default(metadata_default, autogen_context)
-    isdiff = autogen_context['context'].compare_server_default(
+    isdiff = autogen_context['context']._compare_server_default(
                         conn_col, metadata_col,
                         rendered_metadata_default
                     )
diff --git a/alembic/command.py b/alembic/command.py
index 18b421c..ed7b830 100644
--- a/alembic/command.py
+++ b/alembic/command.py
@@ -1,7 +1,7 @@
 from alembic.script import ScriptDirectory
-from alembic import util, ddl, autogenerate as autogen, environment
+from alembic.environment import EnvironmentContext
+from alembic import util, ddl, autogenerate as autogen
 import os
-import functools
 
 def list_templates(config):
     """List available templates"""
@@ -44,14 +44,14 @@ def init(config, directory, template='generic'):
             if os.access(config_file, os.F_OK):
                 util.msg("File %s already exists, skipping" % config_file)
             else:
-                script.generate_template(
+                script._generate_template(
                     os.path.join(template_dir, file_),
                     config_file,
                     script_location=directory
                 )
         else:
             output_file = os.path.join(directory, file_)
-            script.copy_file(
+            script._copy_file(
                 os.path.join(template_dir, file_), 
                 output_file
             )
@@ -68,18 +68,18 @@ def revision(config, message=None, autogenerate=False):
     if autogenerate:
         util.requires_07("autogenerate")
         def retrieve_migrations(rev, context):
-            if script._get_rev(rev) is not script._get_rev("head"):
+            if script.get_revision(rev) is not script.get_revision("head"):
                 raise util.CommandError("Target database is not up to date.")
-            autogen.produce_migration_diffs(context, template_args, imports)
+            autogen._produce_migration_diffs(context, template_args, imports)
             return []
 
-        with environment.configure(
+        with EnvironmentContext(
             config,
             script,
             fn = retrieve_migrations
         ):
             script.run_env()
-    script.generate_rev(util.rev_id(), message, **template_args)
+    script.generate_revision(util.rev_id(), message, **template_args)
 
 
 def upgrade(config, revision, sql=False, tag=None):
@@ -92,10 +92,14 @@ def upgrade(config, revision, sql=False, tag=None):
         if not sql:
             raise util.CommandError("Range revision not allowed")
         starting_rev, revision = revision.split(':', 2)
-    with environment.configure(
+
+    def upgrade(rev, context):
+        return script._upgrade_revs(revision, rev)
+
+    with EnvironmentContext(
         config,
         script,
-        fn = functools.partial(script.upgrade_from, revision),
+        fn = upgrade,
         as_sql = sql,
         starting_rev = starting_rev,
         destination_rev = revision,
@@ -114,10 +118,13 @@ def downgrade(config, revision, sql=False, tag=None):
             raise util.CommandError("Range revision not allowed")
         starting_rev, revision = revision.split(':', 2)
 
-    with environment.configure(
+    def downgrade(rev, context):
+        return script._downgrade_revs(revision, rev)
+
+    with EnvironmentContext(
         config,
         script,
-        fn = functools.partial(script.downgrade_to, revision),
+        fn = downgrade,
         as_sql = sql,
         starting_rev = starting_rev,
         destination_rev = revision,
@@ -143,7 +150,7 @@ def branches(config):
             for rev in sc.nextrev:
                 print "%s -> %s" % (
                     " " * len(str(sc.down_revision)),
-                    script._get_rev(rev)
+                    script.get_revision(rev)
                 )
 
 def current(config):
@@ -154,10 +161,10 @@ def current(config):
         print "Current revision for %s: %s" % (
                             util.obfuscate_url_pw(
                                 context.connection.engine.url),
-                            script._get_rev(rev))
+                            script.get_revision(rev))
         return []
 
-    with environment.configure(
+    with EnvironmentContext(
         config,
         script,
         fn = display_version
@@ -174,12 +181,12 @@ def stamp(config, revision, sql=False, tag=None):
             current = False
         else:
             current = context._current_rev()
-        dest = script._get_rev(revision)
+        dest = script.get_revision(revision)
         if dest is not None:
             dest = dest.revision
         context._update_current_rev(current, dest)
         return []
-    with environment.configure(
+    with EnvironmentContext(
         config, 
         script,
         fn = do_stamp,
diff --git a/alembic/config.py b/alembic/config.py
index 998bb85..92e0921 100644
--- a/alembic/config.py
+++ b/alembic/config.py
@@ -32,6 +32,7 @@ class Config(object):
     
         from alembic.config import Config
         alembic_cfg = Config()
+        alembic_cfg.set_main_option("script_location", "myapp:migrations")
         alembic_cfg.set_main_option("url", "postgresql://foo/bar")
         alembic_cfg.set_section_option("mysection", "foo", "bar")
 
diff --git a/alembic/environment.py b/alembic/environment.py
index 231aceb..52c353a 100644
--- a/alembic/environment.py
+++ b/alembic/environment.py
@@ -13,6 +13,50 @@ class EnvironmentContext(object):
     :class:`.EnvironmentContext` is available via the 
     ``alembic.context`` datamember.
     
+    :class:`.EnvironmentContext` is also 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
+        from alembic.script import ScriptDirectory
+        
+        config = Config()
+        config.set_main_option("script_location", "myapp:migrations")
+        script = ScriptDirectory.from_config(config)
+        
+        def my_function(rev, context):
+            '''do something with revision "rev", which
+            will be the current database revision, 
+            and "context", which is the MigrationContext
+            that the env.py will create'''
+            
+        with EnvironmentContext(
+            config,
+            script,
+            fn = my_function,
+            as_sql = False,
+            starting_rev = 'base',
+            destination_rev = 'head',
+            tag = "sometag"
+        ):
+            script.run_env()
+    
+    The above script will invoke the ``env.py`` script
+    within the migration environment.  If and when ``env.py``
+    calls :meth:`.MigrationContext.run_migrations`, the
+    ``my_function()`` function above will be called 
+    by the :class:`.MigrationContext`, given the context
+    itself as well as the current revision in the database.
+    
+    .. note::
+
+        For most API usages other than full blown
+        invocation of migration scripts, the :class:`.MigrationContext`
+        and :class:`.ScriptDirectory` objects can be created and
+        used directly.  The :class:`.EnvironmentContext` object 
+        is *only* needed when you need to actually invoke the
+        ``env.py`` module present in the migration environment.
+    
     """
 
     _migration_context = None
@@ -31,6 +75,15 @@ class EnvironmentContext(object):
     """
 
     def __init__(self, config, script, **kw):
+        """Construct a new :class:`.EnvironmentContext`.
+        
+        :param config: a :class:`.Config` instance.
+        :param script: a :class:`.ScriptDirectory` instance.
+        :param \**kw: keyword options that will be ultimately
+         passed along to the :class:`.MigrationContext` when
+         :meth:`.EnvironmentContext.configure` is called.
+         
+        """
         self.config = config
         self.script = script
         self.context_opts = kw
@@ -495,4 +548,3 @@ class EnvironmentContext(object):
     def get_impl(self):
         return self.get_context().impl
 
-configure = EnvironmentContext
diff --git a/alembic/migration.py b/alembic/migration.py
index d610b3b..80e53b2 100644
--- a/alembic/migration.py
+++ b/alembic/migration.py
@@ -15,31 +15,48 @@ _version = Table('alembic_version', _meta,
             )
 
 class MigrationContext(object):
-    """Represent the state made available to a migration script,
-    or otherwise a series of migration operations.
+    """Represent the database state made available to a migration 
+    script.
 
-    Mediates the relationship between an ``env.py`` environment script, 
-    a :class:`.ScriptDirectory` instance, and a :class:`.DefaultImpl` instance.
-
-    The :class:`.MigrationContext` that's established for a 
-    duration of a migration command is available via the 
+    :class:`.MigrationContext` is the front end to an actual
+    database connection, or alternatively a string output
+    stream given a particular database dialect,
+    from an Alembic perspective.
+    
+    When inside the ``env.py`` script, the :class:`.MigrationContext` 
+    is available via the 
     :meth:`.EnvironmentContext.get_context` method,
     which is available at ``alembic.context``::
     
+        # from within env.py script
         from alembic import context
         migration_context = context.get_context()
     
-    A :class:`.MigrationContext` can be created programmatically
-    for usage outside of the usual Alembic migrations flow,
-    using the :meth:`.MigrationContext.configure` method::
+    For usage outside of an ``env.py`` script, such as for
+    utility routines that want to check the current version
+    in the database, the :meth:`.MigrationContext.configure` 
+    method to create new :class:`.MigrationContext` objects.
+    For example, to get at the current revision in the 
+    database using :meth:`.MigrationContext.get_current_revision`::
     
-        conn = myengine.connect()
-        ctx = MigrationContext.configure(conn)
+        # in any application, outside of an env.py script
+        from alembic.migration import MigrationContext
+        from sqlalchemy import create_engine
+        
+        engine = create_engine("postgresql://mydatabase")
+        conn = engine.connect()
+        
+        context = MigrationContext.configure(conn)
+        current_rev = context.get_current_revision()
     
-    The above context can then be used to produce
+    The above context can also be used to produce
     Alembic migration operations with an :class:`.Operations`
-    instance.
-    
+    instance::
+
+        # in any application, outside of the normal Alembic environment
+        from alembic.operations import Operations
+        op = Operations(context)
+        op.alter_column("mytable", "somecolumn", nullable=True)
 
     """
     def __init__(self, dialect, connection, opts):
@@ -119,7 +136,15 @@ class MigrationContext(object):
         return MigrationContext(dialect, connection, opts)
 
 
-    def _current_rev(self):
+    def get_current_revision(self):
+        """Return the current revision, usually that which is present
+        in the ``alembic_version`` table in the database.
+        
+        If this :class:`.MigrationContext` was configured in "offline"
+        mode, that is with ``as_sql=True``, the ``starting_rev`` 
+        parameter is returned instead, if any.
+        
+        """
         if self.as_sql:
             return self._start_from_rev
         else:
@@ -130,6 +155,9 @@ class MigrationContext(object):
             _version.create(self.connection, checkfirst=True)
         return self.connection.scalar(_version.select())
 
+    _current_rev = get_current_revision
+    """The 0.2 method name, for backwards compat."""
+
     def _update_current_rev(self, old, new):
         if old == new:
             return
@@ -145,11 +173,30 @@ class MigrationContext(object):
                     )
 
     def run_migrations(self, **kw):
-
+        """Run the migration scripts established for this :class:`.MigrationContext`, 
+        if any.
+        
+        The commands in :mod:`alembic.command` will set up a function
+        that is ultimately passed to the :class:`.MigrationContext`
+        as the ``fn`` argument.  This function represents the "work" 
+        that will be done when :meth:`.MigrationContext.run_migrations`
+        is called, typically from within the ``env.py`` script of the
+        migration environment.  The "work function" then provides an iterable
+        of version callables and other version information which 
+        in the case of the ``upgrade`` or ``downgrade`` commands are the
+        list of version scripts to invoke.  Other commands yield nothing,
+        in the case that a command wants to run some other operation
+        against the database such as the ``current`` or ``stamp`` commands.
+        
+        :param \**kw: keyword arguments here will be passed to each 
+         migration callable, that is the ``upgrade()`` or ``downgrade()``
+         method within revision scripts.
+         
+        """
         current_rev = rev = False
         self.impl.start_migrations()
         for change, prev_rev, rev in self._migrations_fn(
-                                        self._current_rev(),
+                                        self.get_current_revision(),
                                         self):
             if current_rev is False:
                 current_rev = prev_rev
@@ -174,6 +221,14 @@ class MigrationContext(object):
                 _version.drop(self.connection)
 
     def execute(self, sql):
+        """Execute a SQL construct or string statement.
+        
+        The underlying execution mechanics are used, that is
+        if this is "offline mode" the SQL is written to the 
+        output buffer, otherwise the SQL is emitted on
+        the current SQLAlchemy connection.
+
+        """
         self.impl._exec(sql)
 
     def _stdout_connection(self, connection):
@@ -203,7 +258,7 @@ class MigrationContext(object):
         """
         return self.connection
 
-    def compare_type(self, inspector_column, metadata_column):
+    def _compare_type(self, inspector_column, metadata_column):
         if self._user_compare_type is False:
             return False
 
@@ -222,7 +277,7 @@ class MigrationContext(object):
                                     inspector_column, 
                                     metadata_column)
 
-    def compare_server_default(self, inspector_column, 
+    def _compare_server_default(self, inspector_column, 
                             metadata_column, 
                             rendered_metadata_default):
 
diff --git a/alembic/script.py b/alembic/script.py
index 952b572..bef7dfb 100644
--- a/alembic/script.py
+++ b/alembic/script.py
@@ -15,7 +15,22 @@ _default_file_template = "%(rev)s_%(slug)s"
 
 class ScriptDirectory(object):
     """Provides operations upon an Alembic script directory.
-    
+
+    This object is useful to get information as to current revisions,
+    most notably being able to get at the "head" revision, for schemes
+    that want to test if the current revision in the database is the most
+    recent::
+
+        from alembic.script import ScriptDirectory
+        from alembic.config import Config
+        config = Config()
+        config.set_main_option("script_location", "myapp:migrations")
+        script = ScriptDirectory.from_config(config)
+
+        head_revision = script.get_current_head()
+
+
+
     """
     def __init__(self, dir, file_template=_default_file_template):
         self.dir = dir
@@ -29,6 +44,13 @@ class ScriptDirectory(object):
 
     @classmethod
     def from_config(cls, config):
+        """Produce a new :class:`.ScriptDirectory` given a :class:`.Config` 
+        instance.
+
+        The :class:`.Config` need only have the ``script_location`` key
+        present.
+
+        """
         return ScriptDirectory(
                     util.coerce_resource_to_filename(
                         config.get_main_option('script_location')
@@ -45,23 +67,25 @@ class ScriptDirectory(object):
         with leaf nodes being heads.
 
         """
-        heads = set(self._get_heads())
-        base = self._get_rev("base")
+        heads = set(self.get_heads())
+        base = self.get_revision("base")
         while heads:
             todo = set(heads)
             heads = set()
             for head in todo:
                 if head in heads:
                     break
-                for sc in self._revs(head, base):
+                for sc in self.iterate_revisions(head, base):
                     if sc.is_branch_point and sc.revision not in todo:
                         heads.add(sc.revision)
                         break
                     else:
                         yield sc
 
-    def _get_rev(self, id_):
-        id_ = self._as_rev_number(id_)
+    def get_revision(self, id_):
+        """Return the :class:`.Script` instance with the given rev id."""
+
+        id_ = self.as_revision_number(id_)
         try:
             return self._revision_map[id_]
         except KeyError:
@@ -80,16 +104,34 @@ class ScriptDirectory(object):
             else:
                 return self._revision_map[revs[0]]
 
-    def _as_rev_number(self, id_):
+    _get_rev = get_revision
+
+    def as_revision_number(self, id_):
+        """Convert a symbolic revision, i.e. 'head' or 'base', into
+        an actual revision number."""
+
         if id_ == 'head':
-            id_ = self._current_head()
+            id_ = self.get_current_head()
         elif id_ == 'base':
             id_ = None
         return id_
 
-    def _revs(self, upper, lower):
-        lower = self._get_rev(lower)
-        upper = self._get_rev(upper)
+    _as_rev_number = as_revision_number
+
+    def iterate_revisions(self, upper, lower):
+        """Iterate through script revisions, starting at the given 
+        upper revision identifier and ending at the lower.
+
+        The traversal uses strictly the `down_revision`
+        marker inside each migration script, so
+        it is a requirement that upper >= lower,
+        else you'll get nothing back.
+
+        The iterator yields :class:`.Script` objects.
+
+        """
+        lower = self.get_revision(lower)
+        upper = self.get_revision(upper)
         script = upper
         while script != lower:
             yield script
@@ -99,15 +141,15 @@ class ScriptDirectory(object):
                 raise util.CommandError(
                         "Couldn't find revision %s" % downrev)
 
-    def upgrade_from(self, destination, current_rev, context):
-        revs = self._revs(destination, current_rev)
+    def _upgrade_revs(self, destination, current_rev):
+        revs = self.iterate_revisions(destination, current_rev)
         return [
             (script.module.upgrade, script.down_revision, script.revision)
             for script in reversed(list(revs))
             ]
 
-    def downgrade_to(self, destination, current_rev, context):
-        revs = self._revs(current_rev, destination)
+    def _downgrade_revs(self, destination, current_rev):
+        revs = self.iterate_revisions(current_rev, destination)
         return [
             (script.module.downgrade, script.revision, script.down_revision)
             for script in revs
@@ -115,12 +157,12 @@ class ScriptDirectory(object):
 
     def run_env(self):
         """Run the script environment.
-        
+
         This basically runs the ``env.py`` script present
         in the migration environment.   It is called exclusively
         by the command functions in :mod:`alembic.command`.
-        
-        
+
+
         """
         util.load_python_file(self.dir, 'env.py')
 
@@ -132,7 +174,7 @@ class ScriptDirectory(object):
     def _revision_map(self):
         map_ = {}
         for file_ in os.listdir(self.versions):
-            script = Script.from_filename(self.versions, file_)
+            script = Script._from_filename(self.versions, file_)
             if script is None:
                 continue
             if script.revision in map_:
@@ -158,8 +200,16 @@ class ScriptDirectory(object):
         )
         return os.path.join(self.versions, filename)
 
-    def _current_head(self):
-        current_heads = self._get_heads()
+    def get_current_head(self):
+        """Return the current head revision.
+
+        If the script directory has multiple heads
+        due to branching, an error is raised.
+
+        Returns a string revision number.
+
+        """
+        current_heads = self.get_heads()
         if len(current_heads) > 1:
             raise util.CommandError("Only a single head supported so far...")
         if current_heads:
@@ -167,22 +217,45 @@ class ScriptDirectory(object):
         else:
             return None
 
-    def _get_heads(self):
+    _current_head = get_current_head
+    """the 0.2 name, for backwards compat."""
+
+    def get_heads(self):
+        """Return all "head" revisions as strings.
+
+        Returns a list of string revision numbers.
+
+        This is normally a list of length one,
+        unless branches are present.  The
+        :meth:`.ScriptDirectory.get_current_head()` method
+        can be used normally when a script directory
+        has only one head.
+
+        """
         heads = []
         for script in self._revision_map.values():
             if script and script.is_head:
                 heads.append(script.revision)
         return heads
 
-    def _get_origin(self):
+    def get_base(self):
+        """Return the "base" revision as a string.
+
+        This is the revision number of the script that
+        has a ``down_revision`` of None.
+
+        Behavior is not defined if more than one script
+        has a ``down_revision`` of None.
+
+        """
         for script in self._revision_map.values():
             if script.down_revision is None \
                 and script.revision in self._revision_map:
-                return script
+                return script.revision
         else:
             return None
 
-    def generate_template(self, src, dest, **kw):
+    def _generate_template(self, src, dest, **kw):
         util.status("Generating %s" % os.path.abspath(dest),
             util.template_to_file,
             src, 
@@ -190,15 +263,33 @@ class ScriptDirectory(object):
             **kw
         )
 
-    def copy_file(self, src, dest):
+    def _copy_file(self, src, dest):
         util.status("Generating %s" % os.path.abspath(dest), 
                     shutil.copy, 
                     src, dest)
 
-    def generate_rev(self, revid, message, refresh=False, **kw):
-        current_head = self._current_head()
+    def generate_revision(self, revid, message, refresh=False, **kw):
+        """Generate a new revision file.
+
+        This runs the ``script.py.mako`` template, given
+        template arguments, and creates a new file.
+
+        :param revid: String revision id.  Typically this
+         comes from ``alembic.util.rev_id()``.
+        :param message: the revision message, the one passed
+         by the -m argument to the ``revision`` command.
+        :param refresh: when True, the in-memory state of this
+         :class:`.ScriptDirectory` will be updated with a new
+         :class:`.Script` instance representing the new revision;
+         the :class:`.Script` instance is returned.
+         If False, the file is created but the state of the
+         :class:`.ScriptDirectory` is unmodified; ``None``
+         is returned.
+
+        """
+        current_head = self.get_current_head()
         path = self._rev_path(revid, message)
-        self.generate_template(
+        self._generate_template(
             os.path.join(self.dir, "script.py.mako"),
             path,
             up_revision=str(revid),
@@ -208,18 +299,24 @@ class ScriptDirectory(object):
             **kw
         )
         if refresh:
-            script = Script.from_path(path)
+            script = Script._from_path(path)
             self._revision_map[script.revision] = script
             if script.down_revision:
                 self._revision_map[script.down_revision].\
                         add_nextrev(script.revision)
             return script
         else:
-            return revid
+            return None
 
 
 class Script(object):
-    """Represent a single revision file in a ``versions/`` directory."""
+    """Represent a single revision file in a ``versions/`` directory.
+
+    The :class:`.Script` instance is returned by methods
+    such as :meth:`.ScriptDirectory.iterate_revisions`.
+
+    """
+
     nextrev = frozenset()
 
     def __init__(self, module, rev_id, path):
@@ -228,8 +325,21 @@ class Script(object):
         self.path = path
         self.down_revision = getattr(module, 'down_revision', None)
 
+    revision = None
+    """The string revision number for this :class:`.Script` instance."""
+
+    module = None
+    """The Python module representing the actual script itself."""
+
+    path = None
+    """Filesystem path of the script."""
+
+    down_revision = None
+    """The ``down_revision`` identifier within the migration script."""
+
     @property
     def doc(self):
+        """Return the docstring given in the script."""
         return re.split(r"\n\n", self.module.__doc__)[0]
 
     def add_nextrev(self, rev):
@@ -237,10 +347,25 @@ class Script(object):
 
     @property
     def is_head(self):
+        """Return True if this :class:`.Script` is a 'head' revision.
+
+        This is determined based on whether any other :class:`.Script`
+        within the :class:`.ScriptDirectory` refers to this
+        :class:`.Script`.   Multiple heads can be present.
+
+        """
         return not bool(self.nextrev)
 
     @property
     def is_branch_point(self):
+        """Return True if this :class:`.Script` is a branch point.
+
+        A branchpoint is defined as a :class:`.Script` which is referred
+        to by more than one succeeding :class:`.Script`, that is more
+        than one :class:`.Script` has a `down_revision` identifier pointing
+        here.
+
+        """
         return len(self.nextrev) > 1
 
     def __str__(self):
@@ -252,12 +377,12 @@ class Script(object):
                         self.doc)
 
     @classmethod
-    def from_path(cls, path):
+    def _from_path(cls, path):
         dir_, filename = os.path.split(path)
-        return cls.from_filename(dir_, filename)
+        return cls._from_filename(dir_, filename)
 
     @classmethod
-    def from_filename(cls, dir_, filename):
+    def _from_filename(cls, dir_, filename):
         m = _rev_file.match(filename)
         if not m:
             return None
diff --git a/docs/build/api.rst b/docs/build/api.rst
index def71a3..de8f37e 100644
--- a/docs/build/api.rst
+++ b/docs/build/api.rst
@@ -1,3 +1,5 @@
+.. _api:
+
 ===========
 API Details
 ===========
@@ -40,26 +42,36 @@ 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 Environment Context
+=======================
 
-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 :class:`.EnvironmentContext` class provides most of the
+API used within an ``env.py`` script.  Within ``env.py``, 
+the instantated :class:`.EnvironmentContext` is made available
+via a special *proxy module* called ``alembic.context``.   That is,
+you can import ``alembic.context`` like a regular Python module,
+and each name you call upon it is ultimately routed towards the
+current :class:`.EnvironmentContext` in use.
 
 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
-
 .. automodule:: alembic.environment
     :members:
 
+The Migration Context
+=====================
+
 .. automodule:: alembic.migration
     :members:
 
+The Operations Object
+=====================
+
+Within migration scripts, actual database migration operations are handled
+via an instance of :class:`.Operations`.    See :ref:`ops` for an overview
+of this object.
+
 Commands
 =========
 
@@ -75,31 +87,68 @@ object, as in::
     alembic_cfg = Config("/path/to/yourapp/alembic.ini")
     command.upgrade(alembic_cfg, "head")
 
+To write small API functions that make direct use of database and script directory
+information, rather than just running one of the built-in commands,
+use the :class:`.ScriptDirectory` and :class:`.MigrationContext`
+classes directly.
+
 .. currentmodule:: alembic.command
 
 .. automodule:: alembic.command
     :members:
-    :undoc-members:
 
 Configuration
 ==============
 
+The :class:`.Config` object represents the configuration 
+passed to the Alembic environment.  From an API usage perspective,
+it is needed for the following use cases:
+
+* to create a :class:`.ScriptDirectory`, which allows you to work
+  with the actual script files in a migration environment
+* to create an :class:`.EnvironmentContext`, which allows you to 
+  actually run the ``env.py`` module within the migration environment
+* to programatically run any of the commands in the :mod:`alembic.command`
+  module.
+
+The :class:`.Config` is *not* needed for these cases:
+
+* to instantiate a :class:`.MigrationContext` directly - this object
+  only needs a SQLAlchemy connection or dialect name.
+* to instantiate a :class:`.Operations` object - this object only
+  needs a :class:`.MigrationContext`.
+
 .. currentmodule:: alembic.config
 
 .. automodule:: alembic.config
     :members:
-    :undoc-members:
 
+Script Directory
+================
 
-Internals
-=========
+The :class:`.ScriptDirectory` object provides programmatic access
+to the Alembic version files present in the filesystem.
 
 .. automodule:: alembic.script
     :members:
-    :undoc-members:
+
+Autogeneration
+==============
+
+Alembic 0.3 introduces a small portion of the autogeneration system
+as a public API.
+
+.. autofunction:: alembic.autogenerate.compare_metadata
 
 DDL Internals
--------------
+=============
+
+These are some of the constructs used to generate migration
+instructions.  The APIs here build off of the :class:`sqlalchemy.schema.DDLElement`
+and :mod:`sqlalchemy.ext.compiler` systems.
+
+For programmatic usage of Alembic's migration directives, the easiest
+route is to use the higher level functions given by :mod:`alembic.operations`.
 
 .. automodule:: alembic.ddl
     :members:
@@ -114,7 +163,7 @@ DDL Internals
     :undoc-members:
 
 MySQL
-^^^^^
+-----
 
 .. automodule:: alembic.ddl.mysql
     :members:
@@ -122,7 +171,7 @@ MySQL
     :show-inheritance:
 
 MS-SQL
-^^^^^^
+------
 
 .. automodule:: alembic.ddl.mssql
     :members:
@@ -130,7 +179,7 @@ MS-SQL
     :show-inheritance:
 
 Postgresql
-^^^^^^^^^^
+----------
 
 .. automodule:: alembic.ddl.postgresql
     :members:
@@ -138,7 +187,7 @@ Postgresql
     :show-inheritance:
 
 SQLite
-^^^^^^
+------
 
 .. automodule:: alembic.ddl.sqlite
     :members:
diff --git a/docs/build/conf.py b/docs/build/conf.py
index 44dde4b..2bb0961 100644
--- a/docs/build/conf.py
+++ b/docs/build/conf.py
@@ -206,6 +206,8 @@ latex_documents = [
 
 #{'python': ('http://docs.python.org/3.2', None)}
 
+autoclass_content = "both"
+
 intersphinx_mapping = {
     'sqla':('http://www.sqlalchemy.org/docs/', None), 
 }
diff --git a/docs/build/front.rst b/docs/build/front.rst
index bbc6437..cee535c 100644
--- a/docs/build/front.rst
+++ b/docs/build/front.rst
@@ -50,6 +50,36 @@ is installed, in addition to other dependencies.  Alembic will work with
 SQLAlchemy as of version **0.6**, though with a limited featureset.  
 The latest version of SQLAlchemy within the **0.7** series is strongly recommended.
 
+Upgrading from Alembic 0.2 to 0.3
+=================================
+
+Alembic 0.3 is mostly identical to version 0.2 except for some API
+changes, allowing better programmatic access and less ambiguity 
+between public and private methods.   In particular:
+
+* :class:`.ScriptDirectory` now features these methods - the old
+  versions have been removed unless noted:
+
+  * :meth:`.ScriptDirectory.iterate_revisions()`
+  * :meth:`.ScriptDirectory.get_current_head()` (old name ``_current_head`` is available)
+  * :meth:`.ScriptDirectory.get_heads()`
+  * :meth:`.ScriptDirectory.get_base()`
+  * :meth:`.ScriptDirectory.generate_revision()`
+  * :meth:`.ScriptDirectory.get_revision()` (old name ``_get_rev`` is available)
+  * :meth:`.ScriptDirectory.as_revision_number()` (old name ``_as_rev_number`` is available)
+
+* :meth:`.MigrationContext.get_current_revision()` (old name ``_current_rev`` remains available)
+
+* Methods which have been made private include ``ScriptDirectory._copy_file()``,
+  ``ScriptDirectory._generate_template()``, ``ScriptDirectory._upgrade_revs()``,
+  ``ScriptDirectory._downgrade_revs()``.   ``autogenerate._produce_migration_diffs``.
+  It's pretty unlikely that end-user applications
+  were using these directly.
+
+See the newly cleaned up :ref:`api` documentation for what are hopefully clearly
+laid out use cases for API usage, particularly being able to get at the revision
+information in a database as well as a script directory.
+
 Upgrading from Alembic 0.1 to 0.2
 =================================
 
diff --git a/tests/__init__.py b/tests/__init__.py
index e8baba8..d3193ae 100644
--- a/tests/__init__.py
+++ b/tests/__init__.py
@@ -121,6 +121,10 @@ def ne_(a, b, msg=None):
     """Assert a != b, with repr messaging on failure."""
     assert a != b, msg or "%r == %r" % (a, b)
 
+def is_(a, b, msg=None):
+    """Assert a is b, with repr messaging on failure."""
+    assert a is b, msg or "%r is not %r" % (a, b)
+
 def assert_raises_message(except_cls, msg, callable_, *args, **kwargs):
     try:
         callable_(*args, **kwargs)
@@ -294,7 +298,7 @@ def write_script(scriptdir, rev_id, content):
     pyc_path = util.pyc_file_from_path(path)
     if os.access(pyc_path, os.F_OK):
         os.unlink(pyc_path)
-    script = Script.from_path(path)
+    script = Script._from_path(path)
     old = scriptdir._revision_map[script.revision]
     if old.down_revision != script.down_revision:
         raise Exception("Can't change down_revision "
@@ -309,7 +313,7 @@ def three_rev_fixture(cfg):
     c = util.rev_id()
 
     script = ScriptDirectory.from_config(cfg)
-    script.generate_rev(a, "revision a", refresh=True)
+    script.generate_revision(a, "revision a", refresh=True)
     write_script(script, a, """
 revision = '%s'
 down_revision = None
@@ -324,7 +328,7 @@ def downgrade():
 
 """ % a)
 
-    script.generate_rev(b, "revision b", refresh=True)
+    script.generate_revision(b, "revision b", refresh=True)
     write_script(script, b, """
 revision = '%s'
 down_revision = '%s'
@@ -339,7 +343,7 @@ def downgrade():
 
 """ % (b, a))
 
-    script.generate_rev(c, "revision c", refresh=True)
+    script.generate_revision(c, "revision c", refresh=True)
     write_script(script, c, """
 revision = '%s'
 down_revision = '%s'
diff --git a/tests/test_autogenerate.py b/tests/test_autogenerate.py
index e03ceea..9a1f6e7 100644
--- a/tests/test_autogenerate.py
+++ b/tests/test_autogenerate.py
@@ -129,7 +129,7 @@ class AutogenerateDiffTest(TestCase):
         diffs = []
         autogenerate._produce_net_changes(connection, metadata, diffs, 
                                           self.autogen_context)
-        
+
         eq_(
             diffs[0],
             ('add_table', metadata.tables['item'])
@@ -177,7 +177,7 @@ class AutogenerateDiffTest(TestCase):
             }
         )
         template_args = {}
-        autogenerate.produce_migration_diffs(context, template_args, set())
+        autogenerate._produce_migration_diffs(context, template_args, set())
         eq_(re.sub(r"u'", "'", template_args['upgrades']),
 """### commands auto generated by Alembic - please adjust! ###
     pass
@@ -192,7 +192,7 @@ class AutogenerateDiffTest(TestCase):
 
         metadata = self.m2
         template_args = {}
-        autogenerate.produce_migration_diffs(self.context, template_args, set())
+        autogenerate._produce_migration_diffs(self.context, template_args, set())
         eq_(re.sub(r"u'", "'", template_args['upgrades']),
 """### commands auto generated by Alembic - please adjust! ###
     op.create_table('item',
@@ -320,7 +320,7 @@ class AutogenerateDiffOrderTest(TestCase):
                 'sqlalchemy_module_prefix':'sa.'
             }
         )
-        
+
         connection = empty_context.bind
         cls.autogen_empty_context = {
             'imports':set(),
@@ -332,7 +332,7 @@ class AutogenerateDiffOrderTest(TestCase):
     @classmethod
     def teardown_class(cls):
         clear_staging_env()
-    
+
     def test_diffs_order(self):
         """
         Added in order to test that child tables(tables with FKs) are generated
@@ -342,10 +342,10 @@ class AutogenerateDiffOrderTest(TestCase):
         metadata = self.m4
         connection = self.empty_context.bind
         diffs = []
-        
+
         autogenerate._produce_net_changes(connection, metadata, diffs, 
                                           self.autogen_empty_context)
-        
+
         eq_(diffs[0][0], 'add_table')
         eq_(diffs[0][1].name, "parent")
         eq_(diffs[1][0], 'add_table')
diff --git a/tests/test_postgresql.py b/tests/test_postgresql.py
index 3eea778..38560ef 100644
--- a/tests/test_postgresql.py
+++ b/tests/test_postgresql.py
@@ -18,7 +18,7 @@ class PGOfflineEnumTest(TestCase):
         self.rid = rid = util.rev_id()
 
         self.script = script = ScriptDirectory.from_config(cfg)
-        script.generate_rev(rid, None, refresh=True)
+        script.generate_revision(rid, None, refresh=True)
 
     def tearDown(self):
         clear_staging_env()
diff --git a/tests/test_revision_create.py b/tests/test_revision_create.py
index 2bdca93..eaf1859 100644
--- a/tests/test_revision_create.py
+++ b/tests/test_revision_create.py
@@ -1,4 +1,4 @@
-from tests import clear_staging_env, staging_env, eq_, ne_
+from tests import clear_staging_env, staging_env, eq_, ne_, is_
 from alembic import util
 import os
 
@@ -16,20 +16,20 @@ def test_002_rev_ids():
     ne_(abc, def_)
 
 def test_003_heads():
-    eq_(env._get_heads(), [])
+    eq_(env.get_heads(), [])
 
 def test_004_rev():
-    script = env.generate_rev(abc, "this is a message", refresh=True)
+    script = env.generate_revision(abc, "this is a message", refresh=True)
     eq_(script.doc, "this is a message")
     eq_(script.revision, abc)
     eq_(script.down_revision, None)
     assert os.access(
         os.path.join(env.dir, 'versions', '%s_this_is_a_message.py' % abc), os.F_OK)
     assert callable(script.module.upgrade)
-    eq_(env._get_heads(), [abc])
+    eq_(env.get_heads(), [abc])
 
 def test_005_nextrev():
-    script = env.generate_rev(def_, "this is the next rev", refresh=True)
+    script = env.generate_revision(def_, "this is the next rev", refresh=True)
     assert os.access(
         os.path.join(env.dir, 'versions', '%s_this_is_the_next_rev.py' % def_), os.F_OK)
     eq_(script.revision, def_)
@@ -38,7 +38,7 @@ def test_005_nextrev():
     assert script.module.down_revision == abc
     assert callable(script.module.upgrade)
     assert callable(script.module.downgrade)
-    eq_(env._get_heads(), [def_])
+    eq_(env.get_heads(), [def_])
 
 def test_006_from_clean_env():
     # test the environment so far with a 
@@ -50,17 +50,18 @@ def test_006_from_clean_env():
     eq_(abc_rev.nextrev, set([def_]))
     eq_(abc_rev.revision, abc)
     eq_(def_rev.down_revision, abc)
-    eq_(env._get_heads(), [def_])
+    eq_(env.get_heads(), [def_])
 
 def test_007_no_refresh():
-    script = env.generate_rev(util.rev_id(), "dont' refresh")
-    ne_(script, env._as_rev_number("head"))
+    rid = util.rev_id()
+    script = env.generate_revision(rid, "dont' refresh")
+    is_(script, None)
     env2 = staging_env(create=False)
-    eq_(script, env2._as_rev_number("head"))
+    eq_(env2._as_rev_number("head"), rid)
 
 def test_008_long_name():
     rid = util.rev_id()
-    script = env.generate_rev(rid, 
+    script = env.generate_revision(rid, 
             "this is a really long name with "
             "lots of characters and also "
             "I'd like it to\nhave\nnewlines")
diff --git a/tests/test_revision_paths.py b/tests/test_revision_paths.py
index fd09a85..127fda8 100644
--- a/tests/test_revision_paths.py
+++ b/tests/test_revision_paths.py
@@ -6,11 +6,11 @@ def setup():
     global env
     env = staging_env()
     global a, b, c, d, e
-    a = env.generate_rev(util.rev_id(), None, refresh=True)
-    b = env.generate_rev(util.rev_id(), None, refresh=True)
-    c = env.generate_rev(util.rev_id(), None, refresh=True)
-    d = env.generate_rev(util.rev_id(), None, refresh=True)
-    e = env.generate_rev(util.rev_id(), None, refresh=True)
+    a = env.generate_revision(util.rev_id(), None, refresh=True)
+    b = env.generate_revision(util.rev_id(), None, refresh=True)
+    c = env.generate_revision(util.rev_id(), None, refresh=True)
+    d = env.generate_revision(util.rev_id(), None, refresh=True)
+    e = env.generate_revision(util.rev_id(), None, refresh=True)
 
 def teardown():
     clear_staging_env()
@@ -19,7 +19,7 @@ def teardown():
 def test_upgrade_path():
 
     eq_(
-        env.upgrade_from(e.revision, c.revision, None),
+        env._upgrade_revs(e.revision, c.revision),
         [
             (d.module.upgrade, c.revision, d.revision),
             (e.module.upgrade, d.revision, e.revision),
@@ -27,7 +27,7 @@ def test_upgrade_path():
     )
 
     eq_(
-        env.upgrade_from(c.revision, None, None),
+        env._upgrade_revs(c.revision, None),
         [
             (a.module.upgrade, None, a.revision),
             (b.module.upgrade, a.revision, b.revision),
@@ -38,7 +38,7 @@ def test_upgrade_path():
 def test_downgrade_path():
 
     eq_(
-        env.downgrade_to(c.revision, e.revision, None),
+        env._downgrade_revs(c.revision, e.revision),
         [
             (e.module.downgrade, e.revision, e.down_revision),
             (d.module.downgrade, d.revision, d.down_revision),
@@ -46,7 +46,7 @@ def test_downgrade_path():
     )
 
     eq_(
-        env.downgrade_to(None, c.revision, None),
+        env._downgrade_revs(None, c.revision),
         [
             (c.module.downgrade, c.revision, c.down_revision),
             (b.module.downgrade, b.revision, b.down_revision),
diff --git a/tests/test_versioning.py b/tests/test_versioning.py
index 2f19157..989d612 100644
--- a/tests/test_versioning.py
+++ b/tests/test_versioning.py
@@ -16,7 +16,7 @@ class VersioningTest(unittest.TestCase):
         c = util.rev_id()
 
         script = ScriptDirectory.from_config(self.cfg)
-        script.generate_rev(a, None, refresh=True)
+        script.generate_revision(a, None, refresh=True)
         write_script(script, a, """
     revision = '%s'
     down_revision = None
@@ -31,7 +31,7 @@ class VersioningTest(unittest.TestCase):
 
     """ % a)
 
-        script.generate_rev(b, None, refresh=True)
+        script.generate_revision(b, None, refresh=True)
         write_script(script, b, """
     revision = '%s'
     down_revision = '%s'
@@ -46,7 +46,7 @@ class VersioningTest(unittest.TestCase):
 
     """ % (b, a))
 
-        script.generate_rev(c, None, refresh=True)
+        script.generate_revision(c, None, refresh=True)
         write_script(script, c, """
     revision = '%s'
     down_revision = '%s'
@@ -117,7 +117,7 @@ class VersionNameTemplateTest(unittest.TestCase):
         self.cfg.set_main_option("file_template", "myfile_%%(slug)s")
         script = ScriptDirectory.from_config(self.cfg)
         a = util.rev_id()
-        script.generate_rev(a, "some message", refresh=True)
+        script.generate_revision(a, "some message", refresh=True)
         write_script(script, a, """
     revision = '%s'
     down_revision = None
@@ -141,7 +141,7 @@ class VersionNameTemplateTest(unittest.TestCase):
         self.cfg.set_main_option("file_template", "%%(rev)s")
         script = ScriptDirectory.from_config(self.cfg)
         a = util.rev_id()
-        script.generate_rev(a, None, refresh=True)
+        script.generate_revision(a, None, refresh=True)
         write_script(script, a, """
     down_revision = None
 
@@ -164,7 +164,7 @@ class VersionNameTemplateTest(unittest.TestCase):
         self.cfg.set_main_option("file_template", "%%(slug)s_%%(rev)s")
         script = ScriptDirectory.from_config(self.cfg)
         a = util.rev_id()
-        script.generate_rev(a, "foobar", refresh=True)
+        script.generate_revision(a, "foobar", refresh=True)
         assert_raises_message(
             util.CommandError,
             "Could not determine revision id from filename foobar_%s.py. "