Set up absolute references for create_engine and related

includes more replacements for create_engine(), Connection,
disambiguation of Result from future/baked

Change-Id: Icb60a79ee7a6c45ea9056c211ffd1be110da3b5e

8 files changed, 121 insertions, 95 deletions

diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index 014d433a7..8a340d9ce 100644
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -247,8 +247,8 @@ class Connection(Connectable):
           Set the transaction isolation level for the lifespan of this
           :class:`_engine.Connection` object.
           Valid values include those string
-          values accepted by the :paramref:`.create_engine.isolation_level`
-          parameter passed to :func:`.create_engine`.  These levels are
+          values accepted by the :paramref:`_sa.create_engine.isolation_level`
+          parameter passed to :func:`_sa.create_engine`.  These levels are
           semi-database specific; see individual dialect documentation for
           valid levels.
 
@@ -282,7 +282,7 @@ class Connection(Connectable):
 
           .. seealso::
 
-                :paramref:`.create_engine.isolation_level`
+                :paramref:`_sa.create_engine.isolation_level`
                 - set per :class:`_engine.Engine` isolation level
 
                 :meth:`_engine.Connection.get_isolation_level`
@@ -420,7 +420,7 @@ class Connection(Connectable):
             :attr:`_engine.Connection.default_isolation_level`
             - view default level
 
-            :paramref:`.create_engine.isolation_level`
+            :paramref:`_sa.create_engine.isolation_level`
             - set per :class:`_engine.Engine` isolation level
 
             :paramref:`.Connection.execution_options.isolation_level`
@@ -456,7 +456,7 @@ class Connection(Connectable):
             :meth:`_engine.Connection.get_isolation_level`
             - view current level
 
-            :paramref:`.create_engine.isolation_level`
+            :paramref:`_sa.create_engine.isolation_level`
             - set per :class:`_engine.Engine` isolation level
 
             :paramref:`.Connection.execution_options.isolation_level`
@@ -950,7 +950,7 @@ class Connection(Connectable):
 
     def execute(self, object_, *multiparams, **params):
         r"""Executes a SQL statement construct and returns a
-        :class:`.ResultProxy`.
+        :class:`_engine.ResultProxy`.
 
         :param object: The statement to be executed.  May be
          one of:
@@ -1219,7 +1219,7 @@ class Connection(Connectable):
 
     def exec_driver_sql(self, statement, parameters=None):
         r"""Executes a SQL statement construct and returns a
-        :class:`.ResultProxy`.
+        :class:`_engine.ResultProxy`.
 
         :param statement: The statement str to be executed.   Bound parameters
          must use the underlying DBAPI's paramstyle, such as "qmark",
@@ -1272,7 +1272,7 @@ class Connection(Connectable):
         self, dialect, constructor, statement, parameters, *args
     ):
         """Create an :class:`.ExecutionContext` and execute, returning
-        a :class:`.ResultProxy`."""
+        a :class:`_engine.ResultProxy`."""
 
         try:
             try:
@@ -2027,7 +2027,7 @@ class Engine(Connectable, log.Identified):
         default execution options that will be used for
         all connections.  The initial contents of this dictionary
         can be sent via the ``execution_options`` parameter
-        to :func:`.create_engine`.
+        to :func:`_sa.create_engine`.
 
         .. seealso::
 
@@ -2224,10 +2224,10 @@ class Engine(Connectable, log.Identified):
         that the :class:`_engine.Connection` will be closed when the operation
         is complete.   When set to ``True``, it indicates the
         :class:`_engine.Connection` is in "single use" mode, where the
-        :class:`.ResultProxy` returned by the first call to
+        :class:`_engine.ResultProxy` returned by the first call to
         :meth:`_engine.Connection.execute` will close the
         :class:`_engine.Connection` when
-        that :class:`.ResultProxy` has exhausted all result rows.
+        that :class:`_engine.ResultProxy` has exhausted all result rows.
 
         .. seealso::
 
@@ -2335,15 +2335,17 @@ class Engine(Connectable, log.Identified):
         ":class:`.Session`.",
     )
     def execute(self, statement, *multiparams, **params):
-        """Executes the given construct and returns a :class:`.ResultProxy`.
+        """Executes the given construct and returns a
+        :class:`_engine.ResultProxy`.
 
         The arguments are the same as those used by
         :meth:`_engine.Connection.execute`.
 
         Here, a :class:`_engine.Connection` is acquired using the
         :meth:`_engine.Engine.connect` method, and the statement executed
-        with that connection. The returned :class:`.ResultProxy` is flagged
-        such that when the :class:`.ResultProxy` is exhausted and its
+        with that connection. The returned :class:`_engine.ResultProxy`
+        is flagged
+        such that when the :class:`_engine.ResultProxy` is exhausted and its
         underlying cursor is closed, the :class:`_engine.Connection`
         created here
         will also be closed, which allows its associated DBAPI connection
@@ -2359,7 +2361,8 @@ class Engine(Connectable, log.Identified):
         "by the :meth:`_engine.Connection.execute` method of "
         ":class:`_engine.Connection`, "
         "or in the ORM by the :meth:`.Session.execute` method of "
-        ":class:`.Session`; the :meth:`.Result.scalar` method can then be "
+        ":class:`.Session`; the :meth:`_future.Result.scalar` "
+        "method can then be "
         "used to return a scalar result.",
     )
     def scalar(self, statement, *multiparams, **params):
diff --git a/lib/sqlalchemy/engine/create.py b/lib/sqlalchemy/engine/create.py
index 3c1345c63..e5b8a87d3 100644
--- a/lib/sqlalchemy/engine/create.py
+++ b/lib/sqlalchemy/engine/create.py
@@ -19,7 +19,7 @@ from ..sql import compiler
 @util.deprecated_params(
     strategy=(
         "1.4",
-        "The :paramref:`.create_engine.strategy` keyword is deprecated, "
+        "The :paramref:`_sa.create_engine.strategy` keyword is deprecated, "
         "and the only argument accepted is 'mock'; please use "
         ":func:`.create_mock_engine` going forward.  For general "
         "customization of create_engine which may have been accomplished "
@@ -27,7 +27,7 @@ from ..sql import compiler
     ),
     empty_in_strategy=(
         "1.4",
-        "The :paramref:`.create_engine.empty_in_strategy` keyword is "
+        "The :paramref:`_sa.create_engine.empty_in_strategy` keyword is "
         "deprecated, and no longer has any effect.  All IN expressions "
         "are now rendered using "
         'the "expanding parameter" strategy which renders a set of bound'
@@ -36,7 +36,7 @@ from ..sql import compiler
     ),
     case_sensitive=(
         "1.4",
-        "The :paramref:`.create_engine.case_sensitive` parameter "
+        "The :paramref:`_sa.create_engine.case_sensitive` parameter "
         "is deprecated and will be removed in a future release. "
         "Applications should work with result column names in a case "
         "sensitive fashion.",
@@ -73,7 +73,7 @@ def create_engine(url, **kwargs):
     as well as the
     :class:`_pool.Pool`.  Specific dialects also accept keyword arguments that
     are unique to that dialect.   Here, we describe the parameters
-    that are common to most :func:`.create_engine()` usage.
+    that are common to most :func:`_sa.create_engine()` usage.
 
     Once established, the newly resulting :class:`_engine.Engine` will
     request a connection from the underlying :class:`_pool.Pool` once
@@ -81,7 +81,7 @@ def create_engine(url, **kwargs):
     such as :meth:`_engine.Engine.execute` is invoked.   The
     :class:`_pool.Pool` in turn
     will establish the first actual DBAPI connection when this request
-    is received.   The :func:`.create_engine` call itself does **not**
+    is received.   The :func:`_sa.create_engine` call itself does **not**
     establish any actual DBAPI connections directly.
 
     .. seealso::
@@ -111,7 +111,7 @@ def create_engine(url, **kwargs):
 
         .. deprecated:: 1.3
 
-            The :paramref:`.create_engine.convert_unicode` parameter
+            The :paramref:`_sa.create_engine.convert_unicode` parameter
             is deprecated and will be removed in a future release.
             All modern DBAPIs now support Python Unicode directly and this
             parameter is unnecessary.
@@ -277,14 +277,15 @@ def create_engine(url, **kwargs):
         characters. If less than 6, labels are generated as
         "_(counter)". If ``None``, the value of
         ``dialect.max_identifier_length``, which may be affected via the
-        :paramref:`.create_engine.max_identifier_length` parameter,
-        is used instead.   The value of :paramref:`.create_engine.label_length`
+        :paramref:`_sa.create_engine.max_identifier_length` parameter,
+        is used instead.   The value of
+        :paramref:`_sa.create_engine.label_length`
         may not be larger than that of
-        :paramref:`.create_engine.max_identfier_length`.
+        :paramref:`_sa.create_engine.max_identfier_length`.
 
         .. seealso::
 
-            :paramref:`.create_engine.max_identifier_length`
+            :paramref:`_sa.create_engine.max_identifier_length`
 
     :param listeners: A list of one or more
         :class:`~sqlalchemy.interfaces.PoolListener` objects which will
@@ -308,7 +309,7 @@ def create_engine(url, **kwargs):
 
         .. seealso::
 
-            :paramref:`.create_engine.label_length`
+            :paramref:`_sa.create_engine.label_length`
 
     :param max_overflow=10: the number of connections to allow in
         connection pool "overflow", that is connections that can be
@@ -602,7 +603,7 @@ def engine_from_config(configuration, prefix="sqlalchemy.", **kwargs):
     ``sqlalchemy.url``, ``sqlalchemy.echo``, etc.  The 'prefix' argument
     indicates the prefix to be searched for.  Each matching key (after the
     prefix is stripped) is treated as though it were the corresponding keyword
-    argument to a :func:`.create_engine` call.
+    argument to a :func:`_sa.create_engine` call.
 
     The only required key is (assuming the default prefix) ``sqlalchemy.url``,
     which provides the :ref:`database URL <database_urls>`.
@@ -614,7 +615,7 @@ def engine_from_config(configuration, prefix="sqlalchemy.", **kwargs):
     :param configuration: A dictionary (typically produced from a config file,
         but this is not a requirement).  Items whose keys start with the value
         of 'prefix' will have that prefix stripped, and will then be passed to
-        :func:`.create_engine`.
+        :func:`_sa.create_engine`.
 
     :param prefix: Prefix to match and then strip from keys
         in 'configuration'.
diff --git a/lib/sqlalchemy/engine/default.py b/lib/sqlalchemy/engine/default.py
index 5b8cb635c..5ec13d103 100644
--- a/lib/sqlalchemy/engine/default.py
+++ b/lib/sqlalchemy/engine/default.py
@@ -190,14 +190,14 @@ class DefaultDialect(interfaces.Dialect):
     @util.deprecated_params(
         convert_unicode=(
             "1.3",
-            "The :paramref:`.create_engine.convert_unicode` parameter "
+            "The :paramref:`_sa.create_engine.convert_unicode` parameter "
             "and corresponding dialect-level parameters are deprecated, "
             "and will be removed in a future release.  Modern DBAPIs support "
             "Python Unicode natively and this parameter is unnecessary.",
         ),
         empty_in_strategy=(
             "1.4",
-            "The :paramref:`.create_engine.empty_in_strategy` keyword is "
+            "The :paramref:`_sa.create_engine.empty_in_strategy` keyword is "
             "deprecated, and no longer has any effect.  All IN expressions "
             "are now rendered using "
             'the "expanding parameter" strategy which renders a set of bound'
@@ -206,7 +206,7 @@ class DefaultDialect(interfaces.Dialect):
         ),
         case_sensitive=(
             "1.4",
-            "The :paramref:`.create_engine.case_sensitive` parameter "
+            "The :paramref:`_sa.create_engine.case_sensitive` parameter "
             "is deprecated and will be removed in a future release. "
             "Applications should work with result column names in a case "
             "sensitive fashion.",
diff --git a/lib/sqlalchemy/engine/events.py b/lib/sqlalchemy/engine/events.py
index 46459cf73..65b73002c 100644
--- a/lib/sqlalchemy/engine/events.py
+++ b/lib/sqlalchemy/engine/events.py
@@ -61,7 +61,7 @@ class ConnectionEvents(event.Events):
             statement = statement + " -- some comment"
             return statement, parameters
 
-    .. note:: :class:`.ConnectionEvents` can be established on any
+    .. note:: :class:`_events.ConnectionEvents` can be established on any
        combination of :class:`_engine.Engine`, :class:`_engine.Connection`,
        as well
        as instances of each of those classes.  Events across all
@@ -183,7 +183,8 @@ class ConnectionEvents(event.Events):
          :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.
+        :param result: :class:`_engine.ResultProxy` generated by the execution
+                      .
 
         """
 
@@ -208,7 +209,7 @@ class ConnectionEvents(event.Events):
                 # do something with statement, parameters
                 return statement, parameters
 
-        See the example at :class:`.ConnectionEvents`.
+        See the example at :class:`_events.ConnectionEvents`.
 
         :param conn: :class:`_engine.Connection` object
         :param cursor: DBAPI cursor object
@@ -237,7 +238,7 @@ class ConnectionEvents(event.Events):
         :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`.
+         as they will be needed by the :class:`_engine.ResultProxy`.
         :param statement: string SQL statement, as passed to the DBAPI
         :param parameters: Dictionary, tuple, or list of parameters being
          passed to the ``execute()`` or ``executemany()`` method of the
@@ -317,7 +318,8 @@ class ConnectionEvents(event.Events):
                     "failed" in str(context.original_exception):
                     raise MySpecialException("failed operation")
 
-        .. warning::  Because the :meth:`.ConnectionEvents.handle_error`
+        .. warning::  Because the
+           :meth:`_events.ConnectionEvents.handle_error`
            event specifically provides for exceptions to be re-thrown as
            the ultimate exception raised by the failed statement,
            **stack traces will be misleading** if the user-defined event
@@ -358,7 +360,7 @@ class ConnectionEvents(event.Events):
          class for details on all available members.
 
         .. versionadded:: 0.9.7 Added the
-            :meth:`.ConnectionEvents.handle_error` hook.
+            :meth:`_events.ConnectionEvents.handle_error` hook.
 
         .. versionchanged:: 1.1 The :meth:`.handle_error` event will now
            receive all exceptions that inherit from ``BaseException``,
@@ -429,7 +431,7 @@ class ConnectionEvents(event.Events):
         .. seealso::
 
             :ref:`pool_disconnects_pessimistic` - illustrates how to use
-            :meth:`.ConnectionEvents.engine_connect`
+            :meth:`_events.ConnectionEvents.engine_connect`
             to transparently ensure pooled connections are connected to the
             database.
 
@@ -437,7 +439,8 @@ class ConnectionEvents(event.Events):
             the lower-level pool checkout event
             for an individual DBAPI connection
 
-            :meth:`.ConnectionEvents.set_connection_execution_options` - a copy
+            :meth:`_events.ConnectionEvents.set_connection_execution_options`
+            - a copy
             of a :class:`_engine.Connection` is also made when the
             :meth:`_engine.Connection.execution_options` method is called.
 
@@ -456,7 +459,7 @@ class ConnectionEvents(event.Events):
         :class:`_engine.Connection`
         is produced which is inheriting execution options from its parent
         :class:`_engine.Engine`; to intercept this condition, use the
-        :meth:`.ConnectionEvents.engine_connect` event.
+        :meth:`_events.ConnectionEvents.engine_connect` event.
 
         :param conn: The newly copied :class:`_engine.Connection` object
 
@@ -467,7 +470,8 @@ class ConnectionEvents(event.Events):
 
         .. seealso::
 
-            :meth:`.ConnectionEvents.set_engine_execution_options` - event
+            :meth:`_events.ConnectionEvents.set_engine_execution_options`
+            - event
             which is called when :meth:`_engine.Engine.execution_options`
             is called.
 
@@ -483,7 +487,8 @@ class ConnectionEvents(event.Events):
         That new
         :class:`_engine.Engine` is passed here.
         A particular application of this
-        method is to add a :meth:`.ConnectionEvents.engine_connect` event
+        method is to add a :meth:`_events.ConnectionEvents.engine_connect`
+        event
         handler to the given :class:`_engine.Engine`
         which will perform some per-
         :class:`_engine.Connection` task specific to these execution options.
@@ -497,7 +502,8 @@ class ConnectionEvents(event.Events):
 
         .. seealso::
 
-            :meth:`.ConnectionEvents.set_connection_execution_options` - event
+            :meth:`_events.ConnectionEvents.set_connection_execution_options`
+            - event
             which is called when :meth:`_engine.Connection.execution_options`
             is
             called.
@@ -636,17 +642,17 @@ class DialectEvents(event.Events):
         These hooks are not for general use and are only for those situations
         where intricate re-statement of DBAPI mechanics must be injected onto
         an existing dialect.  For general-use statement-interception events,
-        please use the :class:`.ConnectionEvents` interface.
+        please use the :class:`_events.ConnectionEvents` interface.
 
     .. seealso::
 
-        :meth:`.ConnectionEvents.before_cursor_execute`
+        :meth:`_events.ConnectionEvents.before_cursor_execute`
 
-        :meth:`.ConnectionEvents.before_execute`
+        :meth:`_events.ConnectionEvents.before_execute`
 
-        :meth:`.ConnectionEvents.after_cursor_execute`
+        :meth:`_events.ConnectionEvents.after_cursor_execute`
 
-        :meth:`.ConnectionEvents.after_execute`
+        :meth:`_events.ConnectionEvents.after_execute`
 
 
     .. versionadded:: 0.9.4
diff --git a/lib/sqlalchemy/engine/interfaces.py b/lib/sqlalchemy/engine/interfaces.py
index 224d4f693..e07877475 100644
--- a/lib/sqlalchemy/engine/interfaces.py
+++ b/lib/sqlalchemy/engine/interfaces.py
@@ -780,7 +780,7 @@ class Dialect(object):
             :paramref:`.Connection.execution_options.isolation_level` -
             set per :class:`_engine.Connection` isolation level
 
-            :paramref:`.create_engine.isolation_level` -
+            :paramref:`_sa.create_engine.isolation_level` -
             set per :class:`_engine.Engine` isolation level
 
         """
@@ -807,7 +807,7 @@ class Dialect(object):
             :paramref:`.Connection.execution_options.isolation_level` -
             set per :class:`_engine.Connection` isolation level
 
-            :paramref:`.create_engine.isolation_level` -
+            :paramref:`_sa.create_engine.isolation_level` -
             set per :class:`_engine.Engine` isolation level
 
         """
@@ -839,7 +839,7 @@ class Dialect(object):
             :paramref:`.Connection.execution_options.isolation_level` -
             set per :class:`_engine.Connection` isolation level
 
-            :paramref:`.create_engine.isolation_level` -
+            :paramref:`_sa.create_engine.isolation_level` -
             set per :class:`_engine.Engine` isolation level
 
 
@@ -945,14 +945,14 @@ class CreateEnginePlugin(object):
           "mysql+pymysql://scott:tiger@localhost/test?plugin=myplugin")
 
     Alternatively, the :paramref:`.create_engine.plugins" argument may be
-    passed as a list to :func:`.create_engine`::
+    passed as a list to :func:`_sa.create_engine`::
 
         engine = create_engine(
           "mysql+pymysql://scott:tiger@localhost/test",
           plugins=["myplugin"])
 
     .. versionadded:: 1.2.3  plugin names can also be specified
-       to :func:`.create_engine` as a list
+       to :func:`_sa.create_engine` as a list
 
     The ``plugin`` argument supports multiple instances, so that a URL
     may specify multiple plugins; they are loaded in the order stated
@@ -963,7 +963,7 @@ class CreateEnginePlugin(object):
           "test?plugin=plugin_one&plugin=plugin_twp&plugin=plugin_three")
 
     A plugin can receive additional arguments from the URL string as
-    well as from the keyword arguments passed to :func:`.create_engine`.
+    well as from the keyword arguments passed to :func:`_sa.create_engine`.
     The :class:`.URL` object and the keyword dictionary are passed to the
     constructor so that these arguments can be extracted from the url's
     :attr:`.URL.query` collection as well as from the dictionary::
@@ -1004,7 +1004,8 @@ class CreateEnginePlugin(object):
         """Construct a new :class:`.CreateEnginePlugin`.
 
         The plugin object is instantiated individually for each call
-        to :func:`.create_engine`.  A single :class:`_engine.Engine` will be
+        to :func:`_sa.create_engine`.  A single :class:`_engine.
+        Engine` will be
         passed to the :meth:`.CreateEnginePlugin.engine_created` method
         corresponding to this URL.
 
@@ -1249,7 +1250,7 @@ class ExecutionContext(object):
         """Return the DBAPI ``cursor.rowcount`` value, or in some
         cases an interpreted value.
 
-        See :attr:`.ResultProxy.rowcount` for details on this.
+        See :attr:`_engine.ResultProxy.rowcount` for details on this.
 
         """
 
@@ -1296,7 +1297,8 @@ class Connectable(object):
     """
 
     def execute(self, object_, *multiparams, **params):
-        """Executes the given construct and returns a :class:`.ResultProxy`."""
+        """Executes the given construct and returns a """
+        """:class:`_engine.ResultProxy`."""
         raise NotImplementedError()
 
     def scalar(self, object_, *multiparams, **params):
@@ -1317,7 +1319,8 @@ class ExceptionContext(object):
     """Encapsulate information about an error condition in progress.
 
     This object exists solely to be passed to the
-    :meth:`.ConnectionEvents.handle_error` event, supporting an interface that
+    :meth:`_events.ConnectionEvents.handle_error` event,
+    supporting an interface that
     can be extended without backwards-incompatibility.
 
     .. versionadded:: 0.9.7
@@ -1409,7 +1412,7 @@ class ExceptionContext(object):
     :attr:`.ExceptionContext.parameters` members may represent a
     different value than that of the :class:`.ExecutionContext`,
     potentially in the case where a
-    :meth:`.ConnectionEvents.before_cursor_execute` event or similar
+    :meth:`_events.ConnectionEvents.before_cursor_execute` event or similar
     modified the statement/parameters to be sent.
 
     May be None.
@@ -1421,7 +1424,7 @@ class ExceptionContext(object):
     condition.
 
     This flag will always be True or False within the scope of the
-    :meth:`.ConnectionEvents.handle_error` handler.
+    :meth:`_events.ConnectionEvents.handle_error` handler.
 
     SQLAlchemy will defer to this flag in order to determine whether or not
     the connection should be invalidated subsequently.    That is, by
@@ -1436,7 +1439,8 @@ class ExceptionContext(object):
     when a "disconnect" condition is in effect.
 
     Setting this flag to False within the scope of the
-    :meth:`.ConnectionEvents.handle_error` event will have the effect such
+    :meth:`_events.ConnectionEvents.handle_error`
+    event will have the effect such
     that the full collection of connections in the pool will not be
     invalidated during a disconnect; only the current connection that is the
     subject of the error will actually be invalidated.
diff --git a/lib/sqlalchemy/engine/mock.py b/lib/sqlalchemy/engine/mock.py
index 19a3b8e6c..d6a542e19 100644
--- a/lib/sqlalchemy/engine/mock.py
+++ b/lib/sqlalchemy/engine/mock.py
@@ -92,7 +92,8 @@ def create_mock_engine(url, executor, **kw):
      string using :meth:`.DDLElement.compile`.
 
     .. versionadded:: 1.4 - the :func:`.create_mock_engine` function replaces
-       the previous "mock" engine strategy used with :func:`.create_engine`.
+       the previous "mock" engine strategy used with :func:`_sa.create_engine`
+       .
 
     .. seealso::
 
diff --git a/lib/sqlalchemy/engine/result.py b/lib/sqlalchemy/engine/result.py
index 6944e0c67..e1e5e9016 100644
--- a/lib/sqlalchemy/engine/result.py
+++ b/lib/sqlalchemy/engine/result.py
@@ -1112,8 +1112,8 @@ class BaseResult(object):
 
 
     :class:`.BaseResult` is the base class for the 1.x style
-    :class:`.ResultProxy` class as well as the 2.x style
-    :class:`.future.Result` class.
+    :class:`_engine.ResultProxy` class as well as the 2.x style
+    :class:`_future.Result` class.
 
     """
 
@@ -1201,7 +1201,7 @@ class BaseResult(object):
             return has_key(key)
 
     def _soft_close(self, hard=False):
-        """Soft close this :class:`.ResultProxy`.
+        """Soft close this :class:`_engine.ResultProxy`.
 
         This releases all DBAPI cursor resources, but leaves the
         ResultProxy "open" from a semantic perspective, meaning the
@@ -1219,7 +1219,7 @@ class BaseResult(object):
 
         .. seealso::
 
-            :meth:`.ResultProxy.close`
+            :meth:`_engine.ResultProxy.close`
 
 
         """
@@ -1404,7 +1404,7 @@ class BaseResult(object):
     def supports_sane_rowcount(self):
         """Return ``supports_sane_rowcount`` from the dialect.
 
-        See :attr:`.ResultProxy.rowcount` for background.
+        See :attr:`_engine.ResultProxy.rowcount` for background.
 
         """
 
@@ -1413,7 +1413,7 @@ class BaseResult(object):
     def supports_sane_multi_rowcount(self):
         """Return ``supports_sane_multi_rowcount`` from the dialect.
 
-        See :attr:`.ResultProxy.rowcount` for background.
+        See :attr:`_engine.ResultProxy.rowcount` for background.
 
         """
 
@@ -1428,7 +1428,7 @@ class BaseResult(object):
 
         .. note::
 
-           Notes regarding :attr:`.ResultProxy.rowcount`:
+           Notes regarding :attr:`_engine.ResultProxy.rowcount`:
 
 
            * This attribute returns the number of rows *matched*,
@@ -1441,18 +1441,20 @@ class BaseResult(object):
              rowcount is configured by default to return the match
              count in all cases.
 
-           * :attr:`.ResultProxy.rowcount` is *only* useful in conjunction
+           * :attr:`_engine.ResultProxy.rowcount`
+             is *only* useful in conjunction
              with an UPDATE or DELETE statement.  Contrary to what the Python
              DBAPI says, it does *not* return the
              number of rows available from the results of a SELECT statement
              as DBAPIs cannot support this functionality when rows are
              unbuffered.
 
-           * :attr:`.ResultProxy.rowcount` may not be fully implemented by
+           * :attr:`_engine.ResultProxy.rowcount`
+             may not be fully implemented by
              all dialects.  In particular, most DBAPIs do not support an
              aggregate rowcount result from an executemany call.
-             The :meth:`.ResultProxy.supports_sane_rowcount` and
-             :meth:`.ResultProxy.supports_sane_multi_rowcount` methods
+             The :meth:`_engine.ResultProxy.supports_sane_rowcount` and
+             :meth:`_engine.ResultProxy.supports_sane_multi_rowcount` methods
              will report from the dialect if each usage is known to be
              supported.
 
@@ -1492,19 +1494,19 @@ class BaseResult(object):
 
     @property
     def returns_rows(self):
-        """True if this :class:`.ResultProxy` returns rows.
+        """True if this :class:`_engine.ResultProxy` returns rows.
 
         I.e. if it is legal to call the methods
-        :meth:`~.ResultProxy.fetchone`,
-        :meth:`~.ResultProxy.fetchmany`
-        :meth:`~.ResultProxy.fetchall`.
+        :meth:`_engine.ResultProxy.fetchone`,
+        :meth:`_engine.ResultProxy.fetchmany`
+        :meth:`_engine.ResultProxy.fetchall`.
 
         """
         return self._metadata is not None
 
     @property
     def is_insert(self):
-        """True if this :class:`.ResultProxy` is the result
+        """True if this :class:`_engine.ResultProxy` is the result
         of a executing an expression language compiled
         :func:`_expression.insert` construct.
 
@@ -1524,7 +1526,8 @@ class ResultProxy(BaseResult):
     additional API features and behaviors on top of the raw data returned
     by the DBAPI.
 
-    Within the scope of the 1.x series of SQLAlchemy, the :class:`.ResultProxy`
+    Within the scope of the 1.x series of SQLAlchemy, the
+    :class:`_engine.ResultProxy`
     will in fact return instances of the :class:`.LegacyRow` class, which
     maintains Python mapping (i.e. dictionary) like behaviors upon the object
     itself.  Going forward, the :attr:`.Row._mapping` attribute should be used
@@ -1533,7 +1536,7 @@ class ResultProxy(BaseResult):
     .. seealso::
 
         :ref:`coretutorial_selecting` - introductory material for accessing
-        :class:`.ResultProxy` and :class:`.Row` objects.
+        :class:`_engine.ResultProxy` and :class:`.Row` objects.
 
     """
 
@@ -1553,14 +1556,17 @@ class ResultProxy(BaseResult):
                 yield row
 
     def close(self):
-        """Close this :class:`.ResultProxy`.
+        """Close this :class:`_engine.ResultProxy`.
 
         This closes out the underlying DBAPI cursor corresponding
         to the statement execution, if one is still present.  Note that the
-        DBAPI cursor is automatically released when the :class:`.ResultProxy`
-        exhausts all available rows.  :meth:`.ResultProxy.close` is generally
+        DBAPI cursor is automatically released when the
+        :class:`_engine.ResultProxy`
+        exhausts all available rows.  :meth:`_engine.ResultProxy.close`
+        is generally
         an optional method except in the case when discarding a
-        :class:`.ResultProxy` that still has additional rows pending for fetch.
+        :class:`_engine.ResultProxy`
+        that still has additional rows pending for fetch.
 
         In the case of a result that is the product of
         :ref:`connectionless execution <dbengine_implicit>`,
@@ -1570,7 +1576,8 @@ class ResultProxy(BaseResult):
 
         .. deprecated:: 2.0 "connectionless" execution is deprecated and will
            be removed in version 2.0.   Version 2.0 will feature the
-           :class:`.future.Result` object that will no longer affect the status
+           :class:`_future.Result`
+           object that will no longer affect the status
            of the originating connection in any case.
 
         After this method is called, it is no longer valid to call upon
@@ -1636,8 +1643,8 @@ class ResultProxy(BaseResult):
         cursor resource is released, and the object may be safely
         discarded.
 
-        Subsequent calls to :meth:`.ResultProxy.fetchall` will return
-        an empty list.   After the :meth:`.ResultProxy.close` method is
+        Subsequent calls to :meth:`_engine.ResultProxy.fetchall` will return
+        an empty list.   After the :meth:`_engine.ResultProxy.close` method is
         called, the method will raise :class:`.ResourceClosedError`.
 
         :return: a list of :class:`.Row` objects
@@ -1661,9 +1668,10 @@ class ResultProxy(BaseResult):
         cursor resource is released, and the object may be safely
         discarded.
 
-        Calls to :meth:`.ResultProxy.fetchmany` after all rows have been
+        Calls to :meth:`_engine.ResultProxy.fetchmany`
+        after all rows have been
         exhausted will return
-        an empty list.   After the :meth:`.ResultProxy.close` method is
+        an empty list.   After the :meth:`_engine.ResultProxy.close` method is
         called, the method will raise :class:`.ResourceClosedError`.
 
         :return: a list of :class:`.Row` objects
@@ -1690,9 +1698,9 @@ class ResultProxy(BaseResult):
         cursor resource is released, and the object may be safely
         discarded.
 
-        Calls to :meth:`.ResultProxy.fetchone` after all rows have
+        Calls to :meth:`_engine.ResultProxy.fetchone` after all rows have
         been exhausted will return ``None``.
-        After the :meth:`.ResultProxy.close` method is
+        After the :meth:`_engine.ResultProxy.close` method is
         called, the method will raise :class:`.ResourceClosedError`.
 
         :return: a :class:`.Row` object, or None if no rows remain
@@ -1714,7 +1722,8 @@ class ResultProxy(BaseResult):
         """Fetch the first row and then close the result set unconditionally.
 
         After calling this method, the object is fully closed,
-        e.g. the :meth:`.ResultProxy.close` method will have been called.
+        e.g. the :meth:`_engine.ResultProxy.close`
+        method will have been called.
 
         :return: a :class:`.Row` object, or None if no rows remain
 
@@ -1738,7 +1747,8 @@ class ResultProxy(BaseResult):
         """Fetch the first column of the first row, and close the result set.
 
         After calling this method, the object is fully closed,
-        e.g. the :meth:`.ResultProxy.close` method will have been called.
+        e.g. the :meth:`_engine.ResultProxy.close`
+        method will have been called.
 
         :return: a Python scalar value , or None if no rows remain
 
diff --git a/lib/sqlalchemy/engine/row.py b/lib/sqlalchemy/engine/row.py
index b58b350e2..68e32057d 100644
--- a/lib/sqlalchemy/engine/row.py
+++ b/lib/sqlalchemy/engine/row.py
@@ -127,7 +127,7 @@ class Row(BaseRow, collections_abc.Sequence):
 
     The :class:`.Row` object represents a row of a database result.  It is
     typically associated in the 1.x series of SQLAlchemy with the
-    :class:`.ResultProxy` object, however is also used by the ORM for
+    :class:`_engine.ResultProxy` object, however is also used by the ORM for
     tuple-like results as of SQLAlchemy 1.4.
 
     The :class:`.Row` object seeks to act as much like a Python named
@@ -150,7 +150,8 @@ class Row(BaseRow, collections_abc.Sequence):
         and now acts mostly like a named tuple.  Mapping-like functionality is
         moved to the :attr:`.Row._mapping` attribute, but will remain available
         in SQLAlchemy 1.x series via the :class:`.LegacyRow` class that is used
-        by :class:`.ResultProxy`.   See :ref:`change_4710_core` for background
+        by :class:`_engine.ResultProxy`.
+        See :ref:`change_4710_core` for background
         on this change.
 
     """