diff options
Diffstat (limited to 'lib/sqlalchemy/engine/base.py')
| -rw-r--r-- | lib/sqlalchemy/engine/base.py | 393 |
1 files changed, 220 insertions, 173 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:: |