Run search and replace of symbolic module names

Replaces a wide array of Sphinx-relative doc references
with an abbreviated absolute form now supported by
zzzeeksphinx.

Change-Id: I94bffcc3f37885ffdde6238767224296339698a2

1 files changed, 79 insertions, 51 deletions

diff --git a/lib/sqlalchemy/ext/automap.py b/lib/sqlalchemy/ext/automap.py
index e409cf38c..4ae3a415e 100644
--- a/lib/sqlalchemy/ext/automap.py
+++ b/lib/sqlalchemy/ext/automap.py
@@ -60,12 +60,16 @@ asking it to reflect the schema and produce mappings::
 
 Above, calling :meth:`.AutomapBase.prepare` while passing along the
 :paramref:`.AutomapBase.prepare.reflect` parameter indicates that the
-:meth:`.MetaData.reflect` method will be called on this declarative base
-classes' :class:`.MetaData` collection; then, each **viable**
-:class:`.Table` within the :class:`.MetaData` will get a new mapped class
-generated automatically.  The :class:`.ForeignKeyConstraint` objects which
+:meth:`_schema.MetaData.reflect`
+method will be called on this declarative base
+classes' :class:`_schema.MetaData` collection; then, each **viable**
+:class:`_schema.Table` within the :class:`_schema.MetaData`
+will get a new mapped class
+generated automatically.  The :class:`_schema.ForeignKeyConstraint`
+objects which
 link the various tables together will be used to produce new, bidirectional
-:func:`.relationship` objects between classes.   The classes and relationships
+:func:`_orm.relationship` objects between classes.
+The classes and relationships
 follow along a default naming scheme that we can customize.  At this point,
 our basic mapping consisting of related ``User`` and ``Address`` classes is
 ready to use in the traditional way.
@@ -79,10 +83,12 @@ ready to use in the traditional way.
 Generating Mappings from an Existing MetaData
 =============================================
 
-We can pass a pre-declared :class:`.MetaData` object to :func:`.automap_base`.
+We can pass a pre-declared :class:`_schema.MetaData` object to
+:func:`.automap_base`.
 This object can be constructed in any way, including programmatically, from
 a serialized file, or from itself being reflected using
-:meth:`.MetaData.reflect`.  Below we illustrate a combination of reflection and
+:meth:`_schema.MetaData.reflect`.
+Below we illustrate a combination of reflection and
 explicit table declaration::
 
     from sqlalchemy import create_engine, MetaData, Table, Column, ForeignKey
@@ -160,7 +166,7 @@ established based on the table name we use.  If our schema contains tables
     print (a1.user)
 
 Above, one of the more intricate details is that we illustrated overriding
-one of the :func:`.relationship` objects that automap would have created.
+one of the :func:`_orm.relationship` objects that automap would have created.
 To do this, we needed to make sure the names match up with what automap
 would normally generate, in that the relationship name would be
 ``User.address_collection`` and the name of the class referred to, from
@@ -226,39 +232,43 @@ Relationship Detection
 ======================
 
 The vast majority of what automap accomplishes is the generation of
-:func:`.relationship` structures based on foreign keys.  The mechanism
+:func:`_orm.relationship` structures based on foreign keys.  The mechanism
 by which this works for many-to-one and one-to-many relationships is as
 follows:
 
-1. A given :class:`.Table`, known to be mapped to a particular class,
-   is examined for :class:`.ForeignKeyConstraint` objects.
+1. A given :class:`_schema.Table`, known to be mapped to a particular class,
+   is examined for :class:`_schema.ForeignKeyConstraint` objects.
 
-2. From each :class:`.ForeignKeyConstraint`, the remote :class:`.Table`
+2. From each :class:`_schema.ForeignKeyConstraint`, the remote
+   :class:`_schema.Table`
    object present is matched up to the class to which it is to be mapped,
    if any, else it is skipped.
 
-3. As the :class:`.ForeignKeyConstraint` we are examining corresponds to a
+3. As the :class:`_schema.ForeignKeyConstraint`
+   we are examining corresponds to a
    reference from the immediate mapped class,  the relationship will be set up
    as a many-to-one referring to the referred class; a corresponding
    one-to-many backref will be created on the referred class referring
    to this class.
 
-4. If any of the columns that are part of the :class:`.ForeignKeyConstraint`
+4. If any of the columns that are part of the
+   :class:`_schema.ForeignKeyConstraint`
    are not nullable (e.g. ``nullable=False``), a
-   :paramref:`~.relationship.cascade` keyword argument
+   :paramref:`_orm.relationship.cascade` keyword argument
    of ``all, delete-orphan`` will be added to the keyword arguments to
    be passed to the relationship or backref.  If the
-   :class:`.ForeignKeyConstraint` reports that
-   :paramref:`.ForeignKeyConstraint.ondelete`
+   :class:`_schema.ForeignKeyConstraint` reports that
+   :paramref:`_schema.ForeignKeyConstraint.ondelete`
    is set to ``CASCADE`` for a not null or ``SET NULL`` for a nullable
-   set of columns, the option :paramref:`~.relationship.passive_deletes`
+   set of columns, the option :paramref:`_orm.relationship.passive_deletes`
    flag is set to ``True`` in the set of relationship keyword arguments.
    Note that not all backends support reflection of ON DELETE.
 
    .. versionadded:: 1.0.0 - automap will detect non-nullable foreign key
       constraints when producing a one-to-many relationship and establish
       a default cascade of ``all, delete-orphan`` if so; additionally,
-      if the constraint specifies :paramref:`.ForeignKeyConstraint.ondelete`
+      if the constraint specifies
+      :paramref:`_schema.ForeignKeyConstraint.ondelete`
       of ``CASCADE`` for non-nullable or ``SET NULL`` for nullable columns,
       the ``passive_deletes=True`` option is also added.
 
@@ -274,18 +284,20 @@ follows:
 6. The classes are inspected for an existing mapped property matching these
    names.  If one is detected on one side, but none on the other side,
    :class:`.AutomapBase` attempts to create a relationship on the missing side,
-   then uses the :paramref:`.relationship.back_populates` parameter in order to
+   then uses the :paramref:`_orm.relationship.back_populates`
+   parameter in order to
    point the new relationship to the other side.
 
 7. In the usual case where no relationship is on either side,
-   :meth:`.AutomapBase.prepare` produces a :func:`.relationship` on the
+   :meth:`.AutomapBase.prepare` produces a :func:`_orm.relationship` on the
    "many-to-one" side and matches it to the other using the
-   :paramref:`.relationship.backref` parameter.
+   :paramref:`_orm.relationship.backref` parameter.
 
-8. Production of the :func:`.relationship` and optionally the :func:`.backref`
+8. Production of the :func:`_orm.relationship` and optionally the
+   :func:`.backref`
    is handed off to the :paramref:`.AutomapBase.prepare.generate_relationship`
    function, which can be supplied by the end-user in order to augment
-   the arguments passed to :func:`.relationship` or :func:`.backref` or to
+   the arguments passed to :func:`_orm.relationship` or :func:`.backref` or to
    make use of custom implementations of these functions.
 
 Custom Relationship Arguments
@@ -298,8 +310,8 @@ the object, after augmenting the given keyword dictionary with our own
 arguments.
 
 Below is an illustration of how to send
-:paramref:`.relationship.cascade` and
-:paramref:`.relationship.passive_deletes`
+:paramref:`_orm.relationship.cascade` and
+:paramref:`_orm.relationship.passive_deletes`
 options along to all one-to-many relationships::
 
     from sqlalchemy.ext.automap import generate_relationship
@@ -331,20 +343,24 @@ Many-to-Many relationships
 those which contain a ``secondary`` argument.  The process for producing these
 is as follows:
 
-1. A given :class:`.Table` is examined for :class:`.ForeignKeyConstraint`
+1. A given :class:`_schema.Table` is examined for
+   :class:`_schema.ForeignKeyConstraint`
    objects, before any mapped class has been assigned to it.
 
-2. If the table contains two and exactly two :class:`.ForeignKeyConstraint`
+2. If the table contains two and exactly two
+   :class:`_schema.ForeignKeyConstraint`
    objects, and all columns within this table are members of these two
-   :class:`.ForeignKeyConstraint` objects, the table is assumed to be a
+   :class:`_schema.ForeignKeyConstraint` objects, the table is assumed to be a
    "secondary" table, and will **not be mapped directly**.
 
 3. The two (or one, for self-referential) external tables to which the
-   :class:`.Table` refers to are matched to the classes to which they will be
+   :class:`_schema.Table`
+   refers to are matched to the classes to which they will be
    mapped, if any.
 
 4. If mapped classes for both sides are located, a many-to-many bi-directional
-   :func:`.relationship` / :func:`.backref` pair is created between the two
+   :func:`_orm.relationship` / :func:`.backref`
+   pair is created between the two
    classes.
 
 5. The override logic for many-to-many works the same as that of one-to-many/
@@ -469,7 +485,8 @@ Using Automap with Explicit Declarations
 ========================================
 
 As noted previously, automap has no dependency on reflection, and can make
-use of any collection of :class:`.Table` objects within a :class:`.MetaData`
+use of any collection of :class:`_schema.Table` objects within a
+:class:`_schema.MetaData`
 collection.  From this, it follows that automap can also be used
 generate missing relationships given an otherwise complete model that fully
 defines table metadata::
@@ -503,7 +520,7 @@ defines table metadata::
     assert a1.user is u1
 
 Above, given mostly complete ``User`` and ``Address`` mappings, the
-:class:`.ForeignKey` which we defined on ``Address.user_id`` allowed a
+:class:`_schema.ForeignKey` which we defined on ``Address.user_id`` allowed a
 bidirectional relationship pair ``Address.user`` and
 ``User.address_collection`` to be generated on the mapped classes.
 
@@ -539,9 +556,9 @@ def classname_for_table(base, tablename, table):
 
     :param base: the :class:`.AutomapBase` class doing the prepare.
 
-    :param tablename: string name of the :class:`.Table`.
+    :param tablename: string name of the :class:`_schema.Table`.
 
-    :param table: the :class:`.Table` object itself.
+    :param table: the :class:`_schema.Table` object itself.
 
     :return: a string class name.
 
@@ -549,7 +566,8 @@ def classname_for_table(base, tablename, table):
 
         In Python 2, the string used for the class name **must** be a
         non-Unicode object, e.g. a ``str()`` object.  The ``.name`` attribute
-        of :class:`.Table` is typically a Python unicode subclass, so the
+        of :class:`_schema.Table` is typically a Python unicode subclass,
+        so the
         ``str()`` function should be applied to this name, after accounting for
         any non-ASCII characters.
 
@@ -575,7 +593,7 @@ def name_for_scalar_relationship(base, local_cls, referred_cls, constraint):
 
     :param referred_cls: the class to be mapped on the referring side.
 
-    :param constraint: the :class:`.ForeignKeyConstraint` that is being
+    :param constraint: the :class:`_schema.ForeignKeyConstraint` that is being
      inspected to produce this relationship.
 
     """
@@ -603,7 +621,7 @@ def name_for_collection_relationship(
 
     :param referred_cls: the class to be mapped on the referring side.
 
-    :param constraint: the :class:`.ForeignKeyConstraint` that is being
+    :param constraint: the :class:`_schema.ForeignKeyConstraint` that is being
      inspected to produce this relationship.
 
     """
@@ -613,7 +631,8 @@ def name_for_collection_relationship(
 def generate_relationship(
     base, direction, return_fn, attrname, local_cls, referred_cls, **kw
 ):
-    r"""Generate a :func:`.relationship` or :func:`.backref` on behalf of two
+    r"""Generate a :func:`_orm.relationship` or :func:`.backref`
+    on behalf of two
     mapped classes.
 
     An alternate implementation of this function can be specified using the
@@ -634,9 +653,10 @@ def generate_relationship(
      be one of :data:`.ONETOMANY`, :data:`.MANYTOONE`, :data:`.MANYTOMANY`.
 
     :param return_fn: the function that is used by default to create the
-     relationship.  This will be either :func:`.relationship` or
+     relationship.  This will be either :func:`_orm.relationship` or
      :func:`.backref`.  The :func:`.backref` function's result will be used to
-     produce a new :func:`.relationship` in a second step, so it is critical
+     produce a new :func:`_orm.relationship` in a second step,
+     so it is critical
      that user-defined implementations correctly differentiate between the two
      functions, if a custom relationship function is being used.
 
@@ -654,7 +674,8 @@ def generate_relationship(
     :param \**kw: all additional keyword arguments are passed along to the
      function.
 
-    :return: a :func:`.relationship` or :func:`.backref` construct, as dictated
+    :return: a :func:`_orm.relationship` or :func:`.backref` construct,
+     as dictated
      by the :paramref:`.generate_relationship.return_fn` parameter.
 
     """
@@ -710,19 +731,24 @@ class AutomapBase(object):
         name_for_collection_relationship=name_for_collection_relationship,
         generate_relationship=generate_relationship,
     ):
-        """Extract mapped classes and relationships from the :class:`.MetaData` and
+        """Extract mapped classes and relationships from the
+        :class:`_schema.MetaData` and
         perform mappings.
 
-        :param engine: an :class:`.Engine` or :class:`.Connection` with which
+        :param engine: an :class:`_engine.Engine` or
+         :class:`_engine.Connection` with which
          to perform schema reflection, if specified.
          If the :paramref:`.AutomapBase.prepare.reflect` argument is False,
          this object is not used.
 
-        :param reflect: if True, the :meth:`.MetaData.reflect` method is called
-         on the :class:`.MetaData` associated with this :class:`.AutomapBase`.
-         The :class:`.Engine` passed via
+        :param reflect: if True, the :meth:`_schema.MetaData.reflect`
+         method is called
+         on the :class:`_schema.MetaData` associated with this
+         :class:`.AutomapBase`.
+         The :class:`_engine.Engine` passed via
          :paramref:`.AutomapBase.prepare.engine` will be used to perform the
-         reflection if present; else, the :class:`.MetaData` should already be
+         reflection if present; else, the :class:`_schema.MetaData`
+         should already be
          bound to some engine else the operation will fail.
 
         :param classname_for_table: callable function which will be used to
@@ -738,16 +764,18 @@ class AutomapBase(object):
          relationships.  Defaults to :func:`.name_for_collection_relationship`.
 
         :param generate_relationship: callable function which will be used to
-         actually generate :func:`.relationship` and :func:`.backref`
+         actually generate :func:`_orm.relationship` and :func:`.backref`
          constructs.  Defaults to :func:`.generate_relationship`.
 
         :param collection_class: the Python collection class that will be used
-         when a new :func:`.relationship` object is created that represents a
+         when a new :func:`_orm.relationship`
+         object is created that represents a
          collection.  Defaults to ``list``.
 
         :param schema: When present in conjunction with the
          :paramref:`.AutomapBase.prepare.reflect` flag, is passed to
-         :meth:`.MetaData.reflect` to indicate the primary schema where tables
+         :meth:`_schema.MetaData.reflect`
+         to indicate the primary schema where tables
          should be reflected from.  When omitted, the default schema in use
          by the database connection is used.