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, 100 insertions, 76 deletions

diff --git a/lib/sqlalchemy/engine/events.py b/lib/sqlalchemy/engine/events.py
index 32292c826..46459cf73 100644
--- a/lib/sqlalchemy/engine/events.py
+++ b/lib/sqlalchemy/engine/events.py
@@ -15,13 +15,13 @@ from .. import exc
 
 class ConnectionEvents(event.Events):
     """Available events for :class:`.Connectable`, which includes
-    :class:`.Connection` and :class:`.Engine`.
+    :class:`_engine.Connection` and :class:`_engine.Engine`.
 
     The methods here define the name of an event as well as the names of
     members that are passed to listener functions.
 
     An event listener can be associated with any :class:`.Connectable`
-    class or instance, such as an :class:`.Engine`, e.g.::
+    class or instance, such as an :class:`_engine.Engine`, e.g.::
 
         from sqlalchemy import event, create_engine
 
@@ -32,7 +32,7 @@ class ConnectionEvents(event.Events):
         engine = create_engine('postgresql://scott:tiger@localhost/test')
         event.listen(engine, "before_cursor_execute", before_cursor_execute)
 
-    or with a specific :class:`.Connection`::
+    or with a specific :class:`_engine.Connection`::
 
         with engine.begin() as conn:
             @event.listens_for(conn, 'before_cursor_execute')
@@ -62,19 +62,23 @@ class ConnectionEvents(event.Events):
             return statement, parameters
 
     .. note:: :class:`.ConnectionEvents` can be established on any
-       combination of :class:`.Engine`, :class:`.Connection`, as well
+       combination of :class:`_engine.Engine`, :class:`_engine.Connection`,
+       as well
        as instances of each of those classes.  Events across all
        four scopes will fire off for a given instance of
-       :class:`.Connection`.  However, for performance reasons, the
-       :class:`.Connection` object determines at instantiation time
-       whether or not its parent :class:`.Engine` has event listeners
-       established.   Event listeners added to the :class:`.Engine`
-       class or to an instance of :class:`.Engine` *after* the instantiation
-       of a dependent :class:`.Connection` instance will usually
-       *not* be available on that :class:`.Connection` instance.  The newly
-       added listeners will instead take effect for :class:`.Connection`
+       :class:`_engine.Connection`.  However, for performance reasons, the
+       :class:`_engine.Connection` object determines at instantiation time
+       whether or not its parent :class:`_engine.Engine` has event listeners
+       established.   Event listeners added to the :class:`_engine.Engine`
+       class or to an instance of :class:`_engine.Engine`
+       *after* the instantiation
+       of a dependent :class:`_engine.Connection` instance will usually
+       *not* be available on that :class:`_engine.Connection` instance.
+       The newly
+       added listeners will instead take effect for
+       :class:`_engine.Connection`
        instances created subsequent to those event listeners being
-       established on the parent :class:`.Engine` class or instance.
+       established on the parent :class:`_engine.Engine` class or instance.
 
     :param retval=False: Applies to the :meth:`.before_execute` and
       :meth:`.before_cursor_execute` events only.  When True, the
@@ -156,9 +160,10 @@ class ConnectionEvents(event.Events):
                 # do something with clauseelement, multiparams, params
                 return clauseelement, multiparams, params
 
-        :param conn: :class:`.Connection` object
+        :param conn: :class:`_engine.Connection` object
         :param clauseelement: SQL expression construct, :class:`.Compiled`
-         instance, or string statement passed to :meth:`.Connection.execute`.
+         instance, or string statement passed to
+         :meth:`_engine.Connection.execute`.
         :param multiparams: Multiple parameter sets, a list of dictionaries.
         :param params: Single parameter set, a single dictionary.
 
@@ -172,9 +177,10 @@ class ConnectionEvents(event.Events):
         """Intercept high level execute() events after execute.
 
 
-        :param conn: :class:`.Connection` object
+        :param conn: :class:`_engine.Connection` object
         :param clauseelement: SQL expression construct, :class:`.Compiled`
-         instance, or string statement passed to :meth:`.Connection.execute`.
+         instance, or string statement passed to
+         :meth:`_engine.Connection.execute`.
         :param multiparams: Multiple parameter sets, a list of dictionaries.
         :param params: Single parameter set, a single dictionary.
         :param result: :class:`.ResultProxy` generated by the execution.
@@ -204,7 +210,7 @@ class ConnectionEvents(event.Events):
 
         See the example at :class:`.ConnectionEvents`.
 
-        :param conn: :class:`.Connection` object
+        :param conn: :class:`_engine.Connection` object
         :param cursor: DBAPI cursor object
         :param statement: string SQL statement, as to be passed to the DBAPI
         :param parameters: Dictionary, tuple, or list of parameters being
@@ -228,7 +234,7 @@ class ConnectionEvents(event.Events):
     ):
         """Intercept low-level cursor execute() events after execution.
 
-        :param conn: :class:`.Connection` object
+        :param conn: :class:`_engine.Connection` object
         :param cursor: DBAPI cursor object.  Will have results pending
          if the statement was a SELECT, but these should not be consumed
          as they will be needed by the :class:`.ResultProxy`.
@@ -244,7 +250,8 @@ class ConnectionEvents(event.Events):
         """
 
     def handle_error(self, exception_context):
-        r"""Intercept all exceptions processed by the :class:`.Connection`.
+        r"""Intercept all exceptions processed by the
+        :class:`_engine.Connection`.
 
         This includes all exceptions emitted by the DBAPI as well as
         within SQLAlchemy's statement invocation process, including
@@ -362,9 +369,9 @@ class ConnectionEvents(event.Events):
            ``False``.
 
         .. versionchanged:: 1.0.0 The :meth:`.handle_error` event is now
-           invoked when an :class:`.Engine` fails during the initial
-           call to :meth:`.Engine.connect`, as well as when a
-           :class:`.Connection` object encounters an error during a
+           invoked when an :class:`_engine.Engine` fails during the initial
+           call to :meth:`_engine.Engine.connect`, as well as when a
+           :class:`_engine.Connection` object encounters an error during a
            reconnect operation.
 
         .. versionchanged:: 1.0.0 The :meth:`.handle_error` event is
@@ -380,32 +387,39 @@ class ConnectionEvents(event.Events):
         """
 
     def engine_connect(self, conn, branch):
-        """Intercept the creation of a new :class:`.Connection`.
+        """Intercept the creation of a new :class:`_engine.Connection`.
 
         This event is called typically as the direct result of calling
-        the :meth:`.Engine.connect` method.
+        the :meth:`_engine.Engine.connect` method.
 
-        It differs from the :meth:`.PoolEvents.connect` method, which
+        It differs from the :meth:`_events.PoolEvents.connect` method, which
         refers to the actual connection to a database at the DBAPI level;
         a DBAPI connection may be pooled and reused for many operations.
         In contrast, this event refers only to the production of a higher level
-        :class:`.Connection` wrapper around such a DBAPI connection.
+        :class:`_engine.Connection` wrapper around such a DBAPI connection.
 
-        It also differs from the :meth:`.PoolEvents.checkout` event
-        in that it is specific to the :class:`.Connection` object, not the
-        DBAPI connection that :meth:`.PoolEvents.checkout` deals with, although
+        It also differs from the :meth:`_events.PoolEvents.checkout` event
+        in that it is specific to the :class:`_engine.Connection` object,
+        not the
+        DBAPI connection that :meth:`_events.PoolEvents.checkout` deals with,
+        although
         this DBAPI connection is available here via the
-        :attr:`.Connection.connection` attribute.  But note there can in fact
-        be multiple :meth:`.PoolEvents.checkout` events within the lifespan
-        of a single :class:`.Connection` object, if that :class:`.Connection`
+        :attr:`_engine.Connection.connection` attribute.
+        But note there can in fact
+        be multiple :meth:`_events.PoolEvents.checkout`
+        events within the lifespan
+        of a single :class:`_engine.Connection` object, if that
+        :class:`_engine.Connection`
         is invalidated and re-established.  There can also be multiple
-        :class:`.Connection` objects generated for the same already-checked-out
-        DBAPI connection, in the case that a "branch" of a :class:`.Connection`
+        :class:`_engine.Connection`
+        objects generated for the same already-checked-out
+        DBAPI connection, in the case that a "branch" of a
+        :class:`_engine.Connection`
         is produced.
 
-        :param conn: :class:`.Connection` object.
+        :param conn: :class:`_engine.Connection` object.
         :param branch: if True, this is a "branch" of an existing
-         :class:`.Connection`.  A branch is generated within the course
+         :class:`_engine.Connection`.  A branch is generated within the course
          of a statement execution to invoke supplemental statements, most
          typically to pre-execute a SELECT of a default value for the purposes
          of an INSERT statement.
@@ -419,81 +433,91 @@ class ConnectionEvents(event.Events):
             to transparently ensure pooled connections are connected to the
             database.
 
-            :meth:`.PoolEvents.checkout` the lower-level pool checkout event
+            :meth:`_events.PoolEvents.checkout`
+            the lower-level pool checkout event
             for an individual DBAPI connection
 
             :meth:`.ConnectionEvents.set_connection_execution_options` - a copy
-            of a :class:`.Connection` is also made when the
-            :meth:`.Connection.execution_options` method is called.
+            of a :class:`_engine.Connection` is also made when the
+            :meth:`_engine.Connection.execution_options` method is called.
 
         """
 
     def set_connection_execution_options(self, conn, opts):
-        """Intercept when the :meth:`.Connection.execution_options`
+        """Intercept when the :meth:`_engine.Connection.execution_options`
         method is called.
 
-        This method is called after the new :class:`.Connection` has been
+        This method is called after the new :class:`_engine.Connection`
+        has been
         produced, with the newly updated execution options collection, but
         before the :class:`.Dialect` has acted upon any of those new options.
 
-        Note that this method is not called when a new :class:`.Connection`
+        Note that this method is not called when a new
+        :class:`_engine.Connection`
         is produced which is inheriting execution options from its parent
-        :class:`.Engine`; to intercept this condition, use the
+        :class:`_engine.Engine`; to intercept this condition, use the
         :meth:`.ConnectionEvents.engine_connect` event.
 
-        :param conn: The newly copied :class:`.Connection` object
+        :param conn: The newly copied :class:`_engine.Connection` object
 
         :param opts: dictionary of options that were passed to the
-         :meth:`.Connection.execution_options` method.
+         :meth:`_engine.Connection.execution_options` method.
 
         .. versionadded:: 0.9.0
 
         .. seealso::
 
             :meth:`.ConnectionEvents.set_engine_execution_options` - event
-            which is called when :meth:`.Engine.execution_options` is called.
+            which is called when :meth:`_engine.Engine.execution_options`
+            is called.
 
 
         """
 
     def set_engine_execution_options(self, engine, opts):
-        """Intercept when the :meth:`.Engine.execution_options`
+        """Intercept when the :meth:`_engine.Engine.execution_options`
         method is called.
 
-        The :meth:`.Engine.execution_options` method produces a shallow
-        copy of the :class:`.Engine` which stores the new options.  That new
-        :class:`.Engine` is passed here.   A particular application of this
+        The :meth:`_engine.Engine.execution_options` method produces a shallow
+        copy of the :class:`_engine.Engine` which stores the new options.
+        That new
+        :class:`_engine.Engine` is passed here.
+        A particular application of this
         method is to add a :meth:`.ConnectionEvents.engine_connect` event
-        handler to the given :class:`.Engine` which will perform some per-
-        :class:`.Connection` task specific to these execution options.
+        handler to the given :class:`_engine.Engine`
+        which will perform some per-
+        :class:`_engine.Connection` task specific to these execution options.
 
-        :param conn: The newly copied :class:`.Engine` object
+        :param conn: The newly copied :class:`_engine.Engine` object
 
         :param opts: dictionary of options that were passed to the
-         :meth:`.Connection.execution_options` method.
+         :meth:`_engine.Connection.execution_options` method.
 
         .. versionadded:: 0.9.0
 
         .. seealso::
 
             :meth:`.ConnectionEvents.set_connection_execution_options` - event
-            which is called when :meth:`.Connection.execution_options` is
+            which is called when :meth:`_engine.Connection.execution_options`
+            is
             called.
 
         """
 
     def engine_disposed(self, engine):
-        """Intercept when the :meth:`.Engine.dispose` method is called.
+        """Intercept when the :meth:`_engine.Engine.dispose` method is called.
 
-        The :meth:`.Engine.dispose` method instructs the engine to
-        "dispose" of it's connection pool (e.g. :class:`.Pool`), and
+        The :meth:`_engine.Engine.dispose` method instructs the engine to
+        "dispose" of it's connection pool (e.g. :class:`_pool.Pool`), and
         replaces it with a new one.  Disposing of the old pool has the
         effect that existing checked-in connections are closed.  The new
         pool does not establish any new connections until it is first used.
 
         This event can be used to indicate that resources related to the
-        :class:`.Engine` should also be cleaned up, keeping in mind that the
-        :class:`.Engine` can still be used for new requests in which case
+        :class:`_engine.Engine` should also be cleaned up,
+        keeping in mind that the
+        :class:`_engine.Engine`
+        can still be used for new requests in which case
         it re-acquires connection resources.
 
         .. versionadded:: 1.0.5
@@ -503,7 +527,7 @@ class ConnectionEvents(event.Events):
     def begin(self, conn):
         """Intercept begin() events.
 
-        :param conn: :class:`.Connection` object
+        :param conn: :class:`_engine.Connection` object
 
         """
 
@@ -511,17 +535,17 @@ class ConnectionEvents(event.Events):
         """Intercept rollback() events, as initiated by a
         :class:`.Transaction`.
 
-        Note that the :class:`.Pool` also "auto-rolls back"
+        Note that the :class:`_pool.Pool` also "auto-rolls back"
         a DBAPI connection upon checkin, if the ``reset_on_return``
         flag is set to its default value of ``'rollback'``.
         To intercept this
-        rollback, use the :meth:`.PoolEvents.reset` hook.
+        rollback, use the :meth:`_events.PoolEvents.reset` hook.
 
-        :param conn: :class:`.Connection` object
+        :param conn: :class:`_engine.Connection` object
 
         .. seealso::
 
-            :meth:`.PoolEvents.reset`
+            :meth:`_events.PoolEvents.reset`
 
         """
 
@@ -529,18 +553,18 @@ class ConnectionEvents(event.Events):
         """Intercept commit() events, as initiated by a
         :class:`.Transaction`.
 
-        Note that the :class:`.Pool` may also "auto-commit"
+        Note that the :class:`_pool.Pool` may also "auto-commit"
         a DBAPI connection upon checkin, if the ``reset_on_return``
         flag is set to the value ``'commit'``.  To intercept this
-        commit, use the :meth:`.PoolEvents.reset` hook.
+        commit, use the :meth:`_events.PoolEvents.reset` hook.
 
-        :param conn: :class:`.Connection` object
+        :param conn: :class:`_engine.Connection` object
         """
 
     def savepoint(self, conn, name):
         """Intercept savepoint() events.
 
-        :param conn: :class:`.Connection` object
+        :param conn: :class:`_engine.Connection` object
         :param name: specified name used for the savepoint.
 
         """
@@ -548,7 +572,7 @@ class ConnectionEvents(event.Events):
     def rollback_savepoint(self, conn, name, context):
         """Intercept rollback_savepoint() events.
 
-        :param conn: :class:`.Connection` object
+        :param conn: :class:`_engine.Connection` object
         :param name: specified name used for the savepoint.
         :param context: :class:`.ExecutionContext` in use.  May be ``None``.
 
@@ -557,7 +581,7 @@ class ConnectionEvents(event.Events):
     def release_savepoint(self, conn, name, context):
         """Intercept release_savepoint() events.
 
-        :param conn: :class:`.Connection` object
+        :param conn: :class:`_engine.Connection` object
         :param name: specified name used for the savepoint.
         :param context: :class:`.ExecutionContext` in use.  May be ``None``.
 
@@ -566,7 +590,7 @@ class ConnectionEvents(event.Events):
     def begin_twophase(self, conn, xid):
         """Intercept begin_twophase() events.
 
-        :param conn: :class:`.Connection` object
+        :param conn: :class:`_engine.Connection` object
         :param xid: two-phase XID identifier
 
         """
@@ -574,14 +598,14 @@ class ConnectionEvents(event.Events):
     def prepare_twophase(self, conn, xid):
         """Intercept prepare_twophase() events.
 
-        :param conn: :class:`.Connection` object
+        :param conn: :class:`_engine.Connection` object
         :param xid: two-phase XID identifier
         """
 
     def rollback_twophase(self, conn, xid, is_prepared):
         """Intercept rollback_twophase() events.
 
-        :param conn: :class:`.Connection` object
+        :param conn: :class:`_engine.Connection` object
         :param xid: two-phase XID identifier
         :param is_prepared: boolean, indicates if
          :meth:`.TwoPhaseTransaction.prepare` was called.
@@ -591,7 +615,7 @@ class ConnectionEvents(event.Events):
     def commit_twophase(self, conn, xid, is_prepared):
         """Intercept commit_twophase() events.
 
-        :param conn: :class:`.Connection` object
+        :param conn: :class:`_engine.Connection` object
         :param xid: two-phase XID identifier
         :param is_prepared: boolean, indicates if
          :meth:`.TwoPhaseTransaction.prepare` was called.