diff options
author | Mike Bayer <mike_mp@zzzcomputing.com> | 2017-02-27 15:57:33 -0500 |
---|---|---|
committer | Mike Bayer <mike_mp@zzzcomputing.com> | 2017-02-27 15:57:33 -0500 |
commit | 364808a76083cc902ecfd60890ca1d34d24dbbac (patch) | |
tree | 8758ef3f2f8d0de86368ee3d14dc4dc9514bbac8 /alembic/command.py | |
parent | 7d5f6eabeccb9328c1c21dd0cdf9ff1f2f85836d (diff) | |
download | alembic-364808a76083cc902ecfd60890ca1d34d24dbbac.tar.gz |
- provide param docstrings for all of command
- add cross-linking for process_revision_directives
Change-Id: I88914df056d720207c781501934893ec8e030610
Diffstat (limited to 'alembic/command.py')
-rw-r--r-- | alembic/command.py | 168 |
1 files changed, 156 insertions, 12 deletions
diff --git a/alembic/command.py b/alembic/command.py index 9a333a0..694ee3f 100644 --- a/alembic/command.py +++ b/alembic/command.py @@ -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) |