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

13 files changed, 124 insertions, 120 deletions

diff --git a/lib/sqlalchemy/dialects/mssql/base.py b/lib/sqlalchemy/dialects/mssql/base.py
index 924c0f457..526e6e8ab 100644
--- a/lib/sqlalchemy/dialects/mssql/base.py
+++ b/lib/sqlalchemy/dialects/mssql/base.py
@@ -85,7 +85,7 @@ is set to ``False`` on any integer primary key column::
     marked with IDENTITY will be rejected by SQL Server.   In order for the
     value to be accepted, a session-level option "SET IDENTITY_INSERT" must be
     enabled.   The SQLAlchemy SQL Server dialect will perform this operation
-    automatically when using a core :class:`.Insert` construct; if the
+    automatically when using a core :class:`~.sql.expression.Insert` construct; if the
     execution specifies a value for the IDENTITY column, the "IDENTITY_INSERT"
     option will be enabled for the span of that statement's invocation.However,
     this scenario is not high performing and should not be relied upon for
@@ -171,7 +171,7 @@ The process for fetching this value has several variants:
 
 A table that contains an ``IDENTITY`` column will prohibit an INSERT statement
 that refers to the identity column explicitly.  The SQLAlchemy dialect will
-detect when an INSERT construct, created using a core :func:`.insert`
+detect when an INSERT construct, created using a core :func:`~.sql.expression.insert`
 construct (not a plain string SQL), refers to the identity column, and
 in this case will emit ``SET IDENTITY_INSERT ON`` prior to the insert
 statement proceeding, and ``SET IDENTITY_INSERT OFF`` subsequent to the
diff --git a/lib/sqlalchemy/dialects/postgresql/psycopg2.py b/lib/sqlalchemy/dialects/postgresql/psycopg2.py
index 1b1c9b0ba..cf521f06f 100644
--- a/lib/sqlalchemy/dialects/postgresql/psycopg2.py
+++ b/lib/sqlalchemy/dialects/postgresql/psycopg2.py
@@ -178,13 +178,13 @@ Possible options for ``executemany_mode`` include:
   semicolon.   This is the same behavior as was provided by the
   ``use_batch_mode=True`` flag.
 
-* ``'values'``- For Core :func:`.insert` constructs only (including those
+* ``'values'``- For Core :func:`~.sql.expression.insert` constructs only (including those
   emitted by the ORM automatically), the ``psycopg2.extras.execute_values``
   extension is used so that multiple parameter sets are grouped into a single
   INSERT statement and joined together with multiple VALUES expressions.   This
   method requires that the string text of the VALUES clause inside the
   INSERT statement is manipulated, so is only supported with a compiled
-  :func:`.insert` construct where the format is predictable.  For all other
+  :func:`~.sql.expression.insert` construct where the format is predictable.  For all other
   constructs,  including plain textual INSERT statements not rendered  by the
   SQLAlchemy expression language compiler, the
   ``psycopg2.extras.execute_batch``  method is used.   It is therefore important
diff --git a/lib/sqlalchemy/engine/result.py b/lib/sqlalchemy/engine/result.py
index 6755903a0..ac033a5ae 100644
--- a/lib/sqlalchemy/engine/result.py
+++ b/lib/sqlalchemy/engine/result.py
@@ -1203,7 +1203,7 @@ class BaseResult(object):
         corresponding to the list of primary key columns
         in the target table.
 
-        This only applies to single row :func:`.insert`
+        This only applies to single row :func:`~.sql.expression.insert`
         constructs which did not explicitly specify
         :meth:`.Insert.returning`.
 
diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py
index 5619d2e16..cd974190b 100644
--- a/lib/sqlalchemy/orm/mapper.py
+++ b/lib/sqlalchemy/orm/mapper.py
@@ -2227,8 +2227,8 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr):
 
     @property
     def selectable(self):
-        """The :func:`.select` construct this :class:`.Mapper` selects from
-        by default.
+        """The :func:`~.sql.expression.select` construct this
+        :class:`.Mapper` selects from by default.
 
         Normally, this is equivalent to :attr:`.persist_selectable`, unless
         the ``with_polymorphic`` feature is in use, in which case the
@@ -2666,8 +2666,8 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr):
         :param row: A :class:`.Row` instance.  The columns which are
          mapped by this :class:`.Mapper` should be locatable in the row,
          preferably via the :class:`.Column` object directly (as is the case
-         when a :func:`.select` construct is executed), or via string names of
-         the form ``<tablename>_<colname>``.
+         when a :func:`~.sql.expression.select` construct is executed), or
+         via string names of the form ``<tablename>_<colname>``.
 
         """
         pk_cols = self.primary_key
diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 617bba315..3d40339b4 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -548,7 +548,7 @@ class Query(Generative):
          to all columns.
 
         :param reduce_columns: if True, :meth:`.Select.reduce_columns` will
-         be called on the resulting :func:`.select` construct,
+         be called on the resulting :func:`~.sql.expression.select` construct,
          to remove same-named columns where one also refers to the other
          via foreign key or WHERE clause equivalence.
 
@@ -2032,9 +2032,9 @@ class Query(Generative):
 
         There is a lot of flexibility in what the "target" can be when using
         :meth:`~.Query.join`.   As noted previously, it also accepts
-        :class:`.Table` constructs and other selectables such as
-        :func:`.alias` and :func:`.select` constructs, with either the one
-        or two-argument forms::
+        :class:`.Table` constructs and other selectables such as :func:`.alias`
+        and :func:`~.sql.expression.select` constructs, with either the one or
+        two-argument forms::
 
             addresses_q = select([Address.user_id]).\
                         where(Address.email_address.endswith("@bar.com")).\
diff --git a/lib/sqlalchemy/orm/util.py b/lib/sqlalchemy/orm/util.py
index 10cd39e75..48e9b19bf 100644
--- a/lib/sqlalchemy/orm/util.py
+++ b/lib/sqlalchemy/orm/util.py
@@ -767,30 +767,31 @@ def aliased(element, alias=None, name=None, flat=False, adapt_on_names=False):
 
         session.query(MyClass, my_alias).filter(MyClass.id > my_alias.id)
 
-    The :func:`.aliased` function is used to create an ad-hoc mapping
-    of a mapped class to a new selectable.  By default, a selectable
-    is generated from the normally mapped selectable (typically a
-    :class:`.Table`) using the :meth:`.FromClause.alias` method.
-    However, :func:`.aliased` can also be used to link the class to
-    a new :func:`.select` statement.   Also, the :func:`.with_polymorphic`
-    function is a variant of :func:`.aliased` that is intended to specify
-    a so-called "polymorphic selectable", that corresponds to the union
-    of several joined-inheritance subclasses at once.
+    The :func:`.aliased` function is used to create an ad-hoc mapping of a
+    mapped class to a new selectable.  By default, a selectable is generated
+    from the normally mapped selectable (typically a :class:`.Table`) using the
+    :meth:`.FromClause.alias` method. However, :func:`.aliased` can also be
+    used to link the class to a new :func:`~.sql.expression.select` statement.
+    Also, the :func:`.with_polymorphic` function is a variant of
+    :func:`.aliased` that is intended to specify a so-called "polymorphic
+    selectable", that corresponds to the union of several joined-inheritance
+    subclasses at once.
 
     For convenience, the :func:`.aliased` function also accepts plain
     :class:`.FromClause` constructs, such as a :class:`.Table` or
-    :func:`.select` construct.   In those cases, the :meth:`.FromClause.alias`
-    method is called on the object and the new :class:`.Alias` object
-    returned.  The returned :class:`.Alias` is not ORM-mapped in this case.
+    :func:`~.sql.expression.select` construct.   In those cases, the
+    :meth:`.FromClause.alias` method is called on the object and the new
+    :class:`.Alias` object returned.  The returned :class:`.Alias` is not
+    ORM-mapped in this case.
 
     :param element: element to be aliased.  Is normally a mapped class,
      but for convenience can also be a :class:`.FromClause` element.
 
     :param alias: Optional selectable unit to map the element to.  This should
      normally be a :class:`.Alias` object corresponding to the :class:`.Table`
-     to which the class is mapped, or to a :func:`.select` construct that
-     is compatible with the mapping.   By default, a simple anonymous
-     alias of the mapped table is generated.
+     to which the class is mapped, or to a :func:`~.sql.expression.select`
+     construct that is compatible with the mapping.   By default, a simple
+     anonymous alias of the mapped table is generated.
 
     :param name: optional string name to use for the alias, if not specified
      by the ``alias`` parameter.  The name, among other things, forms the
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.
 
     """