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

5 files changed, 23 insertions, 18 deletions

diff --git a/lib/sqlalchemy/sql/base.py b/lib/sqlalchemy/sql/base.py
index 1b9b20b32..d070027c8 100644
--- a/lib/sqlalchemy/sql/base.py
+++ b/lib/sqlalchemy/sql/base.py
@@ -600,7 +600,8 @@ class Executable(Generative):
         "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, *multiparams, **params):
diff --git a/lib/sqlalchemy/sql/dml.py b/lib/sqlalchemy/sql/dml.py
index bc800de42..4ed01375e 100644
--- a/lib/sqlalchemy/sql/dml.py
+++ b/lib/sqlalchemy/sql/dml.py
@@ -345,7 +345,8 @@ class UpdateBase(
 
         Upon execution, the values of the columns to be returned are made
         available via the result set and can be iterated using
-        :meth:`.ResultProxy.fetchone` and similar.   For DBAPIs which do not
+        :meth:`_engine.ResultProxy.fetchone` and similar.
+        For DBAPIs which do not
         natively support returning values (i.e. cx_oracle), SQLAlchemy will
         approximate this behavior at the result level so that a reasonable
         amount of behavioral neutrality is provided.
@@ -546,7 +547,8 @@ class ValuesBase(UpdateBase):
               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
-              :attr:`.ResultProxy.inserted_primary_key` accessor does not
+              :attr:`_engine.ResultProxy.inserted_primary_key`
+              accessor does not
               apply.
 
            .. versionchanged:: 1.0.0 A multiple-VALUES INSERT now supports
@@ -682,7 +684,8 @@ class ValuesBase(UpdateBase):
         added to any existing RETURNING clause, provided that
         :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,
+        :attr:`_engine.ResultProxy.returned_defaults` accessor as a dictionary
+        ,
         referring to values keyed to the :class:`_schema.Column`
         object as well as
         its ``.key``.
@@ -712,7 +715,7 @@ class ValuesBase(UpdateBase):
         3. It can be called against any backend.  Backends that don't support
            RETURNING will skip the usage of the feature, rather than raising
            an exception.  The return value of
-           :attr:`.ResultProxy.returned_defaults` will be ``None``
+           :attr:`_engine.ResultProxy.returned_defaults` will be ``None``
 
         :meth:`.ValuesBase.return_defaults` is used by the ORM to provide
         an efficient implementation for the ``eager_defaults`` feature of
@@ -729,7 +732,7 @@ class ValuesBase(UpdateBase):
 
             :meth:`.UpdateBase.returning`
 
-            :attr:`.ResultProxy.returned_defaults`
+            :attr:`_engine.ResultProxy.returned_defaults`
 
         """
         self._return_defaults = cols or True
@@ -919,7 +922,8 @@ class Insert(ValuesBase):
            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
-           :attr:`.ResultProxy.inserted_primary_key` accessor does not apply.
+           :attr:`_engine.ResultProxy.inserted_primary_key`
+           accessor does not apply.
 
         """
 
@@ -1060,7 +1064,7 @@ class Update(DMLWhereBase, ValuesBase):
           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`.
+          :meth:`_engine.ResultProxy.last_updated_params`.
 
         :param preserve_parameter_order: if True, the update statement is
           expected to receive parameters **only** via the
@@ -1185,7 +1189,7 @@ class Update(DMLWhereBase, ValuesBase):
         ``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`.
+        :meth:`_engine.ResultProxy.last_updated_params`.
 
         .. versionchanged:: 1.4 the :paramref:`_expression.update.inline`
            parameter
diff --git a/lib/sqlalchemy/sql/operators.py b/lib/sqlalchemy/sql/operators.py
index c0699c2ad..1bd63f285 100644
--- a/lib/sqlalchemy/sql/operators.py
+++ b/lib/sqlalchemy/sql/operators.py
@@ -610,7 +610,7 @@ class ColumnOperators(Operators):
         In the case that ``other`` is an empty sequence, the compiler
         produces an "empty not in" expression.   This defaults to the
         expression "1 = 1" to produce true in all cases.  The
-        :paramref:`.create_engine.empty_in_strategy` may be used to
+        :paramref:`_sa.create_engine.empty_in_strategy` may be used to
         alter this behavior.
 
         .. versionchanged:: 1.2  The :meth:`.ColumnOperators.in_` and
diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py
index bfe5d80ad..89ee7e28f 100644
--- a/lib/sqlalchemy/sql/selectable.py
+++ b/lib/sqlalchemy/sql/selectable.py
@@ -3471,7 +3471,7 @@ class Select(
         r"""Construct a new :class:`_expression.Select` using the 2.
         x style API.
 
-        .. versionadded:: 2.0 - the :func:`.future.select` construct is
+        .. versionadded:: 2.0 - the :func:`_future.select` construct is
            the same construct as the one returned by
            :func:`_expression.select`, except that the function only
            accepts the "columns clause" entities up front; the rest of the
diff --git a/lib/sqlalchemy/sql/sqltypes.py b/lib/sqlalchemy/sql/sqltypes.py
index ba8a25821..a65989e93 100644
--- a/lib/sqlalchemy/sql/sqltypes.py
+++ b/lib/sqlalchemy/sql/sqltypes.py
@@ -187,8 +187,8 @@ class String(Concatenable, TypeEngine):
           In the rare circumstance that the DBAPI does not support
           Python unicode under Python 2, SQLAlchemy will use its own
           encoder/decoder functionality on strings, referring to the
-          value of the :paramref:`.create_engine.encoding` parameter
-          parameter passed to :func:`.create_engine` as the encoding.
+          value of the :paramref:`_sa.create_engine.encoding` parameter
+          parameter passed to :func:`_sa.create_engine` as the encoding.
 
           For the extremely rare case that Python Unicode
           is to be encoded/decoded by SQLAlchemy on a backend
@@ -218,7 +218,7 @@ class String(Concatenable, TypeEngine):
 
           .. seealso::
 
-            :paramref:`.create_engine.convert_unicode` -
+            :paramref:`_sa.create_engine.convert_unicode` -
             :class:`_engine.Engine`-wide parameter
 
         :param unicode_error: Optional, a method to use to handle Unicode
@@ -378,7 +378,7 @@ class Unicode(String):
     directly, SQLAlchemy does the encoding and decoding
     outside of the DBAPI.   The encoding in this scenario
     is determined by the ``encoding`` flag passed to
-    :func:`.create_engine`.
+    :func:`_sa.create_engine`.
 
     When using the :class:`.Unicode` type, it is only appropriate
     to pass Python ``unicode`` objects, and not plain ``str``.
@@ -2089,9 +2089,9 @@ class JSON(Indexable, TypeEngine):
     psycopg2 dialect, psycopg2 may be using its own custom loader function.
 
     In order to affect the serializer / deserializer, they are currently
-    configurable at the :func:`.create_engine` level via the
-    :paramref:`.create_engine.json_serializer` and
-    :paramref:`.create_engine.json_deserializer` parameters.  For example,
+    configurable at the :func:`_sa.create_engine` level via the
+    :paramref:`_sa.create_engine.json_serializer` and
+    :paramref:`_sa.create_engine.json_deserializer` parameters.  For example,
     to turn off ``ensure_ascii``::
 
         engine = create_engine(