scripting interface

docs/index.rst

@@ -72,34 +72,64 @@ The two arguments to ``Migrate`` are the application instance and the Flask-SQLA
 The application will now have a ``db`` command line option with several sub-commands. If your launch script is called ``manage.py`` then the commands are:
 
 - ``manage.py db --help``
-    Show a list of available commands.
+    Shows a list of available commands.
 
 - ``manage.py db init``
     Initializes migration support for the application.
 
 - ``manage.py db revision [--message MESSAGE] [--autogenerate] [--sql]``
-    Create an empty revision script. The script needs to be edited manually with the upgrade and downgrade changes. See `Alembic's documentation <https://alembic.readthedocs.org/en/latest/index.html>`_ for instructions on how to write migration scripts. An optional migration message can be included.
+    Creates an empty revision script. The script needs to be edited manually with the upgrade and downgrade changes. See `Alembic's documentation <https://alembic.readthedocs.org/en/latest/index.html>`_ for instructions on how to write migration scripts. An optional migration message can be included.
 
 - ``manage.py db migrate``
     Like ``revision --autogenerate``, but the migration script is populated with changes detected automatically. The generated script should to be reviewed and edited as not all types of changes can be detected. This command does not make any changes to the database.
 
 - ``manage.py db upgrade [--sql] [--tag TAG] [revision]``
-    Upgrade the database. If ``revision`` isn't given then ``"head"`` is assumed.
+    Upgrades the database. If ``revision`` isn't given then ``"head"`` is assumed.
 
 - ``manage.py db downgrade [--sql] [--tag TAG] [revision]``
-    Downgrade the database. If ``revision`` isn't given then ``-1`` is assumed.
+    Downgrades the database. If ``revision`` isn't given then ``-1`` is assumed.
 
 - ``manage.py db stamp [--sql] [--tag TAG] [revision]``
-    Set the revision in the database to the one given as an argument, without performing any migrations.
+    Sets the revision in the database to the one given as an argument, without performing any migrations.
 
 - ``manage.py db current``
-    Show the current revision of the database.
+    Shows the current revision of the database.
 
 - ``manage.py db history [--rev-range REV_RANGE]``
-    Show the list of migrations. If a range isn't given then the entire history is shown.
+    Shows the list of migrations. If a range isn't given then the entire history is shown.
 
 Notes:
 
 - All options also take a ``--directory DIRECTORY`` option that points to the directory containing the migration scripts. If this argument is omitted the directory used is `migrations`.
-- The ``--sql`` option present in several commands performs an 'offline' mode migration. Instead of executing the database commands the SQL statements are shown.
+- The ``--sql`` option present in several commands performs an 'offline' mode migration. Instead of executing the database commands the SQL statements that need to be executed are displayed.
 
+API Reference
+-------------
+
+The commands exposed by Flask-Migrate's interface to Flask-Script can also be accessed programmatically by importing the functions from module ``flask.ext.migrate``. The available functions are:
+
+- ``init(directory = 'migrations')``
+    Initializes migration support for the application.
+
+- ``current(directory = 'migrations')``
+    Shows the current revision of the database.
+
+- ``revision(directory = 'migrations', message = None, autogenerate = False, sql = False)``
+    Creates an empty revision script.
+
+- ``migrate(directory = 'migrations', message = None, sql = False)``
+    Creates an automatic revision script.
+
+- ``upgrade(directory = 'migrations', revision = 'head', sql = False, tag = None)``
+    Upgrades the database.
+
+- ``downgrade(directory = 'migrations', revision = '-1', sql = False, tag = None)``
+    Downgrades the database.
+
+- ``stamp(directory = 'migrations', revision = 'head', sql = False, tag = None)``
+    Sets the revision in the database to the one given as an argument, without performing any migrations.
+
+- ``history(directory = 'migrations', rev_range = None)``
+    Shows the list of migrations. If a range isn't given then the entire history is shown.
+
+Note: For greater scripting flexibility the API exposed by Alembic, on which these functions are based, can be used.

flask_migrate/__init__.py

@@ -26,22 +26,22 @@ def _get_config(directory):
 MigrateCommand = Manager(usage = 'Perform database migrations')
 
 @MigrateCommand.option('-d', '--directory', dest = 'directory', default = 'migrations', help = "migration script directory (default is 'migrations')")
-def init(directory):
+def init(directory = 'migrations'):
     "Generates a new migration"
     config = Config()
     config.set_main_option('script_location', directory)
     config.config_file_name = os.path.join(directory, 'alembic.ini') 
     command.init(config, directory, 'flask')
 
 @MigrateCommand.option('-d', '--directory', dest = 'directory', default = 'migrations', help = "Migration script directory (default is 'migrations')")
-def current(directory):
+def current(directory = 'migrations'):
     "Display the current revision for each database."
     config = _get_config(directory)
     command.current(config)
 
 @MigrateCommand.option('-r', '--rev-range', dest = 'rev_range', default = None, help = "Specify a revision range; format is [start]:[end]")
 @MigrateCommand.option('-d', '--directory', dest = 'directory', default = 'migrations', help = "Migration script directory (default is 'migrations')")
-def history(directory, rev_range):
+def history(directory = 'migrations', rev_range = None):
     "List changeset scripts in chronological order."
     config = _get_config(directory)
     command.history(config)
@@ -50,15 +50,15 @@ def history(directory, rev_range):
 @MigrateCommand.option('--autogenerate', dest = 'autogenerate', action = 'store_true', default = False, help = "Populate revision script with andidate migration operatons, based on comparison of database to model")
 @MigrateCommand.option('-m', '--message', dest = 'message', default = None)
 @MigrateCommand.option('-d', '--directory', dest = 'directory', default = 'migrations', help = "Migration script directory (default is 'migrations')")
-def revision(directory, message, autogenerate, sql):
+def revision(directory = 'migrations', message = None, autogenerate = False, sql = False):
     "Create a new revision file."
     config = _get_config(directory)
     command.revision(config, message, autogenerate = autogenerate, sql = sql)
 
 @MigrateCommand.option('--sql', dest = 'sql', action = 'store_true', default = False, help = "Don't emit SQL to database - dump to standard output instead")
 @MigrateCommand.option('-m', '--message', dest = 'message', default = None)
 @MigrateCommand.option('-d', '--directory', dest = 'directory', default = 'migrations', help = "Migration script directory (default is 'migrations')")
-def migrate(directory, message, sql):
+def migrate(directory = 'migrations', message = None, sql = False):
     "Alias for 'revision --autogenerate'"
     config = _get_config(directory)
     command.revision(config, message, autogenerate = True, sql = sql)
@@ -67,7 +67,7 @@ def migrate(directory, message, sql):
 @MigrateCommand.option('--sql', dest = 'sql', action = 'store_true', default = False, help = "Don't emit SQL to database - dump to standard output instead")
 @MigrateCommand.option('revision', default = None, help = "revision identifier")
 @MigrateCommand.option('-d', '--directory', dest = 'directory', default = 'migrations', help = "Migration script directory (default is 'migrations')")
-def stamp(directory, revision, sql, tag):
+def stamp(directory = 'migrations', revision = 'head', sql = False, tag = None):
     "'stamp' the revision table with the given revision; don't run any migrations"
     config = _get_config(directory)
     command.stamp(config, revision, sql = sql, tag = tag)
@@ -76,7 +76,7 @@ def stamp(directory, revision, sql, tag):
 @MigrateCommand.option('--sql', dest = 'sql', action = 'store_true', default = False, help = "Don't emit SQL to database - dump to standard output instead")
 @MigrateCommand.option('revision', nargs = '?', default = 'head', help = "revision identifier")
 @MigrateCommand.option('-d', '--directory', dest = 'directory', default = 'migrations', help = "Migration script directory (default is 'migrations')")
-def upgrade(directory, revision, sql, tag):
+def upgrade(directory = 'migrations', revision = 'head', sql = False, tag = None):
     "Upgrade to a later version"
     config = _get_config(directory)
     command.upgrade(config, revision, sql = sql, tag = tag)
@@ -85,8 +85,7 @@ def upgrade(directory, revision, sql, tag):
 @MigrateCommand.option('--sql', dest = 'sql', action = 'store_true', default = False, help = "Don't emit SQL to database - dump to standard output instead")
 @MigrateCommand.option('revision', nargs = '?', default = "-1", help = "revision identifier")
 @MigrateCommand.option('-d', '--directory', dest = 'directory', default = 'migrations', help = "Migration script directory (default is 'migrations')")
-def downgrade(directory, revision, sql, tag):
+def downgrade(directory = 'migrations', revision = '-1', sql = False, tag = None):
     "Revert to a previous version"
     config = _get_config(directory)
     command.downgrade(config, revision, sql = sql, tag = tag)
-

setup.py

@@ -9,7 +9,7 @@
 
 setup(
     name='Flask-Migrate',
-    version='0.1.4',
+    version='1.0.0',
     url='http://github.com/miguelgrinberg/flask-migrate/',
     license='MIT',
     author='Miguel Grinberg',