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, 98 insertions, 74 deletions

diff --git a/lib/sqlalchemy/sql/dml.py b/lib/sqlalchemy/sql/dml.py
index 1ac3acd8a..bc800de42 100644
--- a/lib/sqlalchemy/sql/dml.py
+++ b/lib/sqlalchemy/sql/dml.py
@@ -5,8 +5,8 @@
 # This module is part of SQLAlchemy and is released under
 # the MIT License: http://www.opensource.org/licenses/mit-license.php
 """
-Provide :class:`~.sql.expression.Insert`, :class:`.Update` and
-:class:`.Delete`.
+Provide :class:`_expression.Insert`, :class:`_expression.Update` and
+:class:`_expression.Delete`.
 
 """
 from sqlalchemy.types import NullType
@@ -303,7 +303,7 @@ class UpdateBase(
 
     def bind(self):
         """Return a 'bind' linked to this :class:`.UpdateBase`
-        or a :class:`.Table` associated with it.
+        or a :class:`_schema.Table` associated with it.
 
         """
         return self._bind or self.table.bind
@@ -330,7 +330,8 @@ class UpdateBase(
 
         The given collection of column expressions should be derived from
         the table that is
-        the target of the INSERT, UPDATE, or DELETE.  While :class:`.Column`
+        the target of the INSERT, UPDATE, or DELETE.  While
+        :class:`_schema.Column`
         objects are typical, the elements can also be expressions::
 
             stmt = table.insert().returning(
@@ -403,9 +404,9 @@ class UpdateBase(
 
         The text of the hint is rendered in the appropriate
         location for the database backend in use, relative
-        to the :class:`.Table` that is the subject of this
+        to the :class:`_schema.Table` that is the subject of this
         statement, or optionally to that of the given
-        :class:`.Table` passed as the ``selectable`` argument.
+        :class:`_schema.Table` passed as the ``selectable`` argument.
 
         The ``dialect_name`` option will limit the rendering of a particular
         hint to a particular backend. Such as, to add a hint
@@ -414,7 +415,7 @@ class UpdateBase(
             mytable.insert().with_hint("WITH (PAGLOCK)", dialect_name="mssql")
 
         :param text: Text of the hint.
-        :param selectable: optional :class:`.Table` that specifies
+        :param selectable: optional :class:`_schema.Table` that specifies
          an element of the FROM clause within an UPDATE or DELETE
          to be the subject of the hint - applies only to certain backends.
         :param dialect_name: defaults to ``*``, if specified as the name
@@ -457,10 +458,11 @@ class ValuesBase(UpdateBase):
         r"""specify a fixed VALUES clause for an INSERT statement, or the SET
         clause for an UPDATE.
 
-        Note that the :class:`~.sql.expression.Insert` and :class:`.Update`
+        Note that the :class:`_expression.Insert` and
+        :class:`_expression.Update`
         constructs support
         per-execution time formatting of the VALUES and/or SET clauses,
-        based on the arguments passed to :meth:`.Connection.execute`.
+        based on the arguments passed to :meth:`_engine.Connection.execute`.
         However, the :meth:`.ValuesBase.values` method can be used to "fix" a
         particular set of parameters into the statement.
 
@@ -473,7 +475,8 @@ class ValuesBase(UpdateBase):
         onto the existing list of values.
 
         :param \**kwargs: key value pairs representing the string key
-          of a :class:`.Column` mapped to the value to be rendered into the
+          of a :class:`_schema.Column`
+          mapped to the value to be rendered into the
           VALUES or SET clause::
 
                 users.insert().values(name="some name")
@@ -484,10 +487,11 @@ class ValuesBase(UpdateBase):
          a dictionary, tuple, or list of dictionaries or tuples can be passed
          as a single positional argument in order to form the VALUES or
          SET clause of the statement.  The forms that are accepted vary
-         based on whether this is an :class:`~.sql.expression.Insert` or an
-         :class:`.Update` construct.
+         based on whether this is an :class:`_expression.Insert` or an
+         :class:`_expression.Update` construct.
 
-         For either an :class:`~.sql.expression.Insert` or :class:`.Update`
+         For either an :class:`_expression.Insert` or
+         :class:`_expression.Update`
          construct, a single dictionary can be passed, which works the same as
          that of the kwargs form::
 
@@ -496,12 +500,12 @@ class ValuesBase(UpdateBase):
             users.update().values({"name": "some new name"})
 
          Also for either form but more typically for the
-         :class:`~.sql.expression.Insert` construct, a tuple that contains an
+         :class:`_expression.Insert` construct, a tuple that contains an
          entry for every column in the table is also accepted::
 
             users.insert().values((5, "some name"))
 
-         The :class:`~.sql.expression.Insert` construct also supports being
+         The :class:`_expression.Insert` construct also supports being
          passed a list of dictionaries or full-table-tuples, which on the
          server will render the less common SQL syntax of "multiple values" -
          this syntax is supported on backends such as SQLite, PostgreSQL,
@@ -524,7 +528,8 @@ class ValuesBase(UpdateBase):
          NOT the same as using traditional executemany() form**.  The above
          syntax is a **special** syntax not typically used.  To emit an
          INSERT statement against multiple rows, the normal method is
-         to pass a multiple values list to the :meth:`.Connection.execute`
+         to pass a multiple values list to the
+         :meth:`_engine.Connection.execute`
          method, which is supported by all database backends and is generally
          more efficient for a very large number of parameters.
 
@@ -536,7 +541,8 @@ class ValuesBase(UpdateBase):
 
            .. versionchanged:: 1.0.0 an INSERT that uses a multiple-VALUES
               clause, even a list of length one,
-              implies that the :paramref:`.Insert.inline` flag is set to
+              implies that the :paramref:`_expression.Insert.inline`
+              flag is set to
               True, indicating that the statement will not attempt to fetch
               the "last inserted primary key" or other defaults.  The
               statement deals with an arbitrary number of rows, so the
@@ -551,20 +557,20 @@ class ValuesBase(UpdateBase):
 
           The UPDATE construct also supports rendering the SET parameters
           in a specific order.  For this feature refer to the
-          :meth:`.Update.ordered_values` method.
+          :meth:`_expression.Update.ordered_values` method.
 
            .. seealso::
 
-              :meth:`.Update.ordered_values`
+              :meth:`_expression.Update.ordered_values`
 
         .. seealso::
 
             :ref:`inserts_and_updates` - SQL Expression
             Language Tutorial
 
-            :func:`~.expression.insert` - produce an ``INSERT`` statement
+            :func:`_expression.insert` - produce an ``INSERT`` statement
 
-            :func:`~.expression.update` - produce an ``UPDATE`` statement
+            :func:`_expression.update` - produce an ``UPDATE`` statement
 
         """
         if self._select_names:
@@ -677,7 +683,8 @@ class ValuesBase(UpdateBase):
         :meth:`.UpdateBase.returning` is not used simultaneously.  The column
         values will then be available on the result using the
         :attr:`.ResultProxy.returned_defaults` accessor as a dictionary,
-        referring to values keyed to the :class:`.Column` object as well as
+        referring to values keyed to the :class:`_schema.Column`
+        object as well as
         its ``.key``.
 
         This method differs from :meth:`.UpdateBase.returning` in these ways:
@@ -711,7 +718,8 @@ class ValuesBase(UpdateBase):
         an efficient implementation for the ``eager_defaults`` feature of
         :func:`.mapper`.
 
-        :param cols: optional list of column key names or :class:`.Column`
+        :param cols: optional list of column key names or
+         :class:`_schema.Column`
          objects.  If omitted, all column expressions evaluated on the server
          are added to the returning list.
 
@@ -730,8 +738,8 @@ class ValuesBase(UpdateBase):
 class Insert(ValuesBase):
     """Represent an INSERT construct.
 
-    The :class:`~.sql.expression.Insert` object is created using the
-    :func:`~.expression.insert()` function.
+    The :class:`_expression.Insert` object is created using the
+    :func:`_expression.insert()` function.
 
     .. seealso::
 
@@ -787,20 +795,22 @@ class Insert(ValuesBase):
         return_defaults=False,
         **dialect_kw
     ):
-        """Construct an :class:`~.sql.expression.Insert` object.
+        """Construct an :class:`_expression.Insert` object.
 
         Similar functionality is available via the
-        :meth:`~.TableClause.insert` method on
-        :class:`~.schema.Table`.
+        :meth:`_expression.TableClause.insert` method on
+        :class:`_schema.Table`.
 
-        :param table: :class:`.TableClause` which is the subject of the
+        :param table: :class:`_expression.TableClause`
+         which is the subject of the
          insert.
 
         :param values: collection of values to be inserted; see
-         :meth:`.Insert.values` for a description of allowed formats here.
-         Can be omitted entirely; a :class:`~.sql.expression.Insert` construct
+         :meth:`_expression.Insert.values`
+         for a description of allowed formats here.
+         Can be omitted entirely; a :class:`_expression.Insert` construct
          will also dynamically render the VALUES clause at execution time
-         based on the parameters passed to :meth:`.Connection.execute`.
+         based on the parameters passed to :meth:`_engine.Connection.execute`.
 
         :param inline: if True, no attempt will be made to retrieve the
          SQL-generated default values to be provided within the statement;
@@ -845,7 +855,7 @@ class Insert(ValuesBase):
 
     @_generative
     def inline(self):
-        """Make this :class:`~.sql.expression.Insert` construct "inline" .
+        """Make this :class:`_expression.Insert` construct "inline" .
 
         When set, no attempt will be made to retrieve the
         SQL-generated default values to be provided within the statement;
@@ -856,15 +866,16 @@ class Insert(ValuesBase):
         returning" feature for the statement.
 
 
-        .. versionchanged:: 1.4 the :paramref:`.Insert.inline` parameter
-           is now superseded by the :meth:`.Insert.inline` method.
+        .. versionchanged:: 1.4 the :paramref:`_expression.Insert.inline`
+           parameter
+           is now superseded by the :meth:`_expression.Insert.inline` method.
 
         """
         self._inline = True
 
     @_generative
     def from_select(self, names, select, include_defaults=True):
-        """Return a new :class:`~.sql.expression.Insert` construct which represents
+        """Return a new :class:`_expression.Insert` construct which represents
         an ``INSERT...FROM SELECT`` statement.
 
         e.g.::
@@ -872,19 +883,21 @@ class Insert(ValuesBase):
             sel = select([table1.c.a, table1.c.b]).where(table1.c.c > 5)
             ins = table2.insert().from_select(['a', 'b'], sel)
 
-        :param names: a sequence of string column names or :class:`.Column`
+        :param names: a sequence of string column names or
+         :class:`_schema.Column`
          objects representing the target columns.
-        :param select: a :func:`~.sql.expression.select` construct,
-         :class:`.FromClause`
-         or other construct which resolves into a :class:`.FromClause`,
-         such as an ORM :class:`.Query` object, etc.  The order of
+        :param select: a :func:`_expression.select` construct,
+         :class:`_expression.FromClause`
+         or other construct which resolves into a
+         :class:`_expression.FromClause`,
+         such as an ORM :class:`_query.Query` object, etc.  The order of
          columns returned from this FROM clause should correspond to the
          order of columns sent as the ``names`` parameter;  while this
          is not checked before passing along to the database, the database
          would normally raise an exception if these column lists don't
          correspond.
         :param include_defaults: if True, non-server default values and
-         SQL expressions as specified on :class:`.Column` objects
+         SQL expressions as specified on :class:`_schema.Column` objects
          (as documented in :ref:`metadata_defaults_toplevel`) not
          otherwise specified in the list of names will be rendered
          into the INSERT and SELECT statements, so that these values are also
@@ -894,13 +907,15 @@ class Insert(ValuesBase):
             will only be invoked **once** for the whole statement, and **not
             per row**.
 
-         .. versionadded:: 1.0.0 - :meth:`.Insert.from_select` now renders
+         .. versionadded:: 1.0.0 - :meth:`_expression.Insert.from_select`
+            now renders
             Python-side and SQL expression column defaults into the
             SELECT statement for columns otherwise not included in the
             list of column names.
 
         .. versionchanged:: 1.0.0 an INSERT that uses FROM SELECT
-           implies that the :paramref:`.insert.inline` flag is set to
+           implies that the :paramref:`_expression.insert.inline`
+           flag is set to
            True, indicating that the statement will not attempt to fetch
            the "last inserted primary key" or other defaults.  The statement
            deals with an arbitrary number of rows, so the
@@ -937,7 +952,8 @@ class DMLWhereBase(object):
 class Update(DMLWhereBase, ValuesBase):
     """Represent an Update construct.
 
-    The :class:`.Update` object is created using the :func:`update()`
+    The :class:`_expression.Update`
+    object is created using the :func:`update()`
     function.
 
     """
@@ -987,7 +1003,7 @@ class Update(DMLWhereBase, ValuesBase):
         preserve_parameter_order=False,
         **dialect_kw
     ):
-        r"""Construct an :class:`.Update` object.
+        r"""Construct an :class:`_expression.Update` object.
 
         E.g.::
 
@@ -997,14 +1013,15 @@ class Update(DMLWhereBase, ValuesBase):
                     values(name='user #5')
 
         Similar functionality is available via the
-        :meth:`~.TableClause.update` method on
-        :class:`.Table`::
+        :meth:`_expression.TableClause.update` method on
+        :class:`_schema.Table`::
 
             stmt = users.update().\
                         where(users.c.id==5).\
                         values(name='user #5')
 
-        :param table: A :class:`.Table` object representing the database
+        :param table: A :class:`_schema.Table`
+         object representing the database
          table to be updated.
 
         :param whereclause: Optional SQL expression describing the ``WHERE``
@@ -1035,11 +1052,11 @@ class Update(DMLWhereBase, ValuesBase):
           the ``SET`` clause generates for all columns.
 
           Modern applications may prefer to use the generative
-          :meth:`.Update.values` method to set the values of the
+          :meth:`_expression.Update.values` method to set the values of the
           UPDATE statement.
 
         :param inline:
-          if True, SQL defaults present on :class:`.Column` objects via
+          if True, SQL defaults present on :class:`_schema.Column` objects via
           the ``default`` keyword will be compiled 'inline' into the statement
           and not pre-executed.  This means that their values will not
           be available in the dictionary returned from
@@ -1047,7 +1064,8 @@ class Update(DMLWhereBase, ValuesBase):
 
         :param preserve_parameter_order: if True, the update statement is
           expected to receive parameters **only** via the
-          :meth:`.Update.values` method, and they must be passed as a Python
+          :meth:`_expression.Update.values` method,
+          and they must be passed as a Python
           ``list`` of 2-tuples. The rendered UPDATE statement will emit the SET
           clause for each referenced column maintaining this order.
 
@@ -1056,18 +1074,18 @@ class Update(DMLWhereBase, ValuesBase):
           .. seealso::
 
             :ref:`updates_order_parameters` - illustrates the
-            :meth:`.Update.ordered_values` method.
+            :meth:`_expression.Update.ordered_values` method.
 
         If both ``values`` and compile-time bind parameters are present, the
         compile-time bind parameters override the information specified
         within ``values`` on a per-key basis.
 
-        The keys within ``values`` can be either :class:`.Column`
+        The keys within ``values`` can be either :class:`_schema.Column`
         objects or their string identifiers (specifically the "key" of the
-        :class:`.Column`, normally but not necessarily equivalent to
+        :class:`_schema.Column`, normally but not necessarily equivalent to
         its "name").  Normally, the
-        :class:`.Column` objects used here are expected to be
-        part of the target :class:`.Table` that is the table
+        :class:`_schema.Column` objects used here are expected to be
+        part of the target :class:`_schema.Table` that is the table
         to be updated.  However when using MySQL, a multiple-table
         UPDATE statement can refer to columns from any of
         the tables referred to in the WHERE clause.
@@ -1075,14 +1093,14 @@ class Update(DMLWhereBase, ValuesBase):
         The values referred to in ``values`` are typically:
 
         * a literal data value (i.e. string, number, etc.)
-        * a SQL expression, such as a related :class:`.Column`,
-          a scalar-returning :func:`~.sql.expression.select` construct,
+        * a SQL expression, such as a related :class:`_schema.Column`,
+          a scalar-returning :func:`_expression.select` construct,
           etc.
 
-        when combining :func:`~.sql.expression.select` constructs within the
-        values clause of an :func:`.update`
+        when combining :func:`_expression.select` constructs within the
+        values clause of an :func:`_expression.update`
         construct, the subquery represented
-        by the :func:`~.sql.expression.select` should be *correlated* to the
+        by the :func:`_expression.select` should be *correlated* to the
         parent table, that is, providing criterion which links the table inside
         the subquery to the outer table being updated::
 
@@ -1127,10 +1145,12 @@ class Update(DMLWhereBase, ValuesBase):
         .. seealso::
 
            :ref:`updates_order_parameters` - full example of the
-           :meth:`.Update.ordered_values` method.
+           :meth:`_expression.Update.ordered_values` method.
 
-        .. versionchanged:: 1.4 The :meth:`.Update.ordered_values` method
-           supersedes the :paramref:`.update.preserve_parameter_order`
+        .. versionchanged:: 1.4 The :meth:`_expression.Update.ordered_values`
+           method
+           supersedes the
+           :paramref:`_expression.update.preserve_parameter_order`
            parameter, which will be removed in SQLAlchemy 2.0.
 
         """
@@ -1158,16 +1178,18 @@ class Update(DMLWhereBase, ValuesBase):
 
     @_generative
     def inline(self):
-        """Make this :class:`.Update` construct "inline" .
+        """Make this :class:`_expression.Update` construct "inline" .
 
-        When set, SQL defaults present on :class:`.Column` objects via the
+        When set, SQL defaults present on :class:`_schema.Column`
+        objects via the
         ``default`` keyword will be compiled 'inline' into the statement and
         not pre-executed.  This means that their values will not be available
         in the dictionary returned from
         :meth:`.ResultProxy.last_updated_params`.
 
-        .. versionchanged:: 1.4 the :paramref:`.update.inline` parameter
-           is now superseded by the :meth:`.Update.inline` method.
+        .. versionchanged:: 1.4 the :paramref:`_expression.update.inline`
+           parameter
+           is now superseded by the :meth:`_expression.Update.inline` method.
 
         """
         self._inline = True
@@ -1176,7 +1198,8 @@ class Update(DMLWhereBase, ValuesBase):
 class Delete(DMLWhereBase, UpdateBase):
     """Represent a DELETE construct.
 
-    The :class:`.Delete` object is created using the :func:`delete()`
+    The :class:`_expression.Delete`
+    object is created using the :func:`delete()`
     function.
 
     """
@@ -1210,15 +1233,16 @@ class Delete(DMLWhereBase, UpdateBase):
         prefixes=None,
         **dialect_kw
     ):
-        r"""Construct :class:`.Delete` object.
+        r"""Construct :class:`_expression.Delete` object.
 
         Similar functionality is available via the
-        :meth:`~.TableClause.delete` method on
-        :class:`~.schema.Table`.
+        :meth:`_expression.TableClause.delete` method on
+        :class:`_schema.Table`.
 
         :param table: The table to delete rows from.
 
-        :param whereclause: A :class:`.ClauseElement` describing the ``WHERE``
+        :param whereclause: A :class:`_expression.ClauseElement`
+          describing the ``WHERE``
           condition of the ``DELETE`` statement. Note that the
           :meth:`~Delete.where()` generative method may be used instead.