From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Sat, 1 Feb 2014 17:56:00 +0000 (-0500)
Subject: more doc fixes and updates
X-Git-Tag: rel_0_6_3~5
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=320125128178798544fb0c4d054afb6abec0f371;p=thirdparty%2Fsqlalchemy%2Falembic.git

more doc fixes and updates
---

diff --git a/alembic/environment.py b/alembic/environment.py
index 385855be..0c9095d3 100644
--- a/alembic/environment.py
+++ b/alembic/environment.py
@@ -383,7 +383,13 @@ class EnvironmentContext(object):
                 # return True if the types are different,
                 # False if not, or None to allow the default implementation
                 # to compare these types
-                pass
+                return None
+
+            context.configure(
+                # ...
+                compare_type = my_compare_type
+            )
+
 
          ``inspected_column`` is a :class:`sqlalchemy.schema.Column` as returned by
          :meth:`sqlalchemy.engine.reflection.Inspector.reflecttable`, whereas
@@ -393,6 +399,10 @@ class EnvironmentContext(object):
          A return value of ``None`` indicates to allow default type
          comparison to proceed.
 
+         .. seealso::
+
+            :paramref:`.EnvironmentContext.configure.compare_server_default`
+
         :param compare_server_default: Indicates server default comparison
          behavior during
          an autogenerate operation.  Defaults to ``False`` which disables
@@ -414,7 +424,12 @@ class EnvironmentContext(object):
                 # return True if the defaults are different,
                 # False if not, or None to allow the default implementation
                 # to compare these defaults
-                pass
+                return None
+
+            context.configure(
+                # ...
+                compare_server_default = my_compare_server_default
+            )
 
          ``inspected_column`` is a dictionary structure as returned by
          :meth:`sqlalchemy.engine.reflection.Inspector.get_columns`, whereas
@@ -427,6 +442,10 @@ class EnvironmentContext(object):
          execute
          the two defaults on the database side to compare for equivalence.
 
+         .. seealso::
+
+            :paramref:`.EnvironmentContext.configure.compare_type`
+
         :param include_object: A callable function which is given
          the chance to return ``True`` or ``False`` for any object,
          indicating if the given object should be considered in the
@@ -440,8 +459,7 @@ class EnvironmentContext(object):
          * ``name``: the name of the object. This is typically available
            via ``object.name``.
          * ``type``: a string describing the type of object; currently
-           ``"table"`` or ``"column"``, but will include other types in a
-           future release
+           ``"table"`` or ``"column"``
          * ``reflected``: ``True`` if the given object was produced based on
            table reflection, ``False`` if it's from a local :class:`.MetaData`
            object.
@@ -463,8 +481,12 @@ class EnvironmentContext(object):
                 include_object = include_object
             )
 
-         The ``include_object`` filter will be expanded in a future release
-         to also receive type, constraint, and default objects.
+         :paramref:`.EnvironmentContext.configure.include_object` can also
+         be used to filter on specific schemas to include or omit, when
+         the :paramref:`.EnvironmentContext.configure.include_schemas`
+         flag is set to ``True``.   The :attr:`.Table.schema` attribute
+         on each :class:`.Table` object reflected will indicate the name of the
+         schema from which the :class:`.Table` originates.
 
          .. versionadded:: 0.6.0
 
@@ -502,7 +524,8 @@ class EnvironmentContext(object):
          :meth:`~sqlalchemy.engine.reflection.Inspector.get_schema_names`
          method, and include all differences in tables found across all
          those schemas.  When using this option, you may want to also
-         use the ``include_symbol`` option to specify a callable which
+         use the :paramref:`.EnvironmentContext.configure.include_object`
+         option to specify a callable which
          can filter the tables/schemas that get included.
 
          .. versionadded :: 0.4.0
@@ -532,9 +555,9 @@ class EnvironmentContext(object):
                 render_item = my_render_column
             )
 
-         Available values for the type string include: ``column``,
-         ``primary_key``, ``foreign_key``, ``unique``, ``check``,
-         ``type``, ``server_default``.
+         Available values for the type string include: ``"column"``,
+         ``"primary_key"``, ``"foreign_key"``, ``"unique"``, ``"check"``,
+         ``"type"``, ``"server_default"``.
 
          .. versionadded:: 0.5.0
 
diff --git a/docs/build/tutorial.rst b/docs/build/tutorial.rst
index b224e26c..fdab0758 100644
--- a/docs/build/tutorial.rst
+++ b/docs/build/tutorial.rst
@@ -566,13 +566,16 @@ Autogenerate will by default detect:
 
 Autogenerate can *optionally* detect:
 
-* Change of column type.  This will occur if you set ``compare_type=True``
-  on :meth:`.EnvironmentContext.configure`.  The feature works well in most cases,
+* Change of column type.  This will occur if you set
+  the :paramref:`.EnvironmentContext.configure.compare_type` parameter
+  to ``True``, or to a custom callable.
+  The feature works well in most cases,
   but is off by default so that it can be tested on the target schema
   first.  It can also be customized by passing a callable here; see the
   function's documentation for details.
 * Change of server default.  This will occur if you set
-  ``compare_server_default=True`` on :meth:`.EnvironmentContext.configure`.
+  the :paramref:`.EnvironmentContext.configure.compare_server_default`
+  paramter to ``True``, or to a custom callable.
   This feature works well for simple cases but cannot always produce
   accurate results.  The Postgresql backend will actually invoke
   the "detected" and "metadata" values against the database to