diff options
Diffstat (limited to 'docs/build/api')
| -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 |
10 files changed, 34 insertions, 20 deletions
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 ================ |