diff options
-rw-r--r-- | alembic/config.py | 4 | ||||
-rw-r--r-- | docs/build/api/autogenerate.rst | 4 | ||||
-rw-r--r-- | docs/build/api/commands.rst | 8 | ||||
-rw-r--r-- | docs/build/api/config.rst | 6 | ||||
-rw-r--r-- | docs/build/api/ddl.rst | 6 | ||||
-rw-r--r-- | docs/build/api/environment.rst | 2 | ||||
-rw-r--r-- | docs/build/api/index.rst | 2 | ||||
-rw-r--r-- | docs/build/api/migration.rst | 2 | ||||
-rw-r--r-- | docs/build/api/operations.rst | 10 | ||||
-rw-r--r-- | docs/build/api/overview.rst | 12 | ||||
-rw-r--r-- | docs/build/api/script.rst | 2 | ||||
-rw-r--r-- | docs/build/changelog.rst | 38 | ||||
-rw-r--r-- | docs/build/cookbook.rst | 2 | ||||
-rw-r--r-- | docs/build/front.rst | 19 | ||||
-rw-r--r-- | docs/build/ops.rst | 6 |
15 files changed, 85 insertions, 38 deletions
diff --git a/alembic/config.py b/alembic/config.py index 74b4d17..b3fc36f 100644 --- a/alembic/config.py +++ b/alembic/config.py @@ -130,7 +130,7 @@ class Config(object): This is a utility dictionary which can include not just strings but engines, connections, schema objects, or anything else. Use this to pass objects into an env.py script, such as passing - a :class:`.Connection` when calling + a :class:`sqlalchemy.engine.base.Connection` when calling commands from :mod:`alembic.command` programmatically. .. versionadded:: 0.7.5 @@ -155,7 +155,7 @@ class Config(object): @util.memoized_property def file_config(self): - """Return the underlying :class:`ConfigParser` object. + """Return the underlying ``ConfigParser`` object. Direct access to the .ini file is available here, though the :meth:`.Config.get_section` and diff --git a/docs/build/api/autogenerate.rst b/docs/build/api/autogenerate.rst index b96a299..b024ab1 100644 --- a/docs/build/api/autogenerate.rst +++ b/docs/build/api/autogenerate.rst @@ -1,10 +1,12 @@ +.. _alembic.autogenerate.toplevel: + ============== Autogeneration ============== The autogenerate system has two areas of API that are public: -1. The ability to do a "diff" of a :class:`.MetaData` object against +1. The ability to do a "diff" of a :class:`~sqlalchemy.schema.MetaData` object against a database, and receive a data structure back. This structure is available either as a rudimentary list of changes, or as a :class:`.MigrateOperation` structure. diff --git a/docs/build/api/commands.rst b/docs/build/api/commands.rst index 3d73ce5..65dcc09 100644 --- a/docs/build/api/commands.rst +++ b/docs/build/api/commands.rst @@ -1,10 +1,12 @@ +.. _alembic.command.toplevel: + ========= Commands ========= -Alembic commands are all represented by functions in the :mod:`alembic.command` +Alembic commands are all represented by functions in the :ref:`alembic.command.toplevel` package. They all accept the same style of usage, being sent -the :class:`~.alembic.config.Config` object as the first argument. +the :class:`.Config` object as the first argument. Commands can be run programmatically, by first constructing a :class:`.Config` object, as in:: @@ -32,7 +34,5 @@ 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: diff --git a/docs/build/api/config.rst b/docs/build/api/config.rst index 9294a6d..25d934f 100644 --- a/docs/build/api/config.rst +++ b/docs/build/api/config.rst @@ -1,3 +1,5 @@ +.. _alembic.config.toplevel: + ============== Configuration ============== @@ -10,7 +12,7 @@ it is needed for the following use cases: 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` +* to programatically run any of the commands in the :ref:`alembic.command.toplevel` module. The :class:`.Config` is *not* needed for these cases: @@ -20,7 +22,5 @@ The :class:`.Config` is *not* needed for these cases: * to instantiate a :class:`.Operations` object - this object only needs a :class:`.MigrationContext`. -.. currentmodule:: alembic.config - .. automodule:: alembic.config :members: diff --git a/docs/build/api/ddl.rst b/docs/build/api/ddl.rst index aff697c..2d114c8 100644 --- a/docs/build/api/ddl.rst +++ b/docs/build/api/ddl.rst @@ -1,13 +1,15 @@ +.. _alembic.ddl.toplevel: + ============= 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. +and :ref:`sqlalchemy.ext.compiler_toplevel` systems. For programmatic usage of Alembic's migration directives, the easiest -route is to use the higher level functions given by :mod:`alembic.operations`. +route is to use the higher level functions given by :ref:`alembic.operations.toplevel`. .. automodule:: alembic.ddl :members: diff --git a/docs/build/api/environment.rst b/docs/build/api/environment.rst index 874cf98..5a22773 100644 --- a/docs/build/api/environment.rst +++ b/docs/build/api/environment.rst @@ -1,3 +1,5 @@ +.. _alembic.runtime.environment.toplevel: + ======================= The Environment Context ======================= diff --git a/docs/build/api/index.rst b/docs/build/api/index.rst index 26ee9b4..aa7c1a9 100644 --- a/docs/build/api/index.rst +++ b/docs/build/api/index.rst @@ -16,7 +16,7 @@ outside of this subsection, and the parameters that can be passed to the :meth:`.EnvironmentContext.configure` method, used when configuring one's ``env.py`` environment. However, real-world applications will usually end up using more of the internal API, in particular being able -to run commands programmatically, as discussed in the section :doc:`api/commands`. +to run commands programmatically, as discussed in the section :doc:`/api/commands`. .. toctree:: :maxdepth: 2 diff --git a/docs/build/api/migration.rst b/docs/build/api/migration.rst index 300c792..ae74818 100644 --- a/docs/build/api/migration.rst +++ b/docs/build/api/migration.rst @@ -1,3 +1,5 @@ +.. _alembic.runtime.migration.toplevel: + ===================== The Migration Context ===================== diff --git a/docs/build/api/operations.rst b/docs/build/api/operations.rst index 773cf6e..d9ff238 100644 --- a/docs/build/api/operations.rst +++ b/docs/build/api/operations.rst @@ -1,3 +1,5 @@ +.. _alembic.operations.toplevel: + ===================== The Operations Object ===================== @@ -13,7 +15,7 @@ Most methods on the :class:`.Operations` class are generated dynamically using a "plugin" system, described in the next section :ref:`operation_plugins`. Additionally, when Alembic migration scripts actually run, the methods on the current :class:`.Operations` object are -proxied out to the :mod:`alembic.op` module, so that they are available +proxied out to the ``alembic.op`` module, so that they are available using module-style access. For an overview of how to use an :class:`.Operations` object directly @@ -76,7 +78,7 @@ Above, we use the simplest possible technique of invoking our DDL, which is just to call :meth:`.Operations.execute` with literal SQL. If this is all a custom operation needs, then this is fine. However, options for more comprehensive support include building out a custom SQL construct, -as documented at :ref:`sqlalchemy.ext.compiles`. +as documented at :ref:`sqlalchemy.ext.compiler_toplevel`. With the above two steps, a migration script can now use a new method ``op.create_sequence()`` that will proxy to our object as a classmethod:: @@ -90,7 +92,7 @@ within the module level of the ``env.py`` script is sufficient. .. versionadded:: 0.8 - the migration operations available via the - :class:`.Operations` class as well as the :mod:`alembic.op` namespace + :class:`.Operations` class as well as the ``alembic.op`` namespace is now extensible using a plugin system. @@ -115,5 +117,7 @@ autogenerate system renders new migration scripts. The built-in operation objects are listed below. +.. _alembic.operations.ops.toplevel: + .. automodule:: alembic.operations.ops :members: diff --git a/docs/build/api/overview.rst b/docs/build/api/overview.rst index 4bdbfa0..048d1e6 100644 --- a/docs/build/api/overview.rst +++ b/docs/build/api/overview.rst @@ -9,10 +9,10 @@ elements intended to convey the primary purpose of each system. .. image:: api_overview.png -The script runner for Alembic is present in the :mod:`alembic.config` module. +The script runner for Alembic is present in the :ref:`alembic.config.toplevel` module. This module produces a :class:`.Config` object and passes it to the -appropriate function in :mod:`alembic.command`. Functions within -:mod:`alembic.command` will typically instantiate an +appropriate function in :ref:`alembic.command.toplevel`. Functions within +:ref:`alembic.command.toplevel` will typically instantiate an :class:`.ScriptDirectory` instance, which represents the collection of version files, and an :class:`.EnvironmentContext`, which represents a configurational object passed to the environment's ``env.py`` script. @@ -33,15 +33,15 @@ with the :class:`.ScriptDirectory`; the actual scripts themselves make use of the :class:`.Operations` object, which provide the end-user interface to specific database operations. The :class:`.Operations` object is generated based on a series of "operation directive" objects that are user-extensible, -and start out in the :mod:`alembic.operations.ops` module. +and start out in the :ref:`alembic.operations.ops.toplevel` module. Another prominent feature of Alembic is the "autogenerate" feature, which produces new migration scripts that contain Python code. The autogenerate -feature starts in :mod:`alembic.autogenerate`, and is used exclusively +feature starts in :ref:`alembic.autogenerate.toplevel`, and is used exclusively by the :func:`.alembic.command.revision` command when the ``--autogenerate`` flag is passed. Autogenerate refers to the :class:`.MigrationContext` and :class:`.DefaultImpl` in order to access database connectivity and access per-backend rules for autogenerate comparisons. It also makes use -of :mod:`alembic.operations.ops` in order to represent the operations that +of :ref:`alembic.operations.ops.toplevel` in order to represent the operations that it will render into scripts. diff --git a/docs/build/api/script.rst b/docs/build/api/script.rst index 9ff7f2f..8dc594b 100644 --- a/docs/build/api/script.rst +++ b/docs/build/api/script.rst @@ -1,3 +1,5 @@ +.. _alembic.script.toplevel: + ================ Script Directory ================ diff --git a/docs/build/changelog.rst b/docs/build/changelog.rst index 9c06825..7a96f8d 100644 --- a/docs/build/changelog.rst +++ b/docs/build/changelog.rst @@ -4,6 +4,44 @@ Changelog ========== .. changelog:: + :version: 0.8.0 + + .. change:: + :tags: feature, operations + :tickets: 302 + + The internal system for Alembic operations has been reworked to now + build upon an extensible system of operation objects. New operations + can be added to the ``op.`` namespace, including that they are + available in custom autogenerate schemes. + + .. seealso:: + + :ref:`operation_plugins` + + .. change:: + :tags: feature, autogenerate + :tickets: 301 + + The internal system for autogenerate been reworked to build upon + the extensible system of operation objects present in + :ticket:`302`. As part of this change, autogenerate now produces + a full object graph representing a list of migration scripts to + be written as well as operation objects that will render all the + Python code within them; a new hook + :paramref:`.EnvironmentContext.configure.process_revision_directives` + allows end-user code to fully customize what autogenerate will do, + including not just full manipulation of the Python steps to take + but also what file or files will be written and where. It is also + possible to write a system that reads an autogenerate stream and + invokes it directly against a database without writing any files. + + .. seealso:: + + :ref:`alembic.autogenerate.toplevel` + + +.. changelog:: :version: 0.7.7 .. change:: diff --git a/docs/build/cookbook.rst b/docs/build/cookbook.rst index 8c1e0d7..541f595 100644 --- a/docs/build/cookbook.rst +++ b/docs/build/cookbook.rst @@ -193,7 +193,7 @@ Sharing a Connection with a Series of Migration Commands and Environments ========================================================================= It is often the case that an application will need to call upon a series -of commands within :mod:`alembic.command`, where it would be advantageous +of commands within :ref:`alembic.command.toplevel`, where it would be advantageous for all operations to proceed along a single transaction. The connectivity for a migration is typically solely determined within the ``env.py`` script of a migration environment, which is called within the scope of a command. diff --git a/docs/build/front.rst b/docs/build/front.rst index 3270f5c..6e28419 100644 --- a/docs/build/front.rst +++ b/docs/build/front.rst @@ -49,25 +49,19 @@ then proceed through the usage of this command. Dependencies ------------ -Alembic's install process will ensure that `SQLAlchemy <http://www.sqlalchemy.org>`_ +Alembic's install process will ensure that SQLAlchemy_ is installed, in addition to other dependencies. Alembic will work with -SQLAlchemy as of version **0.7.3**. The latest version of SQLAlchemy within -the **0.7**, **0.8**, or more recent series is strongly recommended. +SQLAlchemy as of version **0.7.3**, however more features are available with +newer versions such as the 0.9 or 1.0 series. Alembic supports Python versions 2.6 and above. -.. versionchanged:: 0.5.0 - Support for SQLAlchemy 0.6 has been dropped. - -.. versionchanged:: 0.6.0 - Now supporting Python 2.6 and above. - Community ========= Alembic is developed by `Mike Bayer <http://techspot.zzzeek.org>`_, and is -loosely associated with the `SQLAlchemy <http://www.sqlalchemy.org/>`_ and `Pylons <http://www.pylonsproject.org>`_ -projects. +loosely associated with the SQLAlchemy_, `Pylons <http://www.pylonsproject.org>`_, +and `Openstack <http://www.openstack.org>`_ projects. User issues, discussion of potential bugs and features should be posted to the Alembic Google Group at `sqlalchemy-alembic <https://groups.google.com/group/sqlalchemy-alembic>`_. @@ -78,3 +72,6 @@ Bugs ==== Bugs and feature enhancements to Alembic should be reported on the `Bitbucket issue tracker <https://bitbucket.org/zzzeek/alembic/issues?status=new&status=open>`_. + + +.. _SQLAlchemy: http://www.sqlalchemy.org
\ No newline at end of file diff --git a/docs/build/ops.rst b/docs/build/ops.rst index 83c936c..49aaef5 100644 --- a/docs/build/ops.rst +++ b/docs/build/ops.rst @@ -21,7 +21,7 @@ so symbols can be imported safely from the ``alembic.op`` namespace. The :class:`.Operations` system is also fully extensible. See :ref:`operation_plugins` for details on this. -A key design philosophy to the :mod:`alembic.operations` methods is that +A key design philosophy to the :ref:`alembic.operations.toplevel` methods is that to the greatest degree possible, they internally generate the appropriate SQLAlchemy metadata, typically involving :class:`~sqlalchemy.schema.Table` and :class:`~sqlalchemy.schema.Constraint` @@ -39,7 +39,5 @@ circumstances they are called from an actual migration script, which itself would be invoked by the :meth:`.EnvironmentContext.run_migrations` method. - .. automodule:: alembic.operations - :members: Operations, BatchOperations - + :members: Operations, BatchOperations |