- provide param docstrings for all of command
- add cross-linking for process_revision_directives Change-Id: I88914df056d720207c781501934893ec8e030610
This commit is contained in:
Mike Bayer
parent
7d5f6eabec
commit
364808a760
|
|
@ -7,7 +7,11 @@ from . import autogenerate as autogen
|
|||
|
||||
|
||||
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()):
|
||||
|
|
@ -23,7 +27,16 @@ def list_templates(config):
|
|||
|
||||
|
||||
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)
|
||||
|
|
@ -70,7 +83,51 @@ def revision(
|
|||
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)
|
||||
|
||||
|
|
@ -133,6 +190,15 @@ def merge(config, revisions, message=None, branch_label=None, rev_id=None):
|
|||
|
||||
.. 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`
|
||||
|
|
@ -151,7 +217,19 @@ def merge(config, revisions, message=None, branch_label=None, rev_id=None):
|
|||
|
||||
|
||||
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)
|
||||
|
||||
|
|
@ -177,7 +255,19 @@ def upgrade(config, revision, sql=False, tag=None):
|
|||
|
||||
|
||||
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
|
||||
|
|
@ -205,7 +295,13 @@ def downgrade(config, revision, sql=False, tag=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)
|
||||
|
||||
|
|
@ -226,7 +322,15 @@ def show(config, rev):
|
|||
|
||||
|
||||
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:
|
||||
|
|
@ -271,7 +375,15 @@ def history(config, rev_range=None, verbose=False):
|
|||
|
||||
|
||||
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:
|
||||
|
|
@ -286,7 +398,13 @@ def heads(config, verbose=False, resolve_dependencies=False):
|
|||
|
||||
|
||||
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:
|
||||
|
|
@ -305,7 +423,15 @@ def branches(config, verbose=False):
|
|||
|
||||
|
||||
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)
|
||||
|
||||
|
|
@ -333,7 +459,19 @@ def current(config, verbose=False, head_only=False):
|
|||
|
||||
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)
|
||||
|
||||
|
|
@ -359,7 +497,13 @@ def stamp(config, revision, sql=False, tag=None):
|
|||
|
||||
|
||||
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)
|
||||
|
||||
|
|
|
|||
|
|
@ -730,6 +730,8 @@ class EnvironmentContext(util.ModuleClsProxy):
|
|||
|
||||
:ref:`autogen_rewriter`
|
||||
|
||||
:paramref:`.command.revision.process_revision_directives`
|
||||
|
||||
|
||||
Parameters specific to individual backends:
|
||||
|
||||
|
|
|
|||
|
|
@ -68,7 +68,9 @@ Changelog
|
|||
|
||||
Added a keyword argument ``process_revision_directives`` to the
|
||||
:func:`.command.revision` API call. This function acts in the
|
||||
same role as the environment-level call, and allows API use of the
|
||||
same role as the environment-level
|
||||
:paramref:`.EnvironmentContext.configure.process_revision_directives`,
|
||||
and allows API use of the
|
||||
command to drop in an ad-hoc directive process function. This
|
||||
function can be used among other things to place a complete
|
||||
:class:`.MigrationScript` structure in place.
|
||||
|
|
|
|||
Loading…
Reference in New Issue