Correct ambiguous func / class links

:func:`.sql.expression.select`, :func:`.sql.expression.insert`
and :class:`.sql.expression.Insert` were hitting many ambiguous
symbol errors, due to future.select, as well as the PG/MySQL
variants of Insert.

Change-Id: Iac862bfc172a7f7f0cbba5353a83dc203bed376c

7 files changed, 95 insertions, 92 deletions

diff --git a/lib/sqlalchemy/sql/compiler.py b/lib/sqlalchemy/sql/compiler.py
index 14f4bda8c..000fc05fa 100644
--- a/lib/sqlalchemy/sql/compiler.py
+++ b/lib/sqlalchemy/sql/compiler.py
@@ -669,11 +669,12 @@ class SQLCompiler(Compiled):
     """Optional :class:`.CompileState` object that maintains additional
     state used by the compiler.
 
-    Major executable objects such as :class:`.Insert`, :class:`.Update`,
-    :class:`.Delete`, :class:`.Select` will generate this state when compiled
-    in order to calculate additional information about the object.   For the
-    top level object that is to be executed, the state can be stored here where
-    it can also have applicability towards result set processing.
+    Major executable objects such as :class:`~.sql.expression.Insert`,
+    :class:`.Update`, :class:`.Delete`, :class:`.Select` will generate this
+    state when compiled in order to calculate additional information about the
+    object.   For the top level object that is to be executed, the state can be
+    stored here where it can also have applicability towards result set
+    processing.
 
     .. versionadded:: 1.4
 
diff --git a/lib/sqlalchemy/sql/dml.py b/lib/sqlalchemy/sql/dml.py
index 2349bfd03..5c75e068f 100644
--- a/lib/sqlalchemy/sql/dml.py
+++ b/lib/sqlalchemy/sql/dml.py
@@ -5,7 +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:`.Insert`, :class:`.Update` and :class:`.Delete`.
+Provide :class:`~.sql.expression.Insert`, :class:`.Update` and
+:class:`.Delete`.
 
 """
 from sqlalchemy.types import NullType
@@ -430,7 +431,8 @@ class ValuesBase(UpdateBase):
         r"""specify a fixed VALUES clause for an INSERT statement, or the SET
         clause for an UPDATE.
 
-        Note that the :class:`.Insert` and :class:`.Update` constructs support
+        Note that the :class:`~.sql.expression.Insert` and :class:`.Update`
+        constructs support
         per-execution time formatting of the VALUES and/or SET clauses,
         based on the arguments passed to :meth:`.Connection.execute`.
         However, the :meth:`.ValuesBase.values` method can be used to "fix" a
@@ -456,28 +458,28 @@ 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:`.Insert` or an :class:`.Update`
-         construct.
+         based on whether this is an :class:`~.sql.expression.Insert` or an
+         :class:`.Update` construct.
 
-         For either an :class:`.Insert` or :class:`.Update` construct, a
-         single dictionary can be passed, which works the same as that of
-         the kwargs form::
+         For either an :class:`~.sql.expression.Insert` or :class:`.Update`
+         construct, a single dictionary can be passed, which works the same as
+         that of the kwargs form::
 
             users.insert().values({"name": "some name"})
 
             users.update().values({"name": "some new name"})
 
-         Also for either form but more typically for the :class:`.Insert`
-         construct, a tuple that contains an entry for every column in the
-         table is also accepted::
+         Also for either form but more typically for the
+         :class:`~.sql.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:`.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, MySQL,
-         but not necessarily others::
+         The :class:`~.sql.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,
+         MySQL, but not necessarily others::
 
             users.insert().values([
                                 {"name": "some name"},
@@ -714,7 +716,7 @@ class ValuesBase(UpdateBase):
 class Insert(ValuesBase):
     """Represent an INSERT construct.
 
-    The :class:`.Insert` object is created using the
+    The :class:`~.sql.expression.Insert` object is created using the
     :func:`~.expression.insert()` function.
 
     .. seealso::
@@ -771,7 +773,7 @@ class Insert(ValuesBase):
         return_defaults=False,
         **dialect_kw
     ):
-        """Construct an :class:`.Insert` object.
+        """Construct an :class:`~.sql.expression.Insert` object.
 
         Similar functionality is available via the
         :meth:`~.TableClause.insert` method on
@@ -782,9 +784,9 @@ class Insert(ValuesBase):
 
         :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:`.Insert` construct will also
-         dynamically render the VALUES clause at execution time based on
-         the parameters passed to :meth:`.Connection.execute`.
+         Can be omitted entirely; a :class:`~.sql.expression.Insert` construct
+         will also dynamically render the VALUES clause at execution time
+         based on the parameters passed to :meth:`.Connection.execute`.
 
         :param inline: if True, no attempt will be made to retrieve the
          SQL-generated default values to be provided within the statement;
@@ -829,7 +831,7 @@ class Insert(ValuesBase):
 
     @_generative
     def inline(self):
-        """Make this :class:`.Insert` construct "inline" .
+        """Make this :class:`~.sql.expression.Insert` construct "inline" .
 
         When set, no attempt will be made to retrieve the
         SQL-generated default values to be provided within the statement;
@@ -848,7 +850,7 @@ class Insert(ValuesBase):
 
     @_generative
     def from_select(self, names, select, include_defaults=True):
-        """Return a new :class:`.Insert` construct which represents
+        """Return a new :class:`~.sql.expression.Insert` construct which represents
         an ``INSERT...FROM SELECT`` statement.
 
         e.g.::
@@ -858,7 +860,8 @@ class Insert(ValuesBase):
 
         :param names: a sequence of string column names or :class:`.Column`
          objects representing the target columns.
-        :param select: a :func:`.select` construct, :class:`.FromClause`
+        :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
          columns returned from this FROM clause should correspond to the
@@ -1059,15 +1062,14 @@ class Update(DMLWhereBase, ValuesBase):
 
         * a literal data value (i.e. string, number, etc.)
         * a SQL expression, such as a related :class:`.Column`,
-          a scalar-returning :func:`.select` construct,
+          a scalar-returning :func:`~.sql.expression.select` construct,
           etc.
 
-        When combining :func:`.select` constructs within the values
-        clause of an :func:`.update` construct,
-        the subquery represented by the :func:`.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::
+        when combining :func:`~.sql.expression.select` constructs within the
+        values clause of an :func:`.update` construct, the subquery represented
+        by the :func:`~.sql.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::
 
             users.update().values(
                     name=select([addresses.c.email_address]).\
diff --git a/lib/sqlalchemy/sql/elements.py b/lib/sqlalchemy/sql/elements.py
index 5a10611ad..f644b16d9 100644
--- a/lib/sqlalchemy/sql/elements.py
+++ b/lib/sqlalchemy/sql/elements.py
@@ -398,15 +398,14 @@ class ClauseElement(
         # type: (Optional[Any]) -> ClauseElement
         """Apply a 'grouping' to this :class:`.ClauseElement`.
 
-        This method is overridden by subclasses to return a
-        "grouping" construct, i.e. parenthesis.   In particular
-        it's used by "binary" expressions to provide a grouping
-        around themselves when placed into a larger expression,
-        as well as by :func:`.select` constructs when placed into
-        the FROM clause of another :func:`.select`.  (Note that
-        subqueries should be normally created using the
-        :meth:`.Select.alias` method, as many platforms require
-        nested SELECT statements to be named).
+        This method is overridden by subclasses to return a "grouping"
+        construct, i.e. parenthesis.   In particular it's used by "binary"
+        expressions to provide a grouping around themselves when placed into a
+        larger expression, as well as by :func:`~.sql.expression.select`
+        constructs when placed into the FROM clause of another
+        :func:`~.sql.expression.select`.  (Note that subqueries should be
+        normally created using the :meth:`.Select.alias` method, as many
+        platforms require nested SELECT statements to be named).
 
         As expressions are composed together, the application of
         :meth:`self_group` is automatic - end-user code should never
@@ -1127,11 +1126,11 @@ class BindParameter(roles.InElementRole, ColumnElement):
         while the placeholder ``:name_1`` is rendered in the appropriate form
         for the target database, in this case the PostgreSQL database.
 
-        Similarly, :func:`.bindparam` is invoked automatically
-        when working with :term:`CRUD` statements as far as the "VALUES"
-        portion is concerned.   The :func:`.insert` construct produces an
-        ``INSERT`` expression which will, at statement execution time,
-        generate bound placeholders based on the arguments passed, as in::
+        Similarly, :func:`.bindparam` is invoked automatically when working
+        with :term:`CRUD` statements as far as the "VALUES" portion is
+        concerned.   The :func:`~.sql.expression.insert` construct produces an
+        ``INSERT`` expression which will, at statement execution time, generate
+        bound placeholders based on the arguments passed, as in::
 
             stmt = users_table.insert()
             result = connection.execute(stmt, name='Wendy')
@@ -1141,10 +1140,10 @@ class BindParameter(roles.InElementRole, ColumnElement):
             INSERT INTO "user" (name) VALUES (%(name)s)
             {'name': 'Wendy'}
 
-        The :class:`.Insert` construct, at compilation/execution time,
-        rendered a single :func:`.bindparam` mirroring the column
-        name ``name`` as a result of the single ``name`` parameter
-        we passed to the :meth:`.Connection.execute` method.
+        The :class:`~.sql.expression.Insert` construct, at
+        compilation/execution time, rendered a single :func:`.bindparam`
+        mirroring the column name ``name`` as a result of the single ``name``
+        parameter we passed to the :meth:`.Connection.execute` method.
 
         :param key:
           the key (e.g. the name) for this bind param.
@@ -4209,7 +4208,8 @@ class ColumnClause(
             SELECT id, name FROM user
 
         Once constructed, :func:`.column` may be used like any other SQL
-        expression element such as within :func:`.select` constructs::
+        expression element such as within :func:`~.sql.expression.select`
+        constructs::
 
             from sqlalchemy.sql import column
 
diff --git a/lib/sqlalchemy/sql/functions.py b/lib/sqlalchemy/sql/functions.py
index c1720b4c3..6004f6b51 100644
--- a/lib/sqlalchemy/sql/functions.py
+++ b/lib/sqlalchemy/sql/functions.py
@@ -128,7 +128,7 @@ class FunctionElement(Executable, ColumnElement, FromClause):
         an anonymously named column.
 
         An interim approach to providing named columns for a function
-        as a FROM clause is to build a :func:`.select` with the
+        as a FROM clause is to build a :func:`~.sql.expression.select` with the
         desired columns::
 
             from sqlalchemy.sql import column
diff --git a/lib/sqlalchemy/sql/operators.py b/lib/sqlalchemy/sql/operators.py
index 07a1eaaaf..ae56822c2 100644
--- a/lib/sqlalchemy/sql/operators.py
+++ b/lib/sqlalchemy/sql/operators.py
@@ -579,8 +579,8 @@ class ColumnOperators(Operators):
           .. versionadded:: 1.3 "expanding" bound parameters now support
              empty lists
 
-        * a :func:`.select` construct, which is usually a correlated
-          scalar select::
+        * a :func:`~.sql.expression.select` construct, which is usually a
+          correlated scalar select::
 
             stmt.where(
                 column.in_(
@@ -594,8 +594,8 @@ class ColumnOperators(Operators):
             WHERE COL IN (SELECT othertable.y
             FROM othertable WHERE othertable.x = table.x)
 
-        :param other: a list of literals, a :func:`.select` construct,
-         or a :func:`.bindparam` construct that includes the
+        :param other: a list of literals, a :func:`~.sql.expression.select`
+         construct, or a :func:`.bindparam` construct that includes the
          :paramref:`.bindparam.expanding` flag set to True.
 
         """
diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py
index a44b079c4..5ffdf23d8 100644
--- a/lib/sqlalchemy/sql/selectable.py
+++ b/lib/sqlalchemy/sql/selectable.py
@@ -75,7 +75,7 @@ def subquery(alias, *args, **kwargs):
     :param name: the alias name for the subquery
 
     :param \*args, \**kwargs:  all other arguments are passed through to the
-     :func:`.select` function.
+     :func:`~.sql.expression.select` function.
 
     """
     return Select(*args, **kwargs).subquery(alias)
@@ -316,7 +316,7 @@ class FromClause(HasMemoized, roles.AnonymizedFromClauseRole, Selectable):
     clause of a ``SELECT`` statement.
 
     The most common forms of :class:`.FromClause` are the
-    :class:`.Table` and the :func:`.select` constructs.  Key
+    :class:`.Table` and the :func:`~.sql.expression.select` constructs.  Key
     features common to all :class:`.FromClause` objects include:
 
     * a :attr:`.c` collection, which provides per-name access to a collection
@@ -1277,19 +1277,19 @@ class Alias(AliasedReturnsRows):
         with an alternate name assigned within SQL, typically using the ``AS``
         clause when generated, e.g. ``SELECT * FROM table AS aliasname``.
 
-        Similar functionality is available via the
-        :meth:`~.FromClause.alias` method
-        available on all :class:`.FromClause` subclasses.   In terms of a
-        SELECT object as generated from the :func:`.select` function, the
-        :meth:`.SelectBase.alias` method returns an :class:`.Alias` or
-        similar object which represents a named, parenthesized subquery.
+        Similar functionality is available via the :meth:`~.FromClause.alias`
+        method available on all :class:`.FromClause` subclasses.   In terms of
+        a SELECT object as generated from the :func:`~.sql.expression.select`
+        function, the :meth:`.SelectBase.alias` method returns an
+        :class:`.Alias` or similar object which represents a named,
+        parenthesized subquery.
 
         When an :class:`.Alias` is created from a :class:`.Table` object,
         this has the effect of the table being rendered
         as ``tablename AS aliasname`` in a SELECT statement.
 
-        For :func:`.select` objects, the effect is that of creating a named
-        subquery, i.e. ``(select ...) AS aliasname``.
+        For :func:`~.sql.expression.select` objects, the effect is that of
+        creating a named subquery, i.e. ``(select ...) AS aliasname``.
 
         The ``name`` parameter is optional, and provides the name
         to use in the rendered SQL.  If blank, an "anonymous" name
@@ -1764,7 +1764,8 @@ class Subquery(AliasedReturnsRows):
         "The :meth:`.Subquery.as_scalar` method, which was previously "
         "``Alias.as_scalar()`` prior to version 1.4, is deprecated and "
         "will be removed in a future release; Please use the "
-        ":meth:`.Select.scalar_subquery` method of the :func:`.select` "
+        ":meth:`.Select.scalar_subquery` method of the "
+        ":func:`~.sql.expression.select` "
         "construct before constructing a subquery object, or with the ORM "
         "use the :meth:`.Query.scalar_subquery` method.",
     )
@@ -1909,14 +1910,14 @@ class TableClause(Immutable, FromClause):
 
     @util.preload_module("sqlalchemy.sql.dml")
     def insert(self, values=None, inline=False, **kwargs):
-        """Generate an :func:`.insert` construct against this
+        """Generate an :func:`~.sql.expression.insert` construct against this
         :class:`.TableClause`.
 
         E.g.::
 
             table.insert().values(name='foo')
 
-        See :func:`.insert` for argument and usage information.
+        See :func:`~.sql.expression.insert` for argument and usage information.
 
         """
         return util.preloaded.sql_dml.Insert(
@@ -3320,7 +3321,7 @@ class Select(
         .. seealso::
 
             :ref:`coretutorial_selecting` - Core Tutorial description of
-            :func:`.select`.
+            :func:`~.sql.expression.select`.
 
         :param \*entities:
           Entities to SELECT from.  For Core usage, this is typically a series
@@ -3383,7 +3384,7 @@ class Select(
         .. seealso::
 
             :ref:`coretutorial_selecting` - Core Tutorial description of
-            :func:`.select`.
+            :func:`~.sql.expression.select`.
 
         :param columns:
           A list of :class:`.ColumnElement` or :class:`.FromClause`
@@ -3399,7 +3400,7 @@ class Select(
           .. note::
 
             The :paramref:`.select.columns` parameter is not available
-            in the method form of :func:`.select`, e.g.
+            in the method form of :func:`~.sql.expression.select`, e.g.
             :meth:`.FromClause.select`.
 
           .. seealso::
@@ -3807,11 +3808,11 @@ class Select(
 
     @_generative
     def with_only_columns(self, columns):
-        r"""Return a new :func:`.select` construct with its columns
+        r"""Return a new :func:`~.sql.expression.select` construct with its columns
         clause replaced with the given columns.
 
         This method is exactly equivalent to as if the original
-        :func:`.select` had been called with the given columns
+        :func:`~.sql.expression.select` had been called with the given columns
         clause.   I.e. a statement::
 
             s = select([table1.c.a, table1.c.b])
@@ -3846,15 +3847,14 @@ class Select(
             >>> print(s2)
             SELECT t2.b FROM t1 JOIN t2 ON t1.a=t2.a
 
-        Care should also be taken to use the correct
-        set of column objects passed to :meth:`.Select.with_only_columns`.
-        Since the method is essentially equivalent to calling the
-        :func:`.select` construct in the first place with the given
-        columns, the columns passed to :meth:`.Select.with_only_columns`
-        should usually be a subset of those which were passed
-        to the :func:`.select` construct, not those which are available
-        from the ``.c`` collection of that :func:`.select`.  That
-        is::
+        Care should also be taken to use the correct set of column objects
+        passed to :meth:`.Select.with_only_columns`. Since the method is
+        essentially equivalent to calling the :func:`~.sql.expression.select`
+        construct in the first place with the given columns, the columns passed
+        to :meth:`.Select.with_only_columns` should usually be a subset of
+        those which were passed to the :func:`~.sql.expression.select`
+        construct, not those which are available from the ``.c`` collection of
+        that :func:`~.sql.expression.select`.  That is::
 
             s = select([table1.c.a, table1.c.b]).select_from(table1)
             s = s.with_only_columns([table1.c.b])
@@ -3870,8 +3870,8 @@ class Select(
             FROM (SELECT t1.a AS a, t1.b AS b
             FROM t1), t1
 
-        Since the :func:`.select` construct is essentially being
-        asked to select both from ``table1`` as well as itself.
+        Since the :func:`~.sql.expression.select` construct is essentially
+        being asked to select both from ``table1`` as well as itself.
 
         """
         self._reset_memoizations()
@@ -3930,7 +3930,7 @@ class Select(
 
     @_generative
     def select_from(self, *froms):
-        r"""return a new :func:`.select` construct with the
+        r"""return a new :func:`~.sql.expression.select` construct with the
         given FROM expression(s)
         merged into its list of FROM objects.
 
@@ -4062,8 +4062,8 @@ class Select(
         must be applied first which provides for the necessary parenthesization
         required by SQL.
 
-        For a :func:`.select` construct, the collection here is exactly what
-        would be rendered inside the  "SELECT" statement, and the
+        For a :func:`~.sql.expression.select` construct, the collection here is
+        exactly what would be rendered inside the  "SELECT" statement, and the
         :class:`.ColumnElement` objects are  directly present as they were
         given, e.g.::
 
diff --git a/lib/sqlalchemy/sql/visitors.py b/lib/sqlalchemy/sql/visitors.py
index a049d9bb0..4c1aab62f 100644
--- a/lib/sqlalchemy/sql/visitors.py
+++ b/lib/sqlalchemy/sql/visitors.py
@@ -382,7 +382,7 @@ class InternalTraversal(util.with_metaclass(_InternalTraversalType, object)):
 
     dp_dml_multi_values = symbol("DML_MV")
     """visit the values() multi-valued list of dictionaries of an
-    :class:`.Insert` object.
+    :class:`~.sql.expression.Insert` object.
 
     """