diff options
Diffstat (limited to 'lib/sqlalchemy/engine')
| -rw-r--r-- | lib/sqlalchemy/engine/base.py | 393 | ||||
| -rw-r--r-- | lib/sqlalchemy/engine/create.py | 40 | ||||
| -rw-r--r-- | lib/sqlalchemy/engine/default.py | 13 | ||||
| -rw-r--r-- | lib/sqlalchemy/engine/events.py | 176 | ||||
| -rw-r--r-- | lib/sqlalchemy/engine/interfaces.py | 128 | ||||
| -rw-r--r-- | lib/sqlalchemy/engine/mock.py | 3 | ||||
| -rw-r--r-- | lib/sqlalchemy/engine/reflection.py | 65 | ||||
| -rw-r--r-- | lib/sqlalchemy/engine/result.py | 17 |
8 files changed, 472 insertions, 363 deletions
diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py index 1a5562a9b..014d433a7 100644 --- a/lib/sqlalchemy/engine/base.py +++ b/lib/sqlalchemy/engine/base.py @@ -20,7 +20,7 @@ from ..sql import compiler from ..sql import util as sql_util -"""Defines :class:`.Connection` and :class:`.Engine`. +"""Defines :class:`_engine.Connection` and :class:`_engine.Engine`. """ @@ -29,7 +29,8 @@ class Connection(Connectable): """Provides high-level functionality for a wrapped DB-API connection. Provides execution support for string-based SQL statements as well as - :class:`.ClauseElement`, :class:`.Compiled` and :class:`.DefaultGenerator` + :class:`_expression.ClauseElement`, :class:`.Compiled` and + :class:`.DefaultGenerator` objects. Provides a :meth:`begin` method to return :class:`.Transaction` objects. @@ -185,10 +186,12 @@ class Connection(Connectable): r""" Set non-SQL options for the connection which take effect during execution. - The method returns a copy of this :class:`.Connection` which references + The method returns a copy of this :class:`_engine.Connection` + which references the same underlying DBAPI connection, but also defines the given execution options which will take effect for a call to - :meth:`execute`. As the new :class:`.Connection` references the same + :meth:`execute`. As the new :class:`_engine.Connection` + references the same underlying resource, it's usually a good idea to ensure that the copies will be discarded immediately, which is implicit if used as in:: @@ -196,14 +199,16 @@ class Connection(Connectable): execute(stmt) Note that any key/value can be passed to - :meth:`.Connection.execution_options`, and it will be stored in the - ``_execution_options`` dictionary of the :class:`.Connection`. It + :meth:`_engine.Connection.execution_options`, + and it will be stored in the + ``_execution_options`` dictionary of the :class:`_engine.Connection`. + It is suitable for usage by end-user schemes to communicate with event listeners, for example. The keywords that are currently recognized by SQLAlchemy itself include all those listed under :meth:`.Executable.execution_options`, - as well as others that are specific to :class:`.Connection`. + as well as others that are specific to :class:`_engine.Connection`. :param autocommit: Available on: Connection, statement. When True, a COMMIT will be invoked after execution @@ -221,7 +226,8 @@ class Connection(Connectable): :param compiled_cache: Available on: Connection. A dictionary where :class:`.Compiled` objects - will be cached when the :class:`.Connection` compiles a clause + will be cached when the :class:`_engine.Connection` + compiles a clause expression into a :class:`.Compiled` object. It is the user's responsibility to manage the size of this dictionary, which will have keys @@ -236,10 +242,11 @@ class Connection(Connectable): used by the ORM internally supersedes a cache dictionary specified here. - :param isolation_level: Available on: :class:`.Connection`. + :param isolation_level: Available on: :class:`_engine.Connection`. Set the transaction isolation level for the lifespan of this - :class:`.Connection` object. Valid values include those string + :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 semi-database specific; see individual dialect documentation for @@ -248,25 +255,27 @@ class Connection(Connectable): The isolation level option applies the isolation level by emitting statements on the DBAPI connection, and **necessarily affects the original Connection object overall**, not just the copy that is - returned by the call to :meth:`.Connection.execution_options` + returned by the call to :meth:`_engine.Connection.execution_options` method. The isolation level will remain at the given setting until the DBAPI connection itself is returned to the connection pool, i.e. - the :meth:`.Connection.close` method on the original - :class:`.Connection` is called, where an event handler will emit + the :meth:`_engine.Connection.close` method on the original + :class:`_engine.Connection` is called, + where an event handler will emit additional statements on the DBAPI connection in order to revert the isolation level change. .. warning:: The ``isolation_level`` execution option should **not** be used when a transaction is already established, that - is, the :meth:`.Connection.begin` method or similar has been + is, the :meth:`_engine.Connection.begin` + method or similar has been called. A database cannot change the isolation level on a transaction in progress, and different DBAPIs and/or SQLAlchemy dialects may implicitly roll back or commit the transaction, or not affect the connection at all. .. note:: The ``isolation_level`` execution option is implicitly - reset if the :class:`.Connection` is invalidated, e.g. via - the :meth:`.Connection.invalidate` method, or if a + reset if the :class:`_engine.Connection` is invalidated, e.g. via + the :meth:`_engine.Connection.invalidate` method, or if a disconnection error occurs. The new connection produced after the invalidation will not have the isolation level re-applied to it automatically. @@ -274,9 +283,10 @@ class Connection(Connectable): .. seealso:: :paramref:`.create_engine.isolation_level` - - set per :class:`.Engine` isolation level + - set per :class:`_engine.Engine` isolation level - :meth:`.Connection.get_isolation_level` - view current level + :meth:`_engine.Connection.get_isolation_level` + - view current level :ref:`SQLite Transaction Isolation <sqlite_isolation_level>` @@ -308,8 +318,9 @@ class Connection(Connectable): :param schema_translate_map: Available on: Connection, Engine. A dictionary mapping schema names to schema names, that will be - applied to the :paramref:`.Table.schema` element of each - :class:`.Table` encountered when SQL or DDL expression elements + applied to the :paramref:`_schema.Table.schema` element of each + :class:`_schema.Table` + encountered when SQL or DDL expression elements are compiled into strings; the resulting schema name will be converted based on presence in the map of the original name. @@ -321,11 +332,11 @@ class Connection(Connectable): .. seealso:: - :meth:`.Engine.execution_options` + :meth:`_engine.Engine.execution_options` :meth:`.Executable.execution_options` - :meth:`.Connection.get_execution_options` + :meth:`_engine.Connection.get_execution_options` """ # noqa @@ -343,7 +354,7 @@ class Connection(Connectable): .. seealso:: - :meth:`.Connection.execution_options` + :meth:`_engine.Connection.execution_options` """ return self._execution_options @@ -386,19 +397,19 @@ class Connection(Connectable): def get_isolation_level(self): """Return the current isolation level assigned to this - :class:`.Connection`. + :class:`_engine.Connection`. This will typically be the default isolation level as determined by the dialect, unless if the :paramref:`.Connection.execution_options.isolation_level` feature has been used to alter the isolation level on a - per-:class:`.Connection` basis. + per-:class:`_engine.Connection` basis. This attribute will typically perform a live SQL operation in order to procure the current isolation level, so the value returned is the actual level on the underlying DBAPI connection regardless of how this state was set. Compare to the - :attr:`.Connection.default_isolation_level` accessor + :attr:`_engine.Connection.default_isolation_level` accessor which returns the dialect-level setting without performing a SQL query. @@ -406,13 +417,14 @@ class Connection(Connectable): .. seealso:: - :attr:`.Connection.default_isolation_level` - view default level + :attr:`_engine.Connection.default_isolation_level` + - view default level :paramref:`.create_engine.isolation_level` - - set per :class:`.Engine` isolation level + - set per :class:`_engine.Engine` isolation level :paramref:`.Connection.execution_options.isolation_level` - - set per :class:`.Connection` isolation level + - set per :class:`_engine.Connection` isolation level """ try: @@ -422,15 +434,18 @@ class Connection(Connectable): @property def default_isolation_level(self): - """The default isolation level assigned to this :class:`.Connection`. + """The default isolation level assigned to this + :class:`_engine.Connection`. - This is the isolation level setting that the :class:`.Connection` - has when first procured via the :meth:`.Engine.connect` method. + This is the isolation level setting that the + :class:`_engine.Connection` + has when first procured via the :meth:`_engine.Engine.connect` method. This level stays in place until the :paramref:`.Connection.execution_options.isolation_level` is used - to change the setting on a per-:class:`.Connection` basis. + to change the setting on a per-:class:`_engine.Connection` basis. - Unlike :meth:`.Connection.get_isolation_level`, this attribute is set + Unlike :meth:`_engine.Connection.get_isolation_level`, + this attribute is set ahead of time from the first connection procured by the dialect, so SQL query is not invoked when this accessor is called. @@ -438,13 +453,14 @@ class Connection(Connectable): .. seealso:: - :meth:`.Connection.get_isolation_level` - view current level + :meth:`_engine.Connection.get_isolation_level` + - view current level :paramref:`.create_engine.isolation_level` - - set per :class:`.Engine` isolation level + - set per :class:`_engine.Engine` isolation level :paramref:`.Connection.execution_options.isolation_level` - - set per :class:`.Connection` isolation level + - set per :class:`_engine.Connection` isolation level """ return self.dialect.default_isolation_level @@ -482,12 +498,12 @@ class Connection(Connectable): @property def info(self): """Info dictionary associated with the underlying DBAPI connection - referred to by this :class:`.Connection`, allowing user-defined + referred to by this :class:`_engine.Connection`, allowing user-defined data to be associated with the connection. The data here will follow along with the DBAPI connection including after it is returned to the connection pool and used again - in subsequent instances of :class:`.Connection`. + in subsequent instances of :class:`_engine.Connection`. """ @@ -495,14 +511,14 @@ class Connection(Connectable): @util.deprecated_20(":meth:`.Connection.connect`") def connect(self, close_with_result=False): - """Returns a branched version of this :class:`.Connection`. + """Returns a branched version of this :class:`_engine.Connection`. - The :meth:`.Connection.close` method on the returned - :class:`.Connection` can be called and this - :class:`.Connection` will remain open. + The :meth:`_engine.Connection.close` method on the returned + :class:`_engine.Connection` can be called and this + :class:`_engine.Connection` will remain open. This method provides usage symmetry with - :meth:`.Engine.connect`, including for usage + :meth:`_engine.Engine.connect`, including for usage with context managers. """ @@ -511,36 +527,38 @@ class Connection(Connectable): def invalidate(self, exception=None): """Invalidate the underlying DBAPI connection associated with - this :class:`.Connection`. + this :class:`_engine.Connection`. The underlying DBAPI connection is literally closed (if possible), and is discarded. Its source connection pool will typically lazily create a new connection to replace it. Upon the next use (where "use" typically means using the - :meth:`.Connection.execute` method or similar), - this :class:`.Connection` will attempt to + :meth:`_engine.Connection.execute` method or similar), + this :class:`_engine.Connection` will attempt to procure a new DBAPI connection using the services of the - :class:`.Pool` as a source of connectivity (e.g. a "reconnection"). + :class:`_pool.Pool` as a source of connectivity (e.g. + a "reconnection"). If a transaction was in progress (e.g. the - :meth:`.Connection.begin` method has been called) when - :meth:`.Connection.invalidate` method is called, at the DBAPI + :meth:`_engine.Connection.begin` method has been called) when + :meth:`_engine.Connection.invalidate` method is called, at the DBAPI level all state associated with this transaction is lost, as - the DBAPI connection is closed. The :class:`.Connection` + the DBAPI connection is closed. The :class:`_engine.Connection` will not allow a reconnection to proceed until the :class:`.Transaction` object is ended, by calling the :meth:`.Transaction.rollback` method; until that point, any attempt at - continuing to use the :class:`.Connection` will raise an + continuing to use the :class:`_engine.Connection` will raise an :class:`~sqlalchemy.exc.InvalidRequestError`. This is to prevent applications from accidentally continuing an ongoing transactional operations despite the fact that the transaction has been lost due to an invalidation. - The :meth:`.Connection.invalidate` method, just like auto-invalidation, + The :meth:`_engine.Connection.invalidate` method, + just like auto-invalidation, will at the connection pool level invoke the - :meth:`.PoolEvents.invalidate` event. + :meth:`_events.PoolEvents.invalidate` event. .. seealso:: @@ -573,7 +591,8 @@ class Connection(Connectable): # connection is fully closed (since we used "with:", can # also call .close()) - This :class:`.Connection` instance will remain usable. When closed + This :class:`_engine.Connection` instance will remain usable. + When closed (or exited from a context manager context as above), the DB-API connection will be literally closed and not returned to its originating pool. @@ -594,7 +613,7 @@ class Connection(Connectable): which completes when either the :meth:`.Transaction.rollback` or :meth:`.Transaction.commit` method is called. - Nested calls to :meth:`.begin` on the same :class:`.Connection` + Nested calls to :meth:`.begin` on the same :class:`_engine.Connection` will return new :class:`.Transaction` objects that represent an emulated transaction within the scope of the enclosing transaction, that is:: @@ -612,13 +631,13 @@ class Connection(Connectable): .. seealso:: - :meth:`.Connection.begin_nested` - use a SAVEPOINT + :meth:`_engine.Connection.begin_nested` - use a SAVEPOINT - :meth:`.Connection.begin_twophase` - + :meth:`_engine.Connection.begin_twophase` - use a two phase /XID transaction - :meth:`.Engine.begin` - context manager available from - :class:`.Engine` + :meth:`_engine.Engine.begin` - context manager available from + :class:`_engine.Engine` """ if self.__branch_from: @@ -643,9 +662,9 @@ class Connection(Connectable): .. seealso:: - :meth:`.Connection.begin` + :meth:`_engine.Connection.begin` - :meth:`.Connection.begin_twophase` + :meth:`_engine.Connection.begin_twophase` """ if self.__branch_from: @@ -671,9 +690,9 @@ class Connection(Connectable): .. seealso:: - :meth:`.Connection.begin` + :meth:`_engine.Connection.begin` - :meth:`.Connection.begin_twophase` + :meth:`_engine.Connection.begin_twophase` """ @@ -870,21 +889,21 @@ class Connection(Connectable): self._root._rollback_impl() def close(self): - """Close this :class:`.Connection`. + """Close this :class:`_engine.Connection`. This results in a release of the underlying database resources, that is, the DBAPI connection referenced internally. The DBAPI connection is typically restored - back to the connection-holding :class:`.Pool` referenced - by the :class:`.Engine` that produced this - :class:`.Connection`. Any transactional state present on + back to the connection-holding :class:`_pool.Pool` referenced + by the :class:`_engine.Engine` that produced this + :class:`_engine.Connection`. Any transactional state present on the DBAPI connection is also unconditionally released via the DBAPI connection's ``rollback()`` method, regardless of any :class:`.Transaction` object that may be - outstanding with regards to this :class:`.Connection`. + outstanding with regards to this :class:`_engine.Connection`. - After :meth:`~.Connection.close` is called, the - :class:`.Connection` is permanently in a closed state, + After :meth:`_engine.Connection.close` is called, the + :class:`_engine.Connection` is permanently in a closed state, and will allow no further operations. """ @@ -937,9 +956,9 @@ class Connection(Connectable): one of: * a plain string (deprecated) - * any :class:`.ClauseElement` construct that is also + * any :class:`_expression.ClauseElement` construct that is also a subclass of :class:`.Executable`, such as a - :func:`~.expression.select` construct + :func:`_expression.select` construct * a :class:`.FunctionElement`, such as that generated by :data:`.func`, will be automatically wrapped in a SELECT statement, which is then executed. @@ -947,11 +966,13 @@ class Connection(Connectable): * a :class:`.DefaultGenerator` object * a :class:`.Compiled` object - .. deprecated:: 2.0 passing a string to :meth:`.Connection.execute` is + .. deprecated:: 2.0 passing a string to + :meth:`_engine.Connection.execute` is deprecated and will be removed in version 2.0. Use the - :func:`~.expression.text` construct with - :meth:`.Connection.execute`, or the - :meth:`.Connection.exec_driver_sql` method to invoke a driver-level + :func:`_expression.text` construct with + :meth:`_engine.Connection.execute`, or the + :meth:`_engine.Connection.exec_driver_sql` + method to invoke a driver-level SQL string. :param \*multiparams/\**params: represent bound parameter @@ -992,7 +1013,7 @@ class Connection(Connectable): for details on paramstyle. To execute a textual SQL statement which uses bound parameters in a - DBAPI-agnostic way, use the :func:`~.expression.text` construct. + DBAPI-agnostic way, use the :func:`_expression.text` construct. .. deprecated:: 2.0 use of tuple or scalar positional parameters is deprecated. All params should be dicts or sequences of dicts. @@ -1653,14 +1674,15 @@ class Connection(Connectable): @util.deprecated( "1.4", - "The :meth:`.Connection.transaction` method is deprecated and will be " - "removed in a future release. Use the :meth:`.Engine.begin` " + "The :meth:`_engine.Connection.transaction` " + "method is deprecated and will be " + "removed in a future release. Use the :meth:`_engine.Engine.begin` " "context manager instead.", ) def transaction(self, callable_, *args, **kwargs): r"""Execute the given function within a transaction boundary. - The function is passed this :class:`.Connection` + The function is passed this :class:`_engine.Connection` as the first argument, followed by the given \*args and \**kwargs, e.g.:: @@ -1679,23 +1701,23 @@ class Connection(Connectable): The :meth:`.transaction` method is superseded by the usage of the Python ``with:`` statement, which can - be used with :meth:`.Connection.begin`:: + be used with :meth:`_engine.Connection.begin`:: with conn.begin(): conn.execute(text("some statement"), {'x':5, 'y':10}) - As well as with :meth:`.Engine.begin`:: + As well as with :meth:`_engine.Engine.begin`:: with engine.begin() as conn: conn.execute(text("some statement"), {'x':5, 'y':10}) .. seealso:: - :meth:`.Engine.begin` - engine-level transactional + :meth:`_engine.Engine.begin` - engine-level transactional context - :meth:`.Engine.transaction` - engine-level version of - :meth:`.Connection.transaction` + :meth:`_engine.Engine.transaction` - engine-level version of + :meth:`_engine.Connection.transaction` """ @@ -1711,19 +1733,20 @@ class Connection(Connectable): @util.deprecated( "1.4", - "The :meth:`.Connection.run_callable` method is deprecated and will " + "The :meth:`_engine.Connection.run_callable` " + "method is deprecated and will " "be removed in a future release. Use a context manager instead.", ) def run_callable(self, callable_, *args, **kwargs): r"""Given a callable object or function, execute it, passing - a :class:`.Connection` as the first argument. + a :class:`_engine.Connection` as the first argument. The given \*args and \**kwargs are passed subsequent - to the :class:`.Connection` argument. + to the :class:`_engine.Connection` argument. - This function, along with :meth:`.Engine.run_callable`, - allows a function to be run with a :class:`.Connection` - or :class:`.Engine` object without the need to know + This function, along with :meth:`_engine.Engine.run_callable`, + allows a function to be run with a :class:`_engine.Connection` + or :class:`_engine.Engine` object without the need to know which one is being dealt with. """ @@ -1761,8 +1784,8 @@ class Transaction(object): """Represent a database transaction in progress. The :class:`.Transaction` object is procured by - calling the :meth:`~.Connection.begin` method of - :class:`.Connection`:: + calling the :meth:`_engine.Connection.begin` method of + :class:`_engine.Connection`:: from sqlalchemy import create_engine engine = create_engine("postgresql://scott:tiger@localhost/test") @@ -1775,7 +1798,7 @@ class Transaction(object): methods in order to control transaction boundaries. It also implements a context manager interface so that the Python ``with`` statement can be used with the - :meth:`.Connection.begin` method:: + :meth:`_engine.Connection.begin` method:: with connection.begin(): connection.execute(text("insert into x (a, b) values (1, 2)")) @@ -1784,11 +1807,11 @@ class Transaction(object): .. seealso:: - :meth:`.Connection.begin` + :meth:`_engine.Connection.begin` - :meth:`.Connection.begin_twophase` + :meth:`_engine.Connection.begin_twophase` - :meth:`.Connection.begin_nested` + :meth:`_engine.Connection.begin_nested` .. index:: single: thread safety; Transaction @@ -1886,7 +1909,7 @@ class NestedTransaction(Transaction): """Represent a 'nested', or SAVEPOINT transaction. A new :class:`.NestedTransaction` object may be procured - using the :meth:`.Connection.begin_nested` method. + using the :meth:`_engine.Connection.begin_nested` method. The interface is the same as that of :class:`.Transaction`. @@ -1917,7 +1940,7 @@ class TwoPhaseTransaction(Transaction): """Represent a two-phase transaction. A new :class:`.TwoPhaseTransaction` object may be procured - using the :meth:`.Connection.begin_twophase` method. + using the :meth:`_engine.Connection.begin_twophase` method. The interface is the same as that of :class:`.Transaction` with the addition of the :meth:`prepare` method. @@ -1954,7 +1977,7 @@ class Engine(Connectable, log.Identified): :class:`~sqlalchemy.engine.interfaces.Dialect` together to provide a source of database connectivity and behavior. - An :class:`.Engine` object is instantiated publicly using the + An :class:`_engine.Engine` object is instantiated publicly using the :func:`~sqlalchemy.create_engine` function. .. seealso:: @@ -1998,7 +2021,7 @@ class Engine(Connectable, log.Identified): def update_execution_options(self, **opt): r"""Update the default execution_options dictionary - of this :class:`.Engine`. + of this :class:`_engine.Engine`. The given keys/values in \**opt are added to the default execution options that will be used for @@ -2008,9 +2031,9 @@ class Engine(Connectable, log.Identified): .. seealso:: - :meth:`.Connection.execution_options` + :meth:`_engine.Connection.execution_options` - :meth:`.Engine.execution_options` + :meth:`_engine.Engine.execution_options` """ self._execution_options = self._execution_options.union(opt) @@ -2018,25 +2041,28 @@ class Engine(Connectable, log.Identified): self.dialect.set_engine_execution_options(self, opt) def execution_options(self, **opt): - """Return a new :class:`.Engine` that will provide - :class:`.Connection` objects with the given execution options. + """Return a new :class:`_engine.Engine` that will provide + :class:`_engine.Connection` objects with the given execution options. - The returned :class:`.Engine` remains related to the original - :class:`.Engine` in that it shares the same connection pool and + The returned :class:`_engine.Engine` remains related to the original + :class:`_engine.Engine` in that it shares the same connection pool and other state: - * The :class:`.Pool` used by the new :class:`.Engine` is the - same instance. The :meth:`.Engine.dispose` method will replace + * The :class:`_pool.Pool` used by the new :class:`_engine.Engine` + is the + same instance. The :meth:`_engine.Engine.dispose` + method will replace the connection pool instance for the parent engine as well as this one. - * Event listeners are "cascaded" - meaning, the new :class:`.Engine` + * Event listeners are "cascaded" - meaning, the new + :class:`_engine.Engine` inherits the events of the parent, and new events can be associated - with the new :class:`.Engine` individually. + with the new :class:`_engine.Engine` individually. * The logging configuration and logging_name is copied from the parent - :class:`.Engine`. + :class:`_engine.Engine`. - The intent of the :meth:`.Engine.execution_options` method is - to implement "sharding" schemes where multiple :class:`.Engine` + The intent of the :meth:`_engine.Engine.execution_options` method is + to implement "sharding" schemes where multiple :class:`_engine.Engine` objects refer to the same connection pool, but are differentiated by options that would be consumed by a custom event:: @@ -2045,15 +2071,18 @@ class Engine(Connectable, log.Identified): shard2 = primary_engine.execution_options(shard_id="shard2") Above, the ``shard1`` engine serves as a factory for - :class:`.Connection` objects that will contain the execution option - ``shard_id=shard1``, and ``shard2`` will produce :class:`.Connection` + :class:`_engine.Connection` + objects that will contain the execution option + ``shard_id=shard1``, and ``shard2`` will produce + :class:`_engine.Connection` objects that contain the execution option ``shard_id=shard2``. An event handler can consume the above execution option to perform a schema switch or other operation, given a connection. Below we emit a MySQL ``use`` statement to switch databases, at the same time keeping track of which database we've established using the - :attr:`.Connection.info` dictionary, which gives us a persistent + :attr:`_engine.Connection.info` dictionary, + which gives us a persistent storage space that follows the DBAPI connection:: from sqlalchemy import event @@ -2073,13 +2102,15 @@ class Engine(Connectable, log.Identified): .. seealso:: - :meth:`.Connection.execution_options` - update execution options - on a :class:`.Connection` object. + :meth:`_engine.Connection.execution_options` + - update execution options + on a :class:`_engine.Connection` object. - :meth:`.Engine.update_execution_options` - update the execution - options for a given :class:`.Engine` in place. + :meth:`_engine.Engine.update_execution_options` + - update the execution + options for a given :class:`_engine.Engine` in place. - :meth:`.Engine.get_execution_options` + :meth:`_engine.Engine.get_execution_options` """ @@ -2092,7 +2123,7 @@ class Engine(Connectable, log.Identified): .. seealso:: - :meth:`.Engine.execution_options` + :meth:`_engine.Engine.execution_options` """ return self._execution_options @@ -2116,20 +2147,23 @@ class Engine(Connectable, log.Identified): return "Engine(%r)" % self.url def dispose(self): - """Dispose of the connection pool used by this :class:`.Engine`. + """Dispose of the connection pool used by this :class:`_engine.Engine` + . This has the effect of fully closing all **currently checked in** database connections. Connections that are still checked out will **not** be closed, however they will no longer be associated - with this :class:`.Engine`, so when they are closed individually, - eventually the :class:`.Pool` which they are associated with will + with this :class:`_engine.Engine`, + so when they are closed individually, + eventually the :class:`_pool.Pool` which they are associated with will be garbage collected and they will be closed out fully, if not already closed on checkin. A new connection pool is created immediately after the old one has been disposed. This new pool, like all SQLAlchemy connection pools, does not make any actual connections to the database until one is - first requested, so as long as the :class:`.Engine` isn't used again, + first requested, so as long as the :class:`_engine.Engine` + isn't used again, no new connections will be made. .. seealso:: @@ -2171,7 +2205,7 @@ class Engine(Connectable, log.Identified): self.conn.close() def begin(self, close_with_result=False): - """Return a context manager delivering a :class:`.Connection` + """Return a context manager delivering a :class:`_engine.Connection` with a :class:`.Transaction` established. E.g.:: @@ -2187,20 +2221,22 @@ class Engine(Connectable, log.Identified): is rolled back. The ``close_with_result`` flag is normally ``False``, and indicates - that the :class:`.Connection` will be closed when the operation + that the :class:`_engine.Connection` will be closed when the operation is complete. When set to ``True``, it indicates the - :class:`.Connection` is in "single use" mode, where the + :class:`_engine.Connection` is in "single use" mode, where the :class:`.ResultProxy` returned by the first call to - :meth:`.Connection.execute` will close the :class:`.Connection` when + :meth:`_engine.Connection.execute` will close the + :class:`_engine.Connection` when that :class:`.ResultProxy` has exhausted all result rows. .. seealso:: - :meth:`.Engine.connect` - procure a :class:`.Connection` from - an :class:`.Engine`. + :meth:`_engine.Engine.connect` - procure a + :class:`_engine.Connection` from + an :class:`_engine.Engine`. - :meth:`.Connection.begin` - start a :class:`.Transaction` - for a particular :class:`.Connection`. + :meth:`_engine.Connection.begin` - start a :class:`.Transaction` + for a particular :class:`_engine.Connection`. """ conn = self.connect(close_with_result=close_with_result) @@ -2213,15 +2249,17 @@ class Engine(Connectable, log.Identified): @util.deprecated( "1.4", - "The :meth:`.Engine.transaction` method is deprecated and will be " - "removed in a future release. Use the :meth:`.Engine.begin` context " + "The :meth:`_engine.Engine.transaction` " + "method is deprecated and will be " + "removed in a future release. Use the :meth:`_engine.Engine.begin` " + "context " "manager instead.", ) def transaction(self, callable_, *args, **kwargs): r"""Execute the given function within a transaction boundary. - The function is passed a :class:`.Connection` newly procured - from :meth:`.Engine.connect` as the first argument, + The function is passed a :class:`_engine.Connection` newly procured + from :meth:`_engine.Engine.connect` as the first argument, followed by the given \*args and \**kwargs. e.g.:: @@ -2241,18 +2279,19 @@ class Engine(Connectable, log.Identified): The :meth:`.transaction` method is superseded by the usage of the Python ``with:`` statement, which can - be used with :meth:`.Engine.begin`:: + be used with :meth:`_engine.Engine.begin`:: with engine.begin() as conn: conn.execute(text("some statement"), {'x':5, 'y':10}) .. seealso:: - :meth:`.Engine.begin` - engine-level transactional + :meth:`_engine.Engine.begin` - engine-level transactional context - :meth:`.Connection.transaction` - connection-level version of - :meth:`.Engine.transaction` + :meth:`_engine.Connection.transaction` + - connection-level version of + :meth:`_engine.Engine.transaction` """ kwargs["_sa_skip_warning"] = True @@ -2261,20 +2300,21 @@ class Engine(Connectable, log.Identified): @util.deprecated( "1.4", - "The :meth:`.Engine.run_callable` method is deprecated and will be " - "removed in a future release. Use the :meth:`.Engine.connect` " + "The :meth:`_engine.Engine.run_callable` " + "method is deprecated and will be " + "removed in a future release. Use the :meth:`_engine.Engine.connect` " "context manager instead.", ) def run_callable(self, callable_, *args, **kwargs): r"""Given a callable object or function, execute it, passing - a :class:`.Connection` as the first argument. + a :class:`_engine.Connection` as the first argument. The given \*args and \**kwargs are passed subsequent - to the :class:`.Connection` argument. + to the :class:`_engine.Connection` argument. - This function, along with :meth:`.Connection.run_callable`, - allows a function to be run with a :class:`.Connection` - or :class:`.Engine` object without the need to know + This function, along with :meth:`_engine.Connection.run_callable`, + allows a function to be run with a :class:`_engine.Connection` + or :class:`_engine.Engine` object without the need to know which one is being dealt with. """ @@ -2287,9 +2327,10 @@ class Engine(Connectable, log.Identified): conn._run_ddl_visitor(visitorcallable, element, **kwargs) @util.deprecated_20( - ":meth:`.Engine.execute`", + ":meth:`_engine.Engine.execute`", alternative="All statement execution in SQLAlchemy 2.0 is performed " - "by the :meth:`.Connection.execute` method of :class:`.Connection`, " + "by the :meth:`_engine.Connection.execute` method of " + ":class:`_engine.Connection`, " "or in the ORM by the :meth:`.Session.execute` method of " ":class:`.Session`.", ) @@ -2297,13 +2338,14 @@ class Engine(Connectable, log.Identified): """Executes the given construct and returns a :class:`.ResultProxy`. The arguments are the same as those used by - :meth:`.Connection.execute`. + :meth:`_engine.Connection.execute`. - Here, a :class:`.Connection` is acquired using the - :meth:`~.Engine.connect` method, and the statement executed + 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 - underlying cursor is closed, the :class:`.Connection` created here + underlying cursor is closed, the :class:`_engine.Connection` + created here will also be closed, which allows its associated DBAPI connection resource to be returned to the connection pool. @@ -2312,9 +2354,10 @@ class Engine(Connectable, log.Identified): return connection.execute(statement, *multiparams, **params) @util.deprecated_20( - ":meth:`.Engine.scalar`", + ":meth:`_engine.Engine.scalar`", alternative="All statement execution in SQLAlchemy 2.0 is performed " - "by the :meth:`.Connection.execute` method of :class:`.Connection`, " + "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 " "used to return a scalar result.", @@ -2335,16 +2378,17 @@ class Engine(Connectable, log.Identified): return connection._execute_compiled(compiled, multiparams, params) def connect(self, close_with_result=False): - """Return a new :class:`.Connection` object. + """Return a new :class:`_engine.Connection` object. - The :class:`.Connection` object is a facade that uses a DBAPI + The :class:`_engine.Connection` object is a facade that uses a DBAPI connection internally in order to communicate with the database. This - connection is procured from the connection-holding :class:`.Pool` - referenced by this :class:`.Engine`. When the - :meth:`~.Connection.close` method of the :class:`.Connection` object + connection is procured from the connection-holding :class:`_pool.Pool` + referenced by this :class:`_engine.Engine`. When the + :meth:`_engine.Connection.close` method of the + :class:`_engine.Connection` object is called, the underlying DBAPI connection is then returned to the connection pool, where it may be used again in a subsequent call to - :meth:`~.Engine.connect`. + :meth:`_engine.Engine.connect`. """ @@ -2352,9 +2396,10 @@ class Engine(Connectable, log.Identified): @util.deprecated( "1.4", - "The :meth:`.Engine.table_names` method is deprecated and will be " + "The :meth:`_engine.Engine.table_names` " + "method is deprecated and will be " "removed in a future release. Please refer to " - ":meth:`.Inspector.get_table_names`.", + ":meth:`_reflection.Inspector.get_table_names`.", ) def table_names(self, schema=None, connection=None): """Return a list of all table names available in the database. @@ -2369,9 +2414,10 @@ class Engine(Connectable, log.Identified): @util.deprecated( "1.4", - "The :meth:`.Engine.has_table` method is deprecated and will be " + "The :meth:`_engine.Engine.has_table` " + "method is deprecated and will be " "removed in a future release. Please refer to " - ":meth:`.Inspector.has_table`.", + ":meth:`_reflection.Inspector.has_table`.", ) def has_table(self, table_name, schema=None): """Return True if the given backend has a table of the given name. @@ -2379,7 +2425,7 @@ class Engine(Connectable, log.Identified): .. seealso:: :ref:`metadata_reflection_inspector` - detailed schema inspection - using the :class:`.Inspector` interface. + using the :class:`_reflection.Inspector` interface. :class:`.quoted_name` - used to pass quoting information along with a schema identifier. @@ -2414,10 +2460,11 @@ class Engine(Connectable, log.Identified): for real. This method provides direct DBAPI connection access for - special situations when the API provided by :class:`.Connection` - is not needed. When a :class:`.Connection` object is already + special situations when the API provided by + :class:`_engine.Connection` + is not needed. When a :class:`_engine.Connection` object is already present, the DBAPI connection is available using - the :attr:`.Connection.connection` accessor. + the :attr:`_engine.Connection.connection` accessor. .. seealso:: diff --git a/lib/sqlalchemy/engine/create.py b/lib/sqlalchemy/engine/create.py index 2831f5e7d..3c1345c63 100644 --- a/lib/sqlalchemy/engine/create.py +++ b/lib/sqlalchemy/engine/create.py @@ -43,7 +43,7 @@ from ..sql import compiler ), ) def create_engine(url, **kwargs): - """Create a new :class:`.Engine` instance. + """Create a new :class:`_engine.Engine` instance. The standard calling form is to send the URL as the first positional argument, usually a string @@ -53,8 +53,8 @@ def create_engine(url, **kwargs): engine = create_engine("postgresql://scott:tiger@localhost/test") Additional keyword arguments may then follow it which - establish various options on the resulting :class:`.Engine` - and its underlying :class:`.Dialect` and :class:`.Pool` + establish various options on the resulting :class:`_engine.Engine` + and its underlying :class:`.Dialect` and :class:`_pool.Pool` constructs:: engine = create_engine("mysql://scott:tiger@hostname/dbname", @@ -69,15 +69,17 @@ def create_engine(url, **kwargs): ``**kwargs`` takes a wide variety of options which are routed towards their appropriate components. Arguments may be specific to - the :class:`.Engine`, the underlying :class:`.Dialect`, as well as the - :class:`.Pool`. Specific dialects also accept keyword arguments that + the :class:`_engine.Engine`, the underlying :class:`.Dialect`, + 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. - Once established, the newly resulting :class:`.Engine` will - request a connection from the underlying :class:`.Pool` once - :meth:`.Engine.connect` is called, or a method which depends on it - such as :meth:`.Engine.execute` is invoked. The :class:`.Pool` in turn + Once established, the newly resulting :class:`_engine.Engine` will + request a connection from the underlying :class:`_pool.Pool` once + :meth:`_engine.Engine.connect` is called, or a method which depends on it + 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** establish any actual DBAPI connections directly. @@ -233,16 +235,17 @@ def create_engine(url, **kwargs): individual dialects should be consulted directly. Note that the isolation level can also be set on a - per-:class:`.Connection` basis as well, using the + per-:class:`_engine.Connection` basis as well, using the :paramref:`.Connection.execution_options.isolation_level` feature. .. seealso:: - :attr:`.Connection.default_isolation_level` - view default level + :attr:`_engine.Connection.default_isolation_level` + - view default level :paramref:`.Connection.execution_options.isolation_level` - - set per :class:`.Connection` isolation level + - set per :class:`_engine.Connection` isolation level :ref:`SQLite Transaction Isolation <sqlite_isolation_level>` @@ -252,7 +255,8 @@ def create_engine(url, **kwargs): :ref:`session_transaction_isolation` - for the ORM - :param json_deserializer: for dialects that support the :class:`.JSON` + :param json_deserializer: for dialects that support the + :class:`_types.JSON` datatype, this is a Python callable that will convert a JSON string to a Python object. By default, the Python ``json.loads`` function is used. @@ -260,7 +264,7 @@ def create_engine(url, **kwargs): .. versionchanged:: 1.3.7 The SQLite dialect renamed this from ``_json_deserializer``. - :param json_serializer: for dialects that support the :class:`.JSON` + :param json_serializer: for dialects that support the :class:`_types.JSON` datatype, this is a Python callable that will render a given object as JSON. By default, the Python ``json.dumps`` function is used. @@ -317,7 +321,7 @@ def create_engine(url, **kwargs): specific DBAPI which will be imported before first connect. This parameter causes the import to be bypassed, and the given module to be used instead. Can be used for testing of DBAPIs as well as to - inject "mock" DBAPI implementations into the :class:`.Engine`. + inject "mock" DBAPI implementations into the :class:`_engine.Engine`. :param paramstyle=None: The `paramstyle <http://legacy.python.org/dev/peps/pep-0249/#paramstyle>`_ to use when rendering bound parameters. This style defaults to the @@ -382,13 +386,13 @@ def create_engine(url, **kwargs): :ref:`pool_setting_recycle` :param pool_reset_on_return='rollback': set the - :paramref:`.Pool.reset_on_return` parameter of the underlying - :class:`.Pool` object, which can be set to the values + :paramref:`_pool.Pool.reset_on_return` parameter of the underlying + :class:`_pool.Pool` object, which can be set to the values ``"rollback"``, ``"commit"``, or ``None``. .. seealso:: - :paramref:`.Pool.reset_on_return` + :paramref:`_pool.Pool.reset_on_return` :param pool_timeout=30: number of seconds to wait before giving up on getting a connection from the pool. This is only used diff --git a/lib/sqlalchemy/engine/default.py b/lib/sqlalchemy/engine/default.py index 43ebce83a..5b8cb635c 100644 --- a/lib/sqlalchemy/engine/default.py +++ b/lib/sqlalchemy/engine/default.py @@ -446,7 +446,7 @@ class DefaultDialect(interfaces.Dialect): This method looks for a dictionary called ``colspecs`` as a class or instance-level variable, - and passes on to :func:`.types.adapt_type`. + and passes on to :func:`_types.adapt_type`. """ return sqltypes.adapt_type(typeobj, self.colspecs) @@ -1446,12 +1446,13 @@ class DefaultExecutionContext(interfaces.ExecutionContext): generation function, e.g. as described at :ref:`context_default_functions`. It consists of a dictionary which includes entries for each column/value pair that is to be part of the INSERT or UPDATE statement. The keys of the - dictionary will be the key value of each :class:`.Column`, which is usually + dictionary will be the key value of each :class:`_schema.Column`, + which is usually synonymous with the name. Note that the :attr:`.DefaultExecutionContext.current_parameters` attribute does not accommodate for the "multi-values" feature of the - :meth:`.Insert.values` method. The + :meth:`_expression.Insert.values` method. The :meth:`.DefaultExecutionContext.get_current_parameters` method should be preferred. @@ -1471,11 +1472,13 @@ class DefaultExecutionContext(interfaces.ExecutionContext): :ref:`context_default_functions`. When invoked, a dictionary is returned which includes entries for each column/value pair that is part of the INSERT or UPDATE statement. The keys of the dictionary will be - the key value of each :class:`.Column`, which is usually synonymous + the key value of each :class:`_schema.Column`, + which is usually synonymous with the name. :param isolate_multiinsert_groups=True: indicates that multi-valued - INSERT constructs created using :meth:`.Insert.values` should be + INSERT constructs created using :meth:`_expression.Insert.values` + should be handled by returning only the subset of parameters that are local to the current column default invocation. When ``False``, the raw parameters of the statement are returned including the diff --git a/lib/sqlalchemy/engine/events.py b/lib/sqlalchemy/engine/events.py index 32292c826..46459cf73 100644 --- a/lib/sqlalchemy/engine/events.py +++ b/lib/sqlalchemy/engine/events.py @@ -15,13 +15,13 @@ from .. import exc class ConnectionEvents(event.Events): """Available events for :class:`.Connectable`, which includes - :class:`.Connection` and :class:`.Engine`. + :class:`_engine.Connection` and :class:`_engine.Engine`. The methods here define the name of an event as well as the names of members that are passed to listener functions. An event listener can be associated with any :class:`.Connectable` - class or instance, such as an :class:`.Engine`, e.g.:: + class or instance, such as an :class:`_engine.Engine`, e.g.:: from sqlalchemy import event, create_engine @@ -32,7 +32,7 @@ class ConnectionEvents(event.Events): engine = create_engine('postgresql://scott:tiger@localhost/test') event.listen(engine, "before_cursor_execute", before_cursor_execute) - or with a specific :class:`.Connection`:: + or with a specific :class:`_engine.Connection`:: with engine.begin() as conn: @event.listens_for(conn, 'before_cursor_execute') @@ -62,19 +62,23 @@ class ConnectionEvents(event.Events): return statement, parameters .. note:: :class:`.ConnectionEvents` can be established on any - combination of :class:`.Engine`, :class:`.Connection`, as well + combination of :class:`_engine.Engine`, :class:`_engine.Connection`, + as well as instances of each of those classes. Events across all four scopes will fire off for a given instance of - :class:`.Connection`. However, for performance reasons, the - :class:`.Connection` object determines at instantiation time - whether or not its parent :class:`.Engine` has event listeners - established. Event listeners added to the :class:`.Engine` - class or to an instance of :class:`.Engine` *after* the instantiation - of a dependent :class:`.Connection` instance will usually - *not* be available on that :class:`.Connection` instance. The newly - added listeners will instead take effect for :class:`.Connection` + :class:`_engine.Connection`. However, for performance reasons, the + :class:`_engine.Connection` object determines at instantiation time + whether or not its parent :class:`_engine.Engine` has event listeners + established. Event listeners added to the :class:`_engine.Engine` + class or to an instance of :class:`_engine.Engine` + *after* the instantiation + of a dependent :class:`_engine.Connection` instance will usually + *not* be available on that :class:`_engine.Connection` instance. + The newly + added listeners will instead take effect for + :class:`_engine.Connection` instances created subsequent to those event listeners being - established on the parent :class:`.Engine` class or instance. + established on the parent :class:`_engine.Engine` class or instance. :param retval=False: Applies to the :meth:`.before_execute` and :meth:`.before_cursor_execute` events only. When True, the @@ -156,9 +160,10 @@ class ConnectionEvents(event.Events): # do something with clauseelement, multiparams, params return clauseelement, multiparams, params - :param conn: :class:`.Connection` object + :param conn: :class:`_engine.Connection` object :param clauseelement: SQL expression construct, :class:`.Compiled` - instance, or string statement passed to :meth:`.Connection.execute`. + instance, or string statement passed to + :meth:`_engine.Connection.execute`. :param multiparams: Multiple parameter sets, a list of dictionaries. :param params: Single parameter set, a single dictionary. @@ -172,9 +177,10 @@ class ConnectionEvents(event.Events): """Intercept high level execute() events after execute. - :param conn: :class:`.Connection` object + :param conn: :class:`_engine.Connection` object :param clauseelement: SQL expression construct, :class:`.Compiled` - instance, or string statement passed to :meth:`.Connection.execute`. + instance, or string statement passed to + :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. @@ -204,7 +210,7 @@ class ConnectionEvents(event.Events): See the example at :class:`.ConnectionEvents`. - :param conn: :class:`.Connection` object + :param conn: :class:`_engine.Connection` object :param cursor: DBAPI cursor object :param statement: string SQL statement, as to be passed to the DBAPI :param parameters: Dictionary, tuple, or list of parameters being @@ -228,7 +234,7 @@ class ConnectionEvents(event.Events): ): """Intercept low-level cursor execute() events after execution. - :param conn: :class:`.Connection` object + :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`. @@ -244,7 +250,8 @@ class ConnectionEvents(event.Events): """ def handle_error(self, exception_context): - r"""Intercept all exceptions processed by the :class:`.Connection`. + r"""Intercept all exceptions processed by the + :class:`_engine.Connection`. This includes all exceptions emitted by the DBAPI as well as within SQLAlchemy's statement invocation process, including @@ -362,9 +369,9 @@ class ConnectionEvents(event.Events): ``False``. .. versionchanged:: 1.0.0 The :meth:`.handle_error` event is now - invoked when an :class:`.Engine` fails during the initial - call to :meth:`.Engine.connect`, as well as when a - :class:`.Connection` object encounters an error during a + invoked when an :class:`_engine.Engine` fails during the initial + call to :meth:`_engine.Engine.connect`, as well as when a + :class:`_engine.Connection` object encounters an error during a reconnect operation. .. versionchanged:: 1.0.0 The :meth:`.handle_error` event is @@ -380,32 +387,39 @@ class ConnectionEvents(event.Events): """ def engine_connect(self, conn, branch): - """Intercept the creation of a new :class:`.Connection`. + """Intercept the creation of a new :class:`_engine.Connection`. This event is called typically as the direct result of calling - the :meth:`.Engine.connect` method. + the :meth:`_engine.Engine.connect` method. - It differs from the :meth:`.PoolEvents.connect` method, which + It differs from the :meth:`_events.PoolEvents.connect` method, which refers to the actual connection to a database at the DBAPI level; a DBAPI connection may be pooled and reused for many operations. In contrast, this event refers only to the production of a higher level - :class:`.Connection` wrapper around such a DBAPI connection. + :class:`_engine.Connection` wrapper around such a DBAPI connection. - It also differs from the :meth:`.PoolEvents.checkout` event - in that it is specific to the :class:`.Connection` object, not the - DBAPI connection that :meth:`.PoolEvents.checkout` deals with, although + It also differs from the :meth:`_events.PoolEvents.checkout` event + in that it is specific to the :class:`_engine.Connection` object, + not the + DBAPI connection that :meth:`_events.PoolEvents.checkout` deals with, + although this DBAPI connection is available here via the - :attr:`.Connection.connection` attribute. But note there can in fact - be multiple :meth:`.PoolEvents.checkout` events within the lifespan - of a single :class:`.Connection` object, if that :class:`.Connection` + :attr:`_engine.Connection.connection` attribute. + But note there can in fact + be multiple :meth:`_events.PoolEvents.checkout` + events within the lifespan + of a single :class:`_engine.Connection` object, if that + :class:`_engine.Connection` is invalidated and re-established. There can also be multiple - :class:`.Connection` objects generated for the same already-checked-out - DBAPI connection, in the case that a "branch" of a :class:`.Connection` + :class:`_engine.Connection` + objects generated for the same already-checked-out + DBAPI connection, in the case that a "branch" of a + :class:`_engine.Connection` is produced. - :param conn: :class:`.Connection` object. + :param conn: :class:`_engine.Connection` object. :param branch: if True, this is a "branch" of an existing - :class:`.Connection`. A branch is generated within the course + :class:`_engine.Connection`. A branch is generated within the course of a statement execution to invoke supplemental statements, most typically to pre-execute a SELECT of a default value for the purposes of an INSERT statement. @@ -419,81 +433,91 @@ class ConnectionEvents(event.Events): to transparently ensure pooled connections are connected to the database. - :meth:`.PoolEvents.checkout` the lower-level pool checkout event + :meth:`_events.PoolEvents.checkout` + the lower-level pool checkout event for an individual DBAPI connection :meth:`.ConnectionEvents.set_connection_execution_options` - a copy - of a :class:`.Connection` is also made when the - :meth:`.Connection.execution_options` method is called. + of a :class:`_engine.Connection` is also made when the + :meth:`_engine.Connection.execution_options` method is called. """ def set_connection_execution_options(self, conn, opts): - """Intercept when the :meth:`.Connection.execution_options` + """Intercept when the :meth:`_engine.Connection.execution_options` method is called. - This method is called after the new :class:`.Connection` has been + This method is called after the new :class:`_engine.Connection` + has been produced, with the newly updated execution options collection, but before the :class:`.Dialect` has acted upon any of those new options. - Note that this method is not called when a new :class:`.Connection` + Note that this method is not called when a new + :class:`_engine.Connection` is produced which is inheriting execution options from its parent - :class:`.Engine`; to intercept this condition, use the + :class:`_engine.Engine`; to intercept this condition, use the :meth:`.ConnectionEvents.engine_connect` event. - :param conn: The newly copied :class:`.Connection` object + :param conn: The newly copied :class:`_engine.Connection` object :param opts: dictionary of options that were passed to the - :meth:`.Connection.execution_options` method. + :meth:`_engine.Connection.execution_options` method. .. versionadded:: 0.9.0 .. seealso:: :meth:`.ConnectionEvents.set_engine_execution_options` - event - which is called when :meth:`.Engine.execution_options` is called. + which is called when :meth:`_engine.Engine.execution_options` + is called. """ def set_engine_execution_options(self, engine, opts): - """Intercept when the :meth:`.Engine.execution_options` + """Intercept when the :meth:`_engine.Engine.execution_options` method is called. - The :meth:`.Engine.execution_options` method produces a shallow - copy of the :class:`.Engine` which stores the new options. That new - :class:`.Engine` is passed here. A particular application of this + The :meth:`_engine.Engine.execution_options` method produces a shallow + copy of the :class:`_engine.Engine` which stores the new options. + That new + :class:`_engine.Engine` is passed here. + A particular application of this method is to add a :meth:`.ConnectionEvents.engine_connect` event - handler to the given :class:`.Engine` which will perform some per- - :class:`.Connection` task specific to these execution options. + handler to the given :class:`_engine.Engine` + which will perform some per- + :class:`_engine.Connection` task specific to these execution options. - :param conn: The newly copied :class:`.Engine` object + :param conn: The newly copied :class:`_engine.Engine` object :param opts: dictionary of options that were passed to the - :meth:`.Connection.execution_options` method. + :meth:`_engine.Connection.execution_options` method. .. versionadded:: 0.9.0 .. seealso:: :meth:`.ConnectionEvents.set_connection_execution_options` - event - which is called when :meth:`.Connection.execution_options` is + which is called when :meth:`_engine.Connection.execution_options` + is called. """ def engine_disposed(self, engine): - """Intercept when the :meth:`.Engine.dispose` method is called. + """Intercept when the :meth:`_engine.Engine.dispose` method is called. - The :meth:`.Engine.dispose` method instructs the engine to - "dispose" of it's connection pool (e.g. :class:`.Pool`), and + The :meth:`_engine.Engine.dispose` method instructs the engine to + "dispose" of it's connection pool (e.g. :class:`_pool.Pool`), and replaces it with a new one. Disposing of the old pool has the effect that existing checked-in connections are closed. The new pool does not establish any new connections until it is first used. This event can be used to indicate that resources related to the - :class:`.Engine` should also be cleaned up, keeping in mind that the - :class:`.Engine` can still be used for new requests in which case + :class:`_engine.Engine` should also be cleaned up, + keeping in mind that the + :class:`_engine.Engine` + can still be used for new requests in which case it re-acquires connection resources. .. versionadded:: 1.0.5 @@ -503,7 +527,7 @@ class ConnectionEvents(event.Events): def begin(self, conn): """Intercept begin() events. - :param conn: :class:`.Connection` object + :param conn: :class:`_engine.Connection` object """ @@ -511,17 +535,17 @@ class ConnectionEvents(event.Events): """Intercept rollback() events, as initiated by a :class:`.Transaction`. - Note that the :class:`.Pool` also "auto-rolls back" + Note that the :class:`_pool.Pool` also "auto-rolls back" a DBAPI connection upon checkin, if the ``reset_on_return`` flag is set to its default value of ``'rollback'``. To intercept this - rollback, use the :meth:`.PoolEvents.reset` hook. + rollback, use the :meth:`_events.PoolEvents.reset` hook. - :param conn: :class:`.Connection` object + :param conn: :class:`_engine.Connection` object .. seealso:: - :meth:`.PoolEvents.reset` + :meth:`_events.PoolEvents.reset` """ @@ -529,18 +553,18 @@ class ConnectionEvents(event.Events): """Intercept commit() events, as initiated by a :class:`.Transaction`. - Note that the :class:`.Pool` may also "auto-commit" + Note that the :class:`_pool.Pool` may also "auto-commit" a DBAPI connection upon checkin, if the ``reset_on_return`` flag is set to the value ``'commit'``. To intercept this - commit, use the :meth:`.PoolEvents.reset` hook. + commit, use the :meth:`_events.PoolEvents.reset` hook. - :param conn: :class:`.Connection` object + :param conn: :class:`_engine.Connection` object """ def savepoint(self, conn, name): """Intercept savepoint() events. - :param conn: :class:`.Connection` object + :param conn: :class:`_engine.Connection` object :param name: specified name used for the savepoint. """ @@ -548,7 +572,7 @@ class ConnectionEvents(event.Events): def rollback_savepoint(self, conn, name, context): """Intercept rollback_savepoint() events. - :param conn: :class:`.Connection` object + :param conn: :class:`_engine.Connection` object :param name: specified name used for the savepoint. :param context: :class:`.ExecutionContext` in use. May be ``None``. @@ -557,7 +581,7 @@ class ConnectionEvents(event.Events): def release_savepoint(self, conn, name, context): """Intercept release_savepoint() events. - :param conn: :class:`.Connection` object + :param conn: :class:`_engine.Connection` object :param name: specified name used for the savepoint. :param context: :class:`.ExecutionContext` in use. May be ``None``. @@ -566,7 +590,7 @@ class ConnectionEvents(event.Events): def begin_twophase(self, conn, xid): """Intercept begin_twophase() events. - :param conn: :class:`.Connection` object + :param conn: :class:`_engine.Connection` object :param xid: two-phase XID identifier """ @@ -574,14 +598,14 @@ class ConnectionEvents(event.Events): def prepare_twophase(self, conn, xid): """Intercept prepare_twophase() events. - :param conn: :class:`.Connection` object + :param conn: :class:`_engine.Connection` object :param xid: two-phase XID identifier """ def rollback_twophase(self, conn, xid, is_prepared): """Intercept rollback_twophase() events. - :param conn: :class:`.Connection` object + :param conn: :class:`_engine.Connection` object :param xid: two-phase XID identifier :param is_prepared: boolean, indicates if :meth:`.TwoPhaseTransaction.prepare` was called. @@ -591,7 +615,7 @@ class ConnectionEvents(event.Events): def commit_twophase(self, conn, xid, is_prepared): """Intercept commit_twophase() events. - :param conn: :class:`.Connection` object + :param conn: :class:`_engine.Connection` object :param xid: two-phase XID identifier :param is_prepared: boolean, indicates if :meth:`.TwoPhaseTransaction.prepare` was called. diff --git a/lib/sqlalchemy/engine/interfaces.py b/lib/sqlalchemy/engine/interfaces.py index 6cf4d7dbd..224d4f693 100644 --- a/lib/sqlalchemy/engine/interfaces.py +++ b/lib/sqlalchemy/engine/interfaces.py @@ -185,7 +185,7 @@ class Dialect(object): """Transform a generic type to a dialect-specific type. Dialect classes will usually use the - :func:`.types.adapt_type` function in the types module to + :func:`_types.adapt_type` function in the types module to accomplish this. The returned result is cached *per dialect class* so can @@ -215,7 +215,7 @@ class Dialect(object): def get_columns(self, connection, table_name, schema=None, **kw): """Return information about columns in `table_name`. - Given a :class:`.Connection`, a string + Given a :class:`_engine.Connection`, a string `table_name`, and an optional string `schema`, return column information as a list of dictionaries with these keys: @@ -249,7 +249,7 @@ class Dialect(object): """Return information about the primary key constraint on table_name`. - Given a :class:`.Connection`, a string + Given a :class:`_engine.Connection`, a string `table_name`, and an optional string `schema`, return primary key information as a dictionary with these keys: @@ -265,7 +265,7 @@ class Dialect(object): def get_foreign_keys(self, connection, table_name, schema=None, **kw): """Return information about foreign_keys in `table_name`. - Given a :class:`.Connection`, a string + Given a :class:`_engine.Connection`, a string `table_name`, and an optional string `schema`, return foreign key information as a list of dicts with these keys: @@ -321,7 +321,7 @@ class Dialect(object): def get_view_definition(self, connection, view_name, schema=None, **kw): """Return view definition. - Given a :class:`.Connection`, a string + Given a :class:`_engine.Connection`, a string `view_name`, and an optional string `schema`, return the view definition. """ @@ -331,7 +331,7 @@ class Dialect(object): def get_indexes(self, connection, table_name, schema=None, **kw): """Return information about indexes in `table_name`. - Given a :class:`.Connection`, a string + Given a :class:`_engine.Connection`, a string `table_name` and an optional string `schema`, return index information as a list of dictionaries with these keys: @@ -434,7 +434,7 @@ class Dialect(object): def has_table(self, connection, table_name, schema=None, **kw): """Check the existence of a particular table in the database. - Given a :class:`.Connection` object and a string + Given a :class:`_engine.Connection` object and a string `table_name`, return True if the given table (possibly within the specified `schema`) exists in the database, False otherwise. @@ -445,7 +445,7 @@ class Dialect(object): def has_index(self, connection, table_name, index_name, schema=None): """Check the existence of a particular index name in the database. - Given a :class:`.Connection` object, a string + Given a :class:`_engine.Connection` object, a string `table_name` and stiring index name, return True if an index of the given name on the given table exists, false otherwise. @@ -463,7 +463,7 @@ class Dialect(object): def has_sequence(self, connection, sequence_name, schema=None, **kw): """Check the existence of a particular sequence in the database. - Given a :class:`.Connection` object and a string + Given a :class:`_engine.Connection` object and a string `sequence_name`, return True if the given sequence exists in the database, False otherwise. """ @@ -506,7 +506,8 @@ class Dialect(object): :meth:`.Dialect.do_autocommit` hook is provided for DBAPIs that need some extra commands emitted after a commit in order to enter the next transaction, when the - SQLAlchemy :class:`.Connection` is used in its default "autocommit" + SQLAlchemy :class:`_engine.Connection` + is used in its default "autocommit" mode. :param dbapi_connection: a DBAPI connection, typically @@ -542,7 +543,8 @@ class Dialect(object): """Provide an implementation of ``connection.close()``, given a DBAPI connection. - This hook is called by the :class:`.Pool` when a connection has been + This hook is called by the :class:`_pool.Pool` + when a connection has been detached from the pool, or is being returned beyond the normal capacity of the pool. @@ -563,7 +565,7 @@ class Dialect(object): def do_savepoint(self, connection, name): """Create a savepoint with the given name. - :param connection: a :class:`.Connection`. + :param connection: a :class:`_engine.Connection`. :param name: savepoint name. """ @@ -573,7 +575,7 @@ class Dialect(object): def do_rollback_to_savepoint(self, connection, name): """Rollback a connection to the named savepoint. - :param connection: a :class:`.Connection`. + :param connection: a :class:`_engine.Connection`. :param name: savepoint name. """ @@ -583,7 +585,7 @@ class Dialect(object): def do_release_savepoint(self, connection, name): """Release the named savepoint on a connection. - :param connection: a :class:`.Connection`. + :param connection: a :class:`_engine.Connection`. :param name: savepoint name. """ @@ -592,7 +594,7 @@ class Dialect(object): def do_begin_twophase(self, connection, xid): """Begin a two phase transaction on the given connection. - :param connection: a :class:`.Connection`. + :param connection: a :class:`_engine.Connection`. :param xid: xid """ @@ -602,7 +604,7 @@ class Dialect(object): def do_prepare_twophase(self, connection, xid): """Prepare a two phase transaction on the given connection. - :param connection: a :class:`.Connection`. + :param connection: a :class:`_engine.Connection`. :param xid: xid """ @@ -614,7 +616,7 @@ class Dialect(object): ): """Rollback a two phase transaction on the given connection. - :param connection: a :class:`.Connection`. + :param connection: a :class:`_engine.Connection`. :param xid: xid :param is_prepared: whether or not :meth:`.TwoPhaseTransaction.prepare` was called. @@ -630,7 +632,7 @@ class Dialect(object): """Commit a two phase transaction on the given connection. - :param connection: a :class:`.Connection`. + :param connection: a :class:`_engine.Connection`. :param xid: xid :param is_prepared: whether or not :meth:`.TwoPhaseTransaction.prepare` was called. @@ -644,7 +646,7 @@ class Dialect(object): """Recover list of uncommitted prepared two phase transaction identifiers on the given connection. - :param connection: a :class:`.Connection`. + :param connection: a :class:`_engine.Connection`. """ @@ -734,11 +736,13 @@ class Dialect(object): isolation modes, Unicode modes, etc. The "do_on_connect" callable is invoked by using the - :meth:`.PoolEvents.first_connect` and :meth:`.PoolEvents.connect` event + :meth:`_events.PoolEvents.first_connect` and + :meth:`_events.PoolEvents.connect` event hooks, then unwrapping the DBAPI connection and passing it into the callable. The reason it is invoked for both events is so that any dialect-level initialization that occurs upon first connection, which - also makes use of the :meth:`.PoolEvents.first_connect` method, will + also makes use of the :meth:`_events.PoolEvents.first_connect` method, + will proceed after this hook has been called. This currently means the hook is in fact called twice for the very first connection in which a dialect creates; and once per connection afterwards. @@ -760,22 +764,24 @@ class Dialect(object): """Given a DBAPI connection, revert its isolation to the default. Note that this is a dialect-level method which is used as part - of the implementation of the :class:`.Connection` and - :class:`.Engine` + of the implementation of the :class:`_engine.Connection` and + :class:`_engine.Engine` isolation level facilities; these APIs should be preferred for most typical use cases. .. seealso:: - :meth:`.Connection.get_isolation_level` - view current level + :meth:`_engine.Connection.get_isolation_level` + - view current level - :attr:`.Connection.default_isolation_level` - view default level + :attr:`_engine.Connection.default_isolation_level` + - view default level :paramref:`.Connection.execution_options.isolation_level` - - set per :class:`.Connection` isolation level + set per :class:`_engine.Connection` isolation level :paramref:`.create_engine.isolation_level` - - set per :class:`.Engine` isolation level + set per :class:`_engine.Engine` isolation level """ @@ -785,22 +791,24 @@ class Dialect(object): """Given a DBAPI connection, set its isolation level. Note that this is a dialect-level method which is used as part - of the implementation of the :class:`.Connection` and - :class:`.Engine` + of the implementation of the :class:`_engine.Connection` and + :class:`_engine.Engine` isolation level facilities; these APIs should be preferred for most typical use cases. .. seealso:: - :meth:`.Connection.get_isolation_level` - view current level + :meth:`_engine.Connection.get_isolation_level` + - view current level - :attr:`.Connection.default_isolation_level` - view default level + :attr:`_engine.Connection.default_isolation_level` + - view default level :paramref:`.Connection.execution_options.isolation_level` - - set per :class:`.Connection` isolation level + set per :class:`_engine.Connection` isolation level :paramref:`.create_engine.isolation_level` - - set per :class:`.Engine` isolation level + set per :class:`_engine.Engine` isolation level """ @@ -809,27 +817,30 @@ class Dialect(object): def get_isolation_level(self, dbapi_conn): """Given a DBAPI connection, return its isolation level. - When working with a :class:`.Connection` object, the corresponding + When working with a :class:`_engine.Connection` object, + the corresponding DBAPI connection may be procured using the - :attr:`.Connection.connection` accessor. + :attr:`_engine.Connection.connection` accessor. Note that this is a dialect-level method which is used as part - of the implementation of the :class:`.Connection` and - :class:`.Engine` isolation level facilities; + of the implementation of the :class:`_engine.Connection` and + :class:`_engine.Engine` isolation level facilities; these APIs should be preferred for most typical use cases. .. seealso:: - :meth:`.Connection.get_isolation_level` - view current level + :meth:`_engine.Connection.get_isolation_level` + - view current level - :attr:`.Connection.default_isolation_level` - view default level + :attr:`_engine.Connection.default_isolation_level` + - view default level :paramref:`.Connection.execution_options.isolation_level` - - set per :class:`.Connection` isolation level + set per :class:`_engine.Connection` isolation level :paramref:`.create_engine.isolation_level` - - set per :class:`.Engine` isolation level + set per :class:`_engine.Engine` isolation level """ @@ -883,7 +894,8 @@ class Dialect(object): @classmethod def engine_created(cls, engine): - """A convenience hook called before returning the final :class:`.Engine`. + """A convenience hook called before returning the final + :class:`_engine.Engine`. If the dialect returned a different class from the :meth:`.get_dialect_cls` @@ -903,7 +915,7 @@ class Dialect(object): class CreateEnginePlugin(object): """A set of hooks intended to augment the construction of an - :class:`.Engine` object based on entrypoint names in a URL. + :class:`_engine.Engine` object based on entrypoint names in a URL. The purpose of :class:`.CreateEnginePlugin` is to allow third-party systems to apply engine, pool and dialect level event listeners without @@ -979,7 +991,7 @@ class CreateEnginePlugin(object): arguments afterwards. When the engine creation process completes and produces the - :class:`.Engine` object, it is again passed to the plugin via the + :class:`_engine.Engine` object, it is again passed to the plugin via the :meth:`.CreateEnginePlugin.engine_created` hook. In this hook, additional changes can be made to the engine, most typically involving setup of events (e.g. those defined in :ref:`core_event_toplevel`). @@ -992,7 +1004,7 @@ 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` will be + to :func:`.create_engine`. A single :class:`_engine.Engine` will be passed to the :meth:`.CreateEnginePlugin.engine_created` method corresponding to this URL. @@ -1015,7 +1027,8 @@ class CreateEnginePlugin(object): """parse and modify pool kwargs""" def engine_created(self, engine): - """Receive the :class:`.Engine` object when it is fully constructed. + """Receive the :class:`_engine.Engine` + object when it is fully constructed. The plugin may make additional changes to the engine, such as registering engine or connection pool events. @@ -1246,9 +1259,9 @@ class ExecutionContext(object): @util.deprecated_20_cls( ":class:`.Connectable`", alternative=( - "The :class:`.Engine` will be the only Core " + "The :class:`_engine.Engine` will be the only Core " "object that features a .connect() method, and the " - ":class:`.Connection` will be the only object that features " + ":class:`_engine.Connection` will be the only object that features " "an .execute() method." ), constructor=None, @@ -1257,7 +1270,7 @@ class Connectable(object): """Interface for an object which supports execution of SQL constructs. The two implementations of :class:`.Connectable` are - :class:`.Connection` and :class:`.Engine`. + :class:`_engine.Connection` and :class:`_engine.Engine`. Connectable must also implement the 'dialect' member which references a :class:`.Dialect` instance. @@ -1265,19 +1278,20 @@ class Connectable(object): """ def connect(self, **kwargs): - """Return a :class:`.Connection` object. + """Return a :class:`_engine.Connection` object. Depending on context, this may be ``self`` if this object - is already an instance of :class:`.Connection`, or a newly - procured :class:`.Connection` if this object is an instance - of :class:`.Engine`. + is already an instance of :class:`_engine.Connection`, or a newly + procured :class:`_engine.Connection` if this object is an instance + of :class:`_engine.Engine`. """ engine = None - """The :class:`.Engine` instance referred to by this :class:`.Connectable`. + """The :class:`_engine.Engine` instance referred to by this + :class:`.Connectable`. - May be ``self`` if this is already an :class:`.Engine`. + May be ``self`` if this is already an :class:`_engine.Engine`. """ @@ -1311,7 +1325,7 @@ class ExceptionContext(object): """ connection = None - """The :class:`.Connection` in use during the exception. + """The :class:`_engine.Connection` in use during the exception. This member is present, except in the case of a failure when first connecting. @@ -1324,7 +1338,7 @@ class ExceptionContext(object): """ engine = None - """The :class:`.Engine` in use during the exception. + """The :class:`_engine.Engine` in use during the exception. This member should always be present, even in the case of a failure when first connecting. diff --git a/lib/sqlalchemy/engine/mock.py b/lib/sqlalchemy/engine/mock.py index bda9e91b5..19a3b8e6c 100644 --- a/lib/sqlalchemy/engine/mock.py +++ b/lib/sqlalchemy/engine/mock.py @@ -62,7 +62,8 @@ def create_mock_engine(url, executor, **kw): """Create a "mock" engine used for echoing DDL. This is a utility function used for debugging or storing the output of DDL - sequences as generated by :meth:`.MetaData.create_all` and related methods. + sequences as generated by :meth:`_schema.MetaData.create_all` + and related methods. The function accepts a URL which is used only to determine the kind of dialect to be used, as well as an "executor" callable function which diff --git a/lib/sqlalchemy/engine/reflection.py b/lib/sqlalchemy/engine/reflection.py index 1a34e9c72..344d5511d 100644 --- a/lib/sqlalchemy/engine/reflection.py +++ b/lib/sqlalchemy/engine/reflection.py @@ -66,38 +66,43 @@ class Inspector(object): consistent interface as well as caching support for previously fetched metadata. - A :class:`.Inspector` object is usually created via the - :func:`.inspect` function, which may be passed an :class:`.Engine` - or a :class:`.Connection`:: + A :class:`_reflection.Inspector` object is usually created via the + :func:`_sa.inspect` function, which may be passed an + :class:`_engine.Engine` + or a :class:`_engine.Connection`:: from sqlalchemy import inspect, create_engine engine = create_engine('...') insp = inspect(engine) Where above, the :class:`~sqlalchemy.engine.interfaces.Dialect` associated - with the engine may opt to return an :class:`.Inspector` subclass that + with the engine may opt to return an :class:`_reflection.Inspector` + subclass that provides additional methods specific to the dialect's target database. """ @util.deprecated( "1.4", - "The __init__() method on :class:`.Inspector` is deprecated and " + "The __init__() method on :class:`_reflection.Inspector` " + "is deprecated and " "will be removed in a future release. Please use the " ":func:`.sqlalchemy.inspect` " - "function on an :class:`.Engine` or :class:`.Connection` in order to " - "acquire an :class:`.Inspector`.", + "function on an :class:`_engine.Engine` or " + ":class:`_engine.Connection` " + "in order to " + "acquire an :class:`_reflection.Inspector`.", ) def __init__(self, bind): - """Initialize a new :class:`.Inspector`. + """Initialize a new :class:`_reflection.Inspector`. :param bind: a :class:`~sqlalchemy.engine.Connectable`, which is typically an instance of :class:`~sqlalchemy.engine.Engine` or :class:`~sqlalchemy.engine.Connection`. - For a dialect-specific instance of :class:`.Inspector`, see - :meth:`.Inspector.from_engine` + For a dialect-specific instance of :class:`_reflection.Inspector`, see + :meth:`_reflection.Inspector.from_engine` """ return self._init_legacy(bind) @@ -135,11 +140,14 @@ class Inspector(object): @classmethod @util.deprecated( "1.4", - "The from_engine() method on :class:`.Inspector` is deprecated and " + "The from_engine() method on :class:`_reflection.Inspector` " + "is deprecated and " "will be removed in a future release. Please use the " ":func:`.sqlalchemy.inspect` " - "function on an :class:`.Engine` or :class:`.Connection` in order to " - "acquire an :class:`.Inspector`.", + "function on an :class:`_engine.Engine` or " + ":class:`_engine.Connection` " + "in order to " + "acquire an :class:`_reflection.Inspector`.", ) def from_engine(cls, bind): """Construct a new dialect-specific Inspector object from the given @@ -151,12 +159,13 @@ class Inspector(object): :class:`~sqlalchemy.engine.Connection`. This method differs from direct a direct constructor call of - :class:`.Inspector` in that the + :class:`_reflection.Inspector` in that the :class:`~sqlalchemy.engine.interfaces.Dialect` is given a chance to - provide a dialect-specific :class:`.Inspector` instance, which may + provide a dialect-specific :class:`_reflection.Inspector` instance, + which may provide additional methods. - See the example at :class:`.Inspector`. + See the example at :class:`_reflection.Inspector`. """ return cls._construct(cls._init_legacy, bind) @@ -182,7 +191,8 @@ class Inspector(object): transaction. This essentially allows connect()/close() to be called if we detected - that we're against an :class:`.Engine` and not a :class:`.Connection`. + that we're against an :class:`_engine.Engine` and not a + :class:`_engine.Connection`. """ if self._op_context_requires_connect: @@ -197,7 +207,8 @@ class Inspector(object): @contextlib.contextmanager def _inspection_context(self): - """Return an :class:`.Inspector` from this one that will run all + """Return an :class:`_reflection.Inspector` + from this one that will run all operations on a single connection. """ @@ -233,7 +244,8 @@ class Inspector(object): """Return all table names in referred to within a particular schema. The names are expected to be real tables only, not views. - Views are instead returned using the :meth:`.Inspector.get_view_names` + Views are instead returned using the + :meth:`_reflection.Inspector.get_view_names` method. @@ -250,9 +262,9 @@ class Inspector(object): .. seealso:: - :meth:`.Inspector.get_sorted_table_and_fkc_names` + :meth:`_reflection.Inspector.get_sorted_table_and_fkc_names` - :attr:`.MetaData.sorted_tables` + :attr:`_schema.MetaData.sorted_tables` """ @@ -289,10 +301,10 @@ class Inspector(object): .. seealso:: - :meth:`.Inspector.get_table_names` + :meth:`_reflection.Inspector.get_table_names` :func:`.sort_tables_and_constraints` - similar method which works - with an already-given :class:`.MetaData`. + with an already-given :class:`_schema.MetaData`. """ @@ -646,9 +658,10 @@ class Inspector(object): ) @util.deprecated_20( - ":meth:`.Inspector.reflecttable`", - "The :meth:`.Inspector.reflecttable` method was renamed to " - ":meth:`.Inspector.reflect_table`. This deprecated alias " + ":meth:`_reflection.Inspector.reflecttable`", + "The :meth:`_reflection.Inspector.reflecttable` " + "method was renamed to " + ":meth:`_reflection.Inspector.reflect_table`. This deprecated alias " "will be removed in a future release.", ) def reflecttable(self, *args, **kwargs): diff --git a/lib/sqlalchemy/engine/result.py b/lib/sqlalchemy/engine/result.py index be44f67e7..6944e0c67 100644 --- a/lib/sqlalchemy/engine/result.py +++ b/lib/sqlalchemy/engine/result.py @@ -327,7 +327,8 @@ class CursorResultMetaData(ResultMetaData): The remaining fairly common case is that of the textual SQL that includes at least partial column information; this is when - we use a :class:`.TextualSelect` construct. This construct may have + we use a :class:`_expression.TextualSelect` construct. + This construct may have unordered or ordered column information. In the ordered case, we merge the cursor.description and the compiled construct's information positionally, and warn if there are additional description names @@ -350,7 +351,8 @@ class CursorResultMetaData(ResultMetaData): SQLAlchemy for all cases up through te 0.9 series. Positional matching for compiled SQL expressions was introduced in 1.0 as a major performance feature, and positional matching for textual - :class:`.TextualSelect` objects in 1.1. As name matching is no longer + :class:`_expression.TextualSelect` objects in 1.1. + As name matching is no longer a common case, it was acceptable to factor it into smaller generator- oriented methods that are easier to understand, but incur slightly more performance overhead. @@ -1245,14 +1247,14 @@ class BaseResult(object): corresponding to the list of primary key columns in the target table. - This only applies to single row :func:`~.sql.expression.insert` + This only applies to single row :func:`_expression.insert` constructs which did not explicitly specify - :meth:`.Insert.returning`. + :meth:`_expression.Insert.returning`. Note that primary key columns which specify a server_default clause, or otherwise do not qualify as "autoincrement" - columns (see the notes at :class:`.Column`), and were + columns (see the notes at :class:`_schema.Column`), and were generated using the database-side default, will appear in this list as ``None`` unless the backend supports "returning" and the insert statement executed @@ -1504,7 +1506,7 @@ class BaseResult(object): def is_insert(self): """True if this :class:`.ResultProxy` is the result of a executing an expression language compiled - :func:`.expression.insert` construct. + :func:`_expression.insert` construct. When True, this implies that the :attr:`inserted_primary_key` attribute is accessible, @@ -1562,7 +1564,8 @@ class ResultProxy(BaseResult): In the case of a result that is the product of :ref:`connectionless execution <dbengine_implicit>`, - the underlying :class:`.Connection` object is also closed, which + the underlying :class:`_engine.Connection` object is also closed, + which :term:`releases` DBAPI connection resources. .. deprecated:: 2.0 "connectionless" execution is deprecated and will |