Merge "Run search and replace of symbolic module names"

1 files changed, 92 insertions, 92 deletions

diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst
index 2191dee6e..b9b9d6fcb 100644
--- a/doc/build/core/connections.rst
+++ b/doc/build/core/connections.rst
@@ -6,41 +6,41 @@ Working with Engines and Connections
 
 .. module:: sqlalchemy.engine
 
-This section details direct usage of the :class:`.Engine`,
-:class:`.Connection`, and related objects. Its important to note that when
+This section details direct usage of the :class:`_engine.Engine`,
+:class:`_engine.Connection`, and related objects. Its important to note that when
 using the SQLAlchemy ORM, these objects are not generally accessed; instead,
 the :class:`.Session` object is used as the interface to the database.
 However, for applications that are built around direct usage of textual SQL
 statements and/or SQL expression constructs without involvement by the ORM's
-higher level management services, the :class:`.Engine` and
-:class:`.Connection` are king (and queen?) - read on.
+higher level management services, the :class:`_engine.Engine` and
+:class:`_engine.Connection` are king (and queen?) - read on.
 
 Basic Usage
 ===========
 
-Recall from :doc:`/core/engines` that an :class:`.Engine` is created via
+Recall from :doc:`/core/engines` that an :class:`_engine.Engine` is created via
 the :func:`.create_engine` call::
 
     engine = create_engine('mysql://scott:tiger@localhost/test')
 
 The typical usage of :func:`.create_engine()` is once per particular database
 URL, held globally for the lifetime of a single application process. A single
-:class:`.Engine` manages many individual :term:`DBAPI` connections on behalf of
+:class:`_engine.Engine` manages many individual :term:`DBAPI` connections on behalf of
 the process and is intended to be called upon in a concurrent fashion. The
-:class:`.Engine` is **not** synonymous to the DBAPI ``connect`` function, which
-represents just one connection resource - the :class:`.Engine` is most
+:class:`_engine.Engine` is **not** synonymous to the DBAPI ``connect`` function, which
+represents just one connection resource - the :class:`_engine.Engine` is most
 efficient when created just once at the module level of an application, not
 per-object or per-function call.
 
 .. sidebar:: tip
 
-    When using an :class:`.Engine` with multiple Python processes, such as when
+    When using an :class:`_engine.Engine` with multiple Python processes, such as when
     using ``os.fork`` or Python ``multiprocessing``, it's important that the
     engine is initialized per process.  See :ref:`pooling_multiprocessing` for
     details.
 
-The most basic function of the :class:`.Engine` is to provide access to a
-:class:`.Connection`, which can then invoke SQL statements.   To emit
+The most basic function of the :class:`_engine.Engine` is to provide access to a
+:class:`_engine.Connection`, which can then invoke SQL statements.   To emit
 a textual statement to the database looks like::
 
     from sqlalchemy import text
@@ -50,12 +50,12 @@ a textual statement to the database looks like::
         for row in result:
             print("username:", row['username'])
 
-Above, the :meth:`.Engine.connect` method returns a :class:`.Connection`
+Above, the :meth:`_engine.Engine.connect` method returns a :class:`_engine.Connection`
 object, and by using it in a Python context manager (e.g. the ``with:``
-statement) the :meth:`.Connection.close` method is automatically invoked at the
-end of the block.  The :class:`.Connection`, is a **proxy** object for an
+statement) the :meth:`_engine.Connection.close` method is automatically invoked at the
+end of the block.  The :class:`_engine.Connection`, is a **proxy** object for an
 actual DBAPI connection. The DBAPI connection is retrieved from the connection
-pool at the point at which :class:`.Connection` is created.
+pool at the point at which :class:`_engine.Connection` is created.
 
 The object returned is known as :class:`.ResultProxy`, which
 references a DBAPI cursor and provides methods for fetching rows
@@ -65,7 +65,7 @@ exhausted.  A :class:`.ResultProxy` that returns no rows, such as that of
 an UPDATE statement (without any returned rows),
 releases cursor resources immediately upon construction.
 
-When the :class:`.Connection` is closed at the end of the ``with:`` block, the
+When the :class:`_engine.Connection` is closed at the end of the ``with:`` block, the
 referenced DBAPI connection is :term:`released` to the connection pool.   From
 the perspective of the database itself, the connection pool will not actually
 "close" the connection assuming the pool has room to store this connection  for
@@ -78,8 +78,8 @@ its next use.
    2.0 with a newly refined object known as :class:`.future.Result`.
 
 Our example above illustrated the execution of a textual SQL string, which
-should be invoked by using the :func:`.text` construct to indicate that
-we'd like to use textual SQL.  The :meth:`~.Connection.execute` method can of
+should be invoked by using the :func:`_expression.text` construct to indicate that
+we'd like to use textual SQL.  The :meth:`_engine.Connection.execute` method can of
 course accommodate more than that, including the variety of SQL expression
 constructs described in :ref:`sqlexpression_toplevel`.
 
@@ -90,14 +90,14 @@ Using Transactions
 .. note::
 
   This section describes how to use transactions when working directly
-  with :class:`.Engine` and :class:`.Connection` objects. When using the
+  with :class:`_engine.Engine` and :class:`_engine.Connection` objects. When using the
   SQLAlchemy ORM, the public API for transaction control is via the
   :class:`.Session` object, which makes usage of the :class:`.Transaction`
   object internally. See :ref:`unitofwork_transaction` for further
   information.
 
-The :class:`~sqlalchemy.engine.Connection` object provides a :meth:`~.Connection.begin`
-method which returns a :class:`.Transaction` object.  Like the :class:`.Connection`
+The :class:`~sqlalchemy.engine.Connection` object provides a :meth:`_engine.Connection.begin`
+method which returns a :class:`.Transaction` object.  Like the :class:`_engine.Connection`
 itself, this object is usually used within a Python ``with:`` block so
 that its scope is managed::
 
@@ -106,8 +106,8 @@ that its scope is managed::
             r1 = connection.execute(table1.select())
             connection.execute(table1.insert(), {"col1": 7, "col2": "this is some data"})
 
-The above block can be stated more simply by using the :meth:`.Engine.begin`
-method of :class:`.Engine`::
+The above block can be stated more simply by using the :meth:`_engine.Engine.begin`
+method of :class:`_engine.Engine`::
 
     # runs a transaction
     with engine.begin() as connection:
@@ -121,7 +121,7 @@ outwards.
 
 The underlying object used to represent the transaction is the
 :class:`.Transaction` object.  This object is returned by the
-:meth:`.Connection.begin` method and includes the methods
+:meth:`_engine.Connection.begin` method and includes the methods
 :meth:`.Transaction.commit` and :meth:`.Transaction.rollback`.   The context
 manager calling form, which invokes these methods automatically, is recommended
 as a best practice.
@@ -137,7 +137,7 @@ Nesting of Transaction Blocks
 
 The :class:`.Transaction` object also handles "nested" behavior by keeping
 track of the outermost begin/commit pair. In this example, two functions both
-issue a transaction on a :class:`.Connection`, but only the outermost
+issue a transaction on a :class:`_engine.Connection`, but only the outermost
 :class:`.Transaction` object actually takes effect when it is committed.
 
 .. sourcecode:: python+sql
@@ -209,10 +209,10 @@ the ORM, as the :class:`.Session` object by default always maintains an
 ongoing :class:`.Transaction`.
 
 Full control of the "autocommit" behavior is available using the generative
-:meth:`.Connection.execution_options` method provided on :class:`.Connection`
-and :class:`.Engine`, using the "autocommit" flag which will
+:meth:`_engine.Connection.execution_options` method provided on :class:`_engine.Connection`
+and :class:`_engine.Engine`, using the "autocommit" flag which will
 turn on or off the autocommit for the selected scope. For example, a
-:func:`.text` construct representing a stored procedure that commits might use
+:func:`_expression.text` construct representing a stored procedure that commits might use
 it so that a SELECT statement will issue a COMMIT::
 
     with engine.connect().execution_options(autocommit=True) as conn:
@@ -229,10 +229,10 @@ Connectionless Execution, Implicit Execution
    :ref:`migration_20_implicit_execution` for background.
 
 Recall from the first section we mentioned executing with and without explicit
-usage of :class:`.Connection`. "Connectionless" execution
+usage of :class:`_engine.Connection`. "Connectionless" execution
 refers to the usage of the ``execute()`` method on an object
-which is not a :class:`.Connection`.  This was illustrated using the
-:meth:`~.Engine.execute` method of :class:`.Engine`::
+which is not a :class:`_engine.Connection`.  This was illustrated using the
+:meth:`_engine.Engine.execute` method of :class:`_engine.Engine`::
 
     result = engine.execute(text("select username from users"))
     for row in result:
@@ -242,7 +242,7 @@ In addition to "connectionless" execution, it is also possible
 to use the :meth:`~.Executable.execute` method of
 any :class:`.Executable` construct, which is a marker for SQL expression objects
 that support execution.   The SQL expression object itself references an
-:class:`.Engine` or :class:`.Connection` known as the **bind**, which it uses
+:class:`_engine.Engine` or :class:`_engine.Connection` known as the **bind**, which it uses
 in order to provide so-called "implicit" execution services.
 
 Given a table as below::
@@ -256,7 +256,7 @@ Given a table as below::
     )
 
 Explicit execution delivers the SQL text or constructed SQL expression to the
-:meth:`~.Connection.execute` method of :class:`~sqlalchemy.engine.Connection`:
+:meth:`_engine.Connection.execute` method of :class:`~sqlalchemy.engine.Connection`:
 
 .. sourcecode:: python+sql
 
@@ -267,7 +267,7 @@ Explicit execution delivers the SQL text or constructed SQL expression to the
             # ....
 
 Explicit, connectionless execution delivers the expression to the
-:meth:`~.Engine.execute` method of :class:`~sqlalchemy.engine.Engine`:
+:meth:`_engine.Engine.execute` method of :class:`~sqlalchemy.engine.Engine`:
 
 .. sourcecode:: python+sql
 
@@ -284,9 +284,9 @@ for being invoked against the database.    The method makes usage of
 the assumption that either an
 :class:`~sqlalchemy.engine.Engine` or
 :class:`~sqlalchemy.engine.Connection` has been **bound** to the expression
-object.   By "bound" we mean that the special attribute :attr:`.MetaData.bind`
+object.   By "bound" we mean that the special attribute :attr:`_schema.MetaData.bind`
 has been used to associate a series of
-:class:`.Table` objects and all SQL constructs derived from them with a specific
+:class:`_schema.Table` objects and all SQL constructs derived from them with a specific
 engine::
 
     engine = create_engine('sqlite:///file.db')
@@ -296,23 +296,23 @@ engine::
         # ....
     result.close()
 
-Above, we associate an :class:`.Engine` with a :class:`.MetaData` object using
-the special attribute :attr:`.MetaData.bind`.  The :func:`~.sql.expression.select` construct produced
-from the :class:`.Table` object has a method :meth:`~.Executable.execute`, which will
-search for an :class:`.Engine` that's "bound" to the :class:`.Table`.
+Above, we associate an :class:`_engine.Engine` with a :class:`_schema.MetaData` object using
+the special attribute :attr:`_schema.MetaData.bind`.  The :func:`_expression.select` construct produced
+from the :class:`_schema.Table` object has a method :meth:`~.Executable.execute`, which will
+search for an :class:`_engine.Engine` that's "bound" to the :class:`_schema.Table`.
 
 Overall, the usage of "bound metadata" has three general effects:
 
 * SQL statement objects gain an :meth:`.Executable.execute` method which automatically
   locates a "bind" with which to execute themselves.
 * The ORM :class:`.Session` object supports using "bound metadata" in order
-  to establish which :class:`.Engine` should be used to invoke SQL statements
+  to establish which :class:`_engine.Engine` should be used to invoke SQL statements
   on behalf of a particular mapped class, though the :class:`.Session`
-  also features its own explicit system of establishing complex :class:`.Engine`/
+  also features its own explicit system of establishing complex :class:`_engine.Engine`/
   mapped class configurations.
-* The :meth:`.MetaData.create_all`, :meth:`.MetaData.drop_all`, :meth:`.Table.create`,
-  :meth:`.Table.drop`, and "autoload" features all make usage of the bound
-  :class:`.Engine` automatically without the need to pass it explicitly.
+* The :meth:`_schema.MetaData.create_all`, :meth:`_schema.MetaData.drop_all`, :meth:`_schema.Table.create`,
+  :meth:`_schema.Table.drop`, and "autoload" features all make usage of the bound
+  :class:`_engine.Engine` automatically without the need to pass it explicitly.
 
 .. note::
 
@@ -320,11 +320,11 @@ Overall, the usage of "bound metadata" has three general effects:
     While they offer some convenience, they are no longer required by any API and
     are never necessary.
 
-    In applications where multiple :class:`.Engine` objects are present, each one logically associated
+    In applications where multiple :class:`_engine.Engine` objects are present, each one logically associated
     with a certain set of tables (i.e. *vertical sharding*), the "bound metadata" technique can be used
-    so that individual :class:`.Table` can refer to the appropriate :class:`.Engine` automatically;
+    so that individual :class:`_schema.Table` can refer to the appropriate :class:`_engine.Engine` automatically;
     in particular this is supported within the ORM via the :class:`.Session` object
-    as a means to associate :class:`.Table` objects with an appropriate :class:`.Engine`,
+    as a means to associate :class:`_schema.Table` objects with an appropriate :class:`_engine.Engine`,
     as an alternative to using the bind arguments accepted directly by the :class:`.Session`.
 
     However, the "implicit execution" technique is not at all appropriate for use with the
@@ -349,7 +349,7 @@ In both "connectionless" examples, the
 :class:`~sqlalchemy.engine.ResultProxy` returned by the ``execute()``
 call references the :class:`~sqlalchemy.engine.Connection` used to issue
 the SQL statement. When the :class:`.ResultProxy` is closed, the underlying
-:class:`.Connection` is closed for us, resulting in the
+:class:`_engine.Connection` is closed for us, resulting in the
 DBAPI connection being returned to the pool with transactional resources removed.
 
 .. _schema_translating:
@@ -360,7 +360,7 @@ Translation of Schema Names
 To support multi-tenancy applications that distribute common sets of tables
 into multiple schemas, the
 :paramref:`.Connection.execution_options.schema_translate_map`
-execution option may be used to repurpose a set of :class:`.Table` objects
+execution option may be used to repurpose a set of :class:`_schema.Table` objects
 to render under different schema names without any changes.
 
 Given a table::
@@ -371,10 +371,10 @@ Given a table::
         Column('name', String(50))
     )
 
-The "schema" of this :class:`.Table` as defined by the
-:paramref:`.Table.schema` attribute is ``None``.  The
+The "schema" of this :class:`_schema.Table` as defined by the
+:paramref:`_schema.Table.schema` attribute is ``None``.  The
 :paramref:`.Connection.execution_options.schema_translate_map` can specify
-that all :class:`.Table` objects with a schema of ``None`` would instead
+that all :class:`_schema.Table` objects with a schema of ``None`` would instead
 render the schema as ``user_schema_one``::
 
     connection = engine.connect().execution_options(
@@ -399,18 +399,18 @@ map can specify any number of target->destination schemas::
 
 The :paramref:`.Connection.execution_options.schema_translate_map` parameter
 affects all DDL and SQL constructs generated from the SQL expression language,
-as derived from the :class:`.Table` or :class:`.Sequence` objects.
-It does **not** impact literal string SQL used via the :func:`.expression.text`
-construct nor via plain strings passed to :meth:`.Connection.execute`.
+as derived from the :class:`_schema.Table` or :class:`.Sequence` objects.
+It does **not** impact literal string SQL used via the :func:`_expression.text`
+construct nor via plain strings passed to :meth:`_engine.Connection.execute`.
 
 The feature takes effect **only** in those cases where the name of the
-schema is derived directly from that of a :class:`.Table` or :class:`.Sequence`;
+schema is derived directly from that of a :class:`_schema.Table` or :class:`.Sequence`;
 it does not impact methods where a string schema name is passed directly.
 By this pattern, it takes effect within the "can create" / "can drop" checks
-performed by methods such as :meth:`.MetaData.create_all` or
-:meth:`.MetaData.drop_all` are called, and it takes effect when
-using table reflection given a :class:`.Table` object.  However it does
-**not** affect the operations present on the :class:`.Inspector` object,
+performed by methods such as :meth:`_schema.MetaData.create_all` or
+:meth:`_schema.MetaData.drop_all` are called, and it takes effect when
+using table reflection given a :class:`_schema.Table` object.  However it does
+**not** affect the operations present on the :class:`_reflection.Inspector` object,
 as the schema name is passed to these methods explicitly.
 
 .. versionadded:: 1.1
@@ -420,17 +420,17 @@ as the schema name is passed to these methods explicitly.
 Engine Disposal
 ===============
 
-The :class:`.Engine` refers to a connection pool, which means under normal
+The :class:`_engine.Engine` refers to a connection pool, which means under normal
 circumstances, there are open database connections present while the
-:class:`.Engine` object is still resident in memory.   When an :class:`.Engine`
+:class:`_engine.Engine` object is still resident in memory.   When an :class:`_engine.Engine`
 is garbage collected, its connection pool is no longer referred to by
-that :class:`.Engine`, and assuming none of its connections are still checked
+that :class:`_engine.Engine`, and assuming none of its connections are still checked
 out, the pool and its connections will also be garbage collected, which has the
 effect of closing out the actual database connections as well.   But otherwise,
-the :class:`.Engine` will hold onto open database connections assuming
+the :class:`_engine.Engine` will hold onto open database connections assuming
 it uses the normally default pool implementation of :class:`.QueuePool`.
 
-The :class:`.Engine` is intended to normally be a permanent
+The :class:`_engine.Engine` is intended to normally be a permanent
 fixture established up-front and maintained throughout the lifespan of an
 application.  It is **not** intended to be created and disposed on a
 per-connection basis; it is instead a registry that maintains both a pool
@@ -439,45 +439,45 @@ and DBAPI in use, as well as some degree of internal caching of per-database
 resources.
 
 However, there are many cases where it is desirable that all connection resources
-referred to by the :class:`.Engine` be completely closed out.  It's
+referred to by the :class:`_engine.Engine` be completely closed out.  It's
 generally not a good idea to rely on Python garbage collection for this
-to occur for these cases; instead, the :class:`.Engine` can be explicitly disposed using
-the :meth:`.Engine.dispose` method.   This disposes of the engine's
+to occur for these cases; instead, the :class:`_engine.Engine` can be explicitly disposed using
+the :meth:`_engine.Engine.dispose` method.   This disposes of the engine's
 underlying connection pool and replaces it with a new one that's empty.
-Provided that the :class:`.Engine`
+Provided that the :class:`_engine.Engine`
 is discarded at this point and no longer used, all **checked-in** connections
 which it refers to will also be fully closed.
 
-Valid use cases for calling :meth:`.Engine.dispose` include:
+Valid use cases for calling :meth:`_engine.Engine.dispose` include:
 
 * When a program wants to release any remaining checked-in connections
   held by the connection pool and expects to no longer be connected
   to that database at all for any future operations.
 
 * When a program uses multiprocessing or ``fork()``, and an
-  :class:`.Engine` object is copied to the child process,
-  :meth:`.Engine.dispose` should be called so that the engine creates
+  :class:`_engine.Engine` object is copied to the child process,
+  :meth:`_engine.Engine.dispose` should be called so that the engine creates
   brand new database connections local to that fork.   Database connections
   generally do **not** travel across process boundaries.
 
 * Within test suites or multitenancy scenarios where many
-  ad-hoc, short-lived :class:`.Engine` objects may be created and disposed.
+  ad-hoc, short-lived :class:`_engine.Engine` objects may be created and disposed.
 
 
 Connections that are **checked out** are **not** discarded when the
 engine is disposed or garbage collected, as these connections are still
 strongly referenced elsewhere by the application.
-However, after :meth:`.Engine.dispose` is called, those
-connections are no longer associated with that :class:`.Engine`; when they
+However, after :meth:`_engine.Engine.dispose` is called, those
+connections are no longer associated with that :class:`_engine.Engine`; when they
 are closed, they will be returned to their now-orphaned connection pool
 which will ultimately be garbage collected, once all connections which refer
 to it are also no longer referenced anywhere.
 Since this process is not easy to control, it is strongly recommended that
-:meth:`.Engine.dispose` is called only after all checked out connections
+:meth:`_engine.Engine.dispose` is called only after all checked out connections
 are checked in or otherwise de-associated from their pool.
 
 An alternative for applications that are negatively impacted by the
-:class:`.Engine` object's use of connection pooling is to disable pooling
+:class:`_engine.Engine` object's use of connection pooling is to disable pooling
 entirely.  This typically incurs only a modest performance impact upon the
 use of new connections, and means that when a connection is checked in,
 it is entirely closed out and is not held in memory.  See :ref:`pool_switching`
@@ -488,12 +488,12 @@ for guidelines on how to disable pooling.
 Working with Driver SQL and Raw DBAPI Connections
 =================================================
 
-The introduction on using :meth:`.Connection.execute` made use of the
-:func:`.sql.text` construct in order to illustrate how textual SQL statements
+The introduction on using :meth:`_engine.Connection.execute` made use of the
+:func:`_expression.text` construct in order to illustrate how textual SQL statements
 may be invoked.  When working with SQLAlchemy, textual SQL is actually more
 of the exception rather than the norm, as the Core expression language
 and the ORM both abstract away the textual representation of SQL.  Hpwever, the
-:func:`.sql.text` construct itself also provides some abstraction of textual
+:func:`_expression.text` construct itself also provides some abstraction of textual
 SQL in that it normalizes how bound parameters are passed, as well as that
 it supports datatyping behavior for parameters and result set rows.
 
@@ -502,14 +502,14 @@ Invoking SQL strings directly to the driver
 
 For the use case where one wants to invoke textual SQL directly passed to the
 underlying driver (known as the :term:`DBAPI`) without any intervention
-from the :func:`.sql.text` construct, the :meth:`.Connection.exec_driver_sql`
+from the :func:`_expression.text` construct, the :meth:`_engine.Connection.exec_driver_sql`
 method may be used::
 
     with engine.connect() as conn:
         conn.exec_driver_sql("SET param='bar'")
 
 
-.. versionadded:: 1.4  Added the :meth:`.Connection.exec_driver_sql` method.
+.. versionadded:: 1.4  Added the :meth:`_engine.Connection.exec_driver_sql` method.
 
 Working with the DBAPI cursor directly
 --------------------------------------
@@ -520,8 +520,8 @@ as dealing with multiple result sets.  In these cases, it's just as expedient
 to deal with the raw DBAPI connection directly.
 
 The most common way to access the raw DBAPI connection is to get it
-from an already present :class:`.Connection` object directly.  It is
-present using the :attr:`.Connection.connection` attribute::
+from an already present :class:`_engine.Connection` object directly.  It is
+present using the :attr:`_engine.Connection.connection` attribute::
 
     connection = engine.connect()
     dbapi_conn = connection.connection
@@ -529,17 +529,17 @@ present using the :attr:`.Connection.connection` attribute::
 The DBAPI connection here is actually a "proxied" in terms of the
 originating connection pool, however this is an implementation detail
 that in most cases can be ignored.    As this DBAPI connection is still
-contained within the scope of an owning :class:`.Connection` object, it is
-best to make use of the :class:`.Connection` object for most features such
-as transaction control as well as calling the :meth:`.Connection.close`
+contained within the scope of an owning :class:`_engine.Connection` object, it is
+best to make use of the :class:`_engine.Connection` object for most features such
+as transaction control as well as calling the :meth:`_engine.Connection.close`
 method; if these operations are performed on the DBAPI connection directly,
-the owning :class:`.Connection` will not be aware of these changes in state.
+the owning :class:`_engine.Connection` will not be aware of these changes in state.
 
 To overcome the limitations imposed by the DBAPI connection that is
-maintained by an owning :class:`.Connection`, a DBAPI connection is also
+maintained by an owning :class:`_engine.Connection`, a DBAPI connection is also
 available without the need to procure a
-:class:`.Connection` first, using the :meth:`.Engine.raw_connection` method
-of :class:`.Engine`::
+:class:`_engine.Connection` first, using the :meth:`_engine.Engine.raw_connection` method
+of :class:`_engine.Engine`::
 
     dbapi_conn = engine.raw_connection()