- add docs and links and stuff for the -x option, which apparently

we had ticketed as #120

diff --git a/alembic/config.py b/alembic/config.py
index bc3ae7a03b9eec36021ddbf5317daa0c81a7f343..da5eee2dc906b040c57b0b3b65bbd90e673fecb5 100644 (file)
--- a/alembic/config.py
+++ b/alembic/config.py
@@ -64,7 +64,14 @@ class Config(object):
     cmd_opts = None
     """The command-line options passed to the ``alembic`` script.
 
-    ..versionadded:: 0.6.0
+    Within an ``env.py`` script this can be accessed via the
+    :attr:`.EnvironmentContext.config` attribute.
+
+    .. versionadded:: 0.6.0
+
+    .. seealso::
+
+        :meth:`.EnvironmentContext.get_x_argument`
 
     """
 

diff --git a/alembic/environment.py b/alembic/environment.py
index 1808145e641bc47fd7441132502fb5da7e1aab18..5d4e056105286a06cc79ff475213ea25b0b83209 100644 (file)
--- a/alembic/environment.py
+++ b/alembic/environment.py
@@ -197,9 +197,62 @@ class EnvironmentContext(object):
         This function does not require that the :class:`.MigrationContext`
         has been configured.
 
+        .. seealso::
+
+            :meth:`.EnvironmentContext.get_x_argument` - a newer and more
+            open ended system of extending ``env.py`` scripts via the command
+            line.
+
         """
         return self.context_opts.get('tag', None)
 
+    def get_x_argument(self, as_dictionary=False):
+        """Return the value(s) passed for the ``-x`` argument, if any.
+
+        The ``-x`` argument is an open ended flag that allows any user-defined
+        value or values to be passed on the command line, then available
+        here for consumption by a custom ``env.py`` script.
+
+        The return value is a list, returned directly from the ``argparse``
+        structure.  If ``as_dictionary=True`` is passed, the ``x`` arguments
+        are parsed using ``key=value`` format into a dictionary that is
+        then returned.
+
+        For example, to support passing a database URL on the command line,
+        the standard ``env.py`` script can be modified like this::
+
+            cmd_line_url = context.get_x_argument(as_dictionary=True).get('dbname')
+            if cmd_line_url:
+                engine = create_engine(cmd_line_url)
+            else:
+                engine = engine_from_config(
+                        config.get_section(config.config_ini_section),
+                        prefix='sqlalchemy.',
+                        poolclass=pool.NullPool)
+
+        This then takes effect by running the ``alembic`` script as::
+
+            alembic -x dbname=postgresql://user:pass@host/dbname upgrade head
+
+        This function does not require that the :class:`.MigrationContext`
+        has been configured.
+
+        .. versionadded:: 0.6.0
+
+        .. seealso::
+
+            :meth:`.EnvironmentContext.get_tag_argument`
+
+            :attr:`.Config.cmd_opts`
+
+        """
+        value = self.config.cmd_opts.x or []
+        if as_dictionary:
+            value = dict(
+                        arg.split('=', 1) for arg in value
+                    )
+        return value
+
     def configure(self,
             connection=None,
             url=None,
@@ -289,7 +342,7 @@ class EnvironmentContext(object):
          running the "revision" command.   Note that the script environment
          is only run within the "revision" command if the --autogenerate
          option is used, or if the option "revision_environment=true"
-         is present in the alembic.ini file. 
+         is present in the alembic.ini file.
 
          .. versionadded:: 0.3.3
 

diff --git a/docs/build/changelog.rst b/docs/build/changelog.rst
index c19e6596f4e16cfde65dd95c7ba948b07ada5631..ec5beba3f777a26f8a8410960e53d88a209f4fc7 100644 (file)
--- a/docs/build/changelog.rst
+++ b/docs/build/changelog.rst
@@ -10,16 +10,18 @@ Changelog
       :tags: feature
 
       Added :attr:`alembic.config.Config.cmd_opts` attribute,
-      allows access to the `argparse` options passed to the
-      `alembic` runner.
+      allows access to the ``argparse`` options passed to the
+      ``alembic`` runner.
 
     .. change::
       :tags: feature
+      :tickets: 120
 
       Added new command line argument ``-x``, allows extra arguments
       to be appended to the command line which can be consumed
       within an ``env.py`` script by looking at
-      ``context.config.cmd_opts.x``.
+      ``context.config.cmd_opts.x``, or more simply a new
+      method :meth:`.EnvironmentContext.get_x_argument`.
 
     .. change::
       :tags: bug