def list_templates(config):
- """List available templates"""
+ """List available templates
+
+ :param config: a :class:`.Config` object.
+
+ """
config.print_stdout("Available templates:\n")
for tempname in os.listdir(config.get_template_directory()):
def init(config, directory, template='generic'):
- """Initialize a new scripts directory."""
+ """Initialize a new scripts directory.
+
+ :param config: a :class:`.Config` object.
+
+ :param directory: string path of the target directory
+
+ :param template: string name of the migration environment template to
+ use.
+
+ """
if os.access(directory, os.F_OK):
raise util.CommandError("Directory %s already exists" % directory)
head="head", splice=False, branch_label=None,
version_path=None, rev_id=None, depends_on=None,
process_revision_directives=None):
- """Create a new revision file."""
+ """Create a new revision file.
+
+ :param config: a :class:`.Config` object.
+
+ :param message: string message to apply to the revision; this is the
+ ``-m`` option to ``alembic revision``.
+
+ :param autogenerate: whether or not to autogenerate the script from
+ the database; this is the ``--autogenerate`` option to ``alembic revision``.
+
+ :param sql: whether to dump the script out as a SQL string; when specified,
+ the script is dumped to stdout. This is the ``--sql`` option to
+ ``alembic revision``.
+
+ :param head: head revision to build the new revision upon as a parent;
+ this is the ``--head`` option to ``alembic revision``.
+
+ :param splice: whether or not the new revision should be made into a
+ new head of its own; is required when the given ``head`` is not itself
+ a head. This is the ``--splice`` option to ``alembic revision``.
+
+ :param branch_label: string label to apply to the branch; this is the
+ ``--branch-label`` option to ``alembic revision``.
+
+ :param version_path: string symbol identifying a specific version path
+ from the configuration; this is the ``--version-path`` option to
+ ``alembic revision``.
+
+ :param rev_id: optional revision identifier to use instead of having
+ one generated; this is the ``--rev-id`` option to ``alembic revision``.
+
+ :param depends_on: optional list of "depends on" identifiers; this is the
+ ``--depends-on`` option to ``alembic revision``.
+
+ :param process_revision_directives: this is a callable that takes the
+ same form as the callable described at
+ :paramref:`.EnvironmentContext.configure.process_revision_directives`;
+ will be applied to the structure generated by the revision process
+ where it can be altered programmatically. Note that unlike all
+ the other parameters, this option is only available via programmatic
+ use of :func:`.command.revision`
+
+ .. versionadded:: 0.9.0
+
+ """
script_directory = ScriptDirectory.from_config(config)
.. versionadded:: 0.7.0
+ :param config: a :class:`.Config` instance
+
+ :param message: string message to apply to the revision
+
+ :param branch_label: string label name to apply to the new revision
+
+ :param rev_id: hardcoded revision identifier instead of generating a new
+ one.
+
.. seealso::
:ref:`branches`
def upgrade(config, revision, sql=False, tag=None):
- """Upgrade to a later version."""
+ """Upgrade to a later version.
+
+ :param config: a :class:`.Config` instance.
+
+ :param revision: string revision target or range for --sql mode
+
+ :param sql: if True, use ``--sql`` mode
+
+ :param tag: an arbitrary "tag" that can be intercepted by custom
+ ``env.py`` scripts via the :class:`.EnvironmentContext.get_tag_argument`
+ method.
+
+ """
script = ScriptDirectory.from_config(config)
def downgrade(config, revision, sql=False, tag=None):
- """Revert to a previous version."""
+ """Revert to a previous version.
+
+ :param config: a :class:`.Config` instance.
+
+ :param revision: string revision target or range for --sql mode
+
+ :param sql: if True, use ``--sql`` mode
+
+ :param tag: an arbitrary "tag" that can be intercepted by custom
+ ``env.py`` scripts via the :class:`.EnvironmentContext.get_tag_argument`
+ method.
+
+ """
script = ScriptDirectory.from_config(config)
starting_rev = None
def show(config, rev):
- """Show the revision(s) denoted by the given symbol."""
+ """Show the revision(s) denoted by the given symbol.
+
+ :param config: a :class:`.Config` instance.
+
+ :param revision: string revision target
+
+ """
script = ScriptDirectory.from_config(config)
def history(config, rev_range=None, verbose=False):
- """List changeset scripts in chronological order."""
+ """List changeset scripts in chronological order.
+
+ :param config: a :class:`.Config` instance.
+
+ :param rev_range: string revision range
+
+ :param verbose: output in verbose mode.
+
+ """
script = ScriptDirectory.from_config(config)
if rev_range is not None:
def heads(config, verbose=False, resolve_dependencies=False):
- """Show current available heads in the script directory"""
+ """Show current available heads in the script directory
+
+ :param config: a :class:`.Config` instance.
+
+ :param verbose: output in verbose mode.
+
+ :param resolve_dependencies: treat dependency version as down revisions.
+
+ """
script = ScriptDirectory.from_config(config)
if resolve_dependencies:
def branches(config, verbose=False):
- """Show current branch points"""
+ """Show current branch points.
+
+ :param config: a :class:`.Config` instance.
+
+ :param verbose: output in verbose mode.
+
+ """
script = ScriptDirectory.from_config(config)
for sc in script.walk_revisions():
if sc.is_branch_point:
def current(config, verbose=False, head_only=False):
- """Display the current revision for a database."""
+ """Display the current revision for a database.
+
+ :param config: a :class:`.Config` instance.
+
+ :param verbose: output in verbose mode.
+
+ :param head_only: deprecated; use ``verbose`` for additional output.
+
+ """
script = ScriptDirectory.from_config(config)
def stamp(config, revision, sql=False, tag=None):
"""'stamp' the revision table with the given revision; don't
- run any migrations."""
+ run any migrations.
+
+ :param config: a :class:`.Config` instance.
+
+ :param revision: target revision.
+
+ :param sql: use ``--sql`` mode
+
+ :param tag: an arbitrary "tag" that can be intercepted by custom
+ ``env.py`` scripts via the :class:`.EnvironmentContext.get_tag_argument`
+ method.
+
+ """
script = ScriptDirectory.from_config(config)
def edit(config, rev):
- """Edit revision script(s) using $EDITOR"""
+ """Edit revision script(s) using $EDITOR.
+
+ :param config: a :class:`.Config` instance.
+
+ :param rev: target revision.
+
+ """
script = ScriptDirectory.from_config(config)