From: Mike Bayer Date: Fri, 17 Jul 2015 20:48:41 +0000 (-0400) Subject: - since the section titles in api are bound to be misleading, X-Git-Tag: rel_0_8_0~13 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2d9fc09440882175ab7197dc963242e1110c820a;p=thirdparty%2Fsqlalchemy%2Falembic.git - since the section titles in api are bound to be misleading, put notes at the top of most of them - consolidate EnvironmentContext / MigrationContext --- diff --git a/docs/build/api/autogenerate.rst b/docs/build/api/autogenerate.rst index 8b026e81..7376915e 100644 --- a/docs/build/api/autogenerate.rst +++ b/docs/build/api/autogenerate.rst @@ -4,6 +4,13 @@ Autogeneration ============== +.. note:: this section discusses the **internal API of Alembic** + as regards the autogeneration feature of the ``alembic revision`` + command. + This section is only useful for developers who wish to extend the + capabilities of Alembic. For general documentation on the autogenerate + feature, please see :doc:`/autogenerate`. + The autogeneration system has a wide degree of public API, including the following areas: diff --git a/docs/build/api/commands.rst b/docs/build/api/commands.rst index 65dcc095..266a2066 100644 --- a/docs/build/api/commands.rst +++ b/docs/build/api/commands.rst @@ -4,6 +4,12 @@ Commands ========= +.. note:: this section discusses the **internal API of Alembic** + as regards its command invocation system. + This section is only useful for developers who wish to extend the + capabilities of Alembic. For documentation on using Alembic commands, + please see :doc:`/tutorial`. + 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:`.Config` object as the first argument. diff --git a/docs/build/api/config.rst b/docs/build/api/config.rst index 25d934fb..1d1181b9 100644 --- a/docs/build/api/config.rst +++ b/docs/build/api/config.rst @@ -4,6 +4,12 @@ Configuration ============== +.. note:: this section discusses the **internal API of Alembic** as + regards internal configuration constructs. + This section is only useful for developers who wish to extend the + capabilities of Alembic. For documentation on configuration of + an Alembic environment, please see :doc:`/tutorial`. + The :class:`.Config` object represents the configuration passed to the Alembic environment. From an API usage perspective, it is needed for the following use cases: diff --git a/docs/build/api/index.rst b/docs/build/api/index.rst index aa7c1a9e..f9efb899 100644 --- a/docs/build/api/index.rst +++ b/docs/build/api/index.rst @@ -22,8 +22,7 @@ to run commands programmatically, as discussed in the section :doc:`/api/command :maxdepth: 2 overview - environment - migration + runtime config commands operations diff --git a/docs/build/api/migration.rst b/docs/build/api/migration.rst deleted file mode 100644 index ae74818a..00000000 --- a/docs/build/api/migration.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. _alembic.runtime.migration.toplevel: - -===================== -The Migration Context -===================== - -.. automodule:: alembic.runtime.migration - :members: MigrationContext diff --git a/docs/build/api/operations.rst b/docs/build/api/operations.rst index 2eb8358e..e55b958b 100644 --- a/docs/build/api/operations.rst +++ b/docs/build/api/operations.rst @@ -4,6 +4,12 @@ Operation Directives ===================== +.. note:: this section discusses the **internal API of Alembic** as regards + the internal system of defining migration operation directives. + This section is only useful for developers who wish to extend the + capabilities of Alembic. For end-user guidance on Alembic migration + operations, please see :ref:`ops`. + Within migration scripts, actual database migration operations are handled via an instance of :class:`.Operations`. The :class:`.Operations` class lists out available migration operations that are linked to a diff --git a/docs/build/api/overview.rst b/docs/build/api/overview.rst index 3e6bec83..94c1f858 100644 --- a/docs/build/api/overview.rst +++ b/docs/build/api/overview.rst @@ -2,6 +2,12 @@ Overview ======== +.. note:: this section is a technical overview of the + **internal API of Alembic**. + This section is only useful for developers who wish to extend the + capabilities of Alembic; for regular users, reading this section + is **not necessary**. + A visualization of the primary features of Alembic's internals is presented in the following figure. The module and class boxes do not list out all the operations provided by each unit; only a small set of representative diff --git a/docs/build/api/environment.rst b/docs/build/api/runtime.rst similarity index 56% rename from docs/build/api/environment.rst rename to docs/build/api/runtime.rst index 5a227738..f32e943a 100644 --- a/docs/build/api/environment.rst +++ b/docs/build/api/runtime.rst @@ -1,6 +1,14 @@ .. _alembic.runtime.environment.toplevel: ======================= +Runtime Objects +======================= + +The "runtime" of Alembic involves the :class:`.EnvironmentContext` +and :class:`.MigrationContext` objects. These are the objects that are +in play once the ``env.py`` script is loaded up by a command and +a migration operation proceeds. + The Environment Context ======================= @@ -17,3 +25,15 @@ which establishes all the details about how the database will be accessed. .. automodule:: alembic.runtime.environment :members: EnvironmentContext + +.. _alembic.runtime.migration.toplevel: + +The Migration Context +===================== + +The :class:`.MigrationContext` handles the actual work to be performed +against a database backend as migration operations proceed. It is generally +not exposed to the end-user. + +.. automodule:: alembic.runtime.migration + :members: MigrationContext