diff options
Diffstat (limited to 'lib/sqlalchemy/pool/base.py')
| -rw-r--r-- | lib/sqlalchemy/pool/base.py | 43 |
1 files changed, 24 insertions, 19 deletions
diff --git a/lib/sqlalchemy/pool/base.py b/lib/sqlalchemy/pool/base.py index 17d5ba15f..7da6e2c4a 100644 --- a/lib/sqlalchemy/pool/base.py +++ b/lib/sqlalchemy/pool/base.py @@ -31,8 +31,8 @@ class _ConnDialect(object): """partial implementation of :class:`.Dialect` which provides DBAPI connection methods. - When a :class:`.Pool` is combined with an :class:`.Engine`, - the :class:`.Engine` replaces this with its own + When a :class:`_pool.Pool` is combined with an :class:`_engine.Engine`, + the :class:`_engine.Engine` replaces this with its own :class:`.Dialect`. """ @@ -94,7 +94,7 @@ class Pool(log.Identified): which defaults to ``sys.stdout`` for output.. If set to the string ``"debug"``, the logging will include pool checkouts and checkins. - The :paramref:`.Pool.echo` parameter can also be set from the + The :paramref:`_pool.Pool.echo` parameter can also be set from the :func:`.create_engine` call by using the :paramref:`.create_engine.echo_pool` parameter. @@ -151,7 +151,7 @@ class Pool(log.Identified): as it is handled by the engine creation strategy. .. versionadded:: 1.1 - ``dialect`` is now a public parameter - to the :class:`.Pool`. + to the :class:`_pool.Pool`. :param pre_ping: if True, the pool will emit a "ping" (typically "SELECT 1", but is dialect-specific) on the connection @@ -264,11 +264,11 @@ class Pool(log.Identified): connection.invalidate(exception) def recreate(self): - """Return a new :class:`.Pool`, of the same class as this one + """Return a new :class:`_pool.Pool`, of the same class as this one and configured with identical creation arguments. This method is used in conjunction with :meth:`dispose` - to close out an entire :class:`.Pool` and create a new one in + to close out an entire :class:`_pool.Pool` and create a new one in its place. """ @@ -301,7 +301,7 @@ class Pool(log.Identified): return _ConnectionFairy._checkout(self) def _return_conn(self, record): - """Given a _ConnectionRecord, return it to the :class:`.Pool`. + """Given a _ConnectionRecord, return it to the :class:`_pool.Pool`. This method is called when an instrumented DBAPI connection has its ``close()`` method called. @@ -326,7 +326,7 @@ class Pool(log.Identified): class _ConnectionRecord(object): """Internal object which maintains an individual DBAPI connection - referenced by a :class:`.Pool`. + referenced by a :class:`_pool.Pool`. The :class:`._ConnectionRecord` object always exists for any particular DBAPI connection whether or not that DBAPI connection has been @@ -340,12 +340,14 @@ class _ConnectionRecord(object): method is called, the DBAPI connection associated with this :class:`._ConnectionRecord` will be discarded, but the :class:`._ConnectionRecord` may be used again, - in which case a new DBAPI connection is produced when the :class:`.Pool` + in which case a new DBAPI connection is produced when the + :class:`_pool.Pool` next uses this record. The :class:`._ConnectionRecord` is delivered along with connection - pool events, including :meth:`.PoolEvents.connect` and - :meth:`.PoolEvents.checkout`, however :class:`._ConnectionRecord` still + pool events, including :meth:`_events.PoolEvents.connect` and + :meth:`_events.PoolEvents.checkout`, however :class:`._ConnectionRecord` + still remains an internal object whose API and internals may change. .. seealso:: @@ -382,7 +384,7 @@ class _ConnectionRecord(object): """The ``.info`` dictionary associated with the DBAPI connection. This dictionary is shared among the :attr:`._ConnectionFairy.info` - and :attr:`.Connection.info` accessors. + and :attr:`_engine.Connection.info` accessors. .. note:: @@ -468,7 +470,8 @@ class _ConnectionRecord(object): This method is called for all connection invalidations, including when the :meth:`._ConnectionFairy.invalidate` or - :meth:`.Connection.invalidate` methods are called, as well as when any + :meth:`_engine.Connection.invalidate` methods are called, + as well as when any so-called "automatic invalidation" condition occurs. :param e: an exception object indicating a reason for the invalidation. @@ -639,9 +642,9 @@ class _ConnectionFairy(object): """Proxies a DBAPI connection and provides return-on-dereference support. - This is an internal object used by the :class:`.Pool` implementation + This is an internal object used by the :class:`_pool.Pool` implementation to provide context management to a DBAPI connection delivered by - that :class:`.Pool`. + that :class:`_pool.Pool`. The name "fairy" is inspired by the fact that the :class:`._ConnectionFairy` object's lifespan is transitory, as it lasts @@ -677,10 +680,11 @@ class _ConnectionFairy(object): rather than directly against the dialect-level do_rollback() and do_commit() methods. - In practice, a :class:`.Connection` assigns a :class:`.Transaction` object + In practice, a :class:`_engine.Connection` assigns a :class:`.Transaction` + object to this variable when one is in scope so that the :class:`.Transaction` takes the job of committing or rolling back on return if - :meth:`.Connection.close` is called while the :class:`.Transaction` + :meth:`_engine.Connection.close` is called while the :class:`.Transaction` still exists. This is essentially an "event handler" of sorts but is simplified as an @@ -838,7 +842,8 @@ class _ConnectionFairy(object): 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:`._ConnectionFairy`. It is shared - with the :attr:`._ConnectionRecord.info` and :attr:`.Connection.info` + with the :attr:`._ConnectionRecord.info` and + :attr:`_engine.Connection.info` accessors. The dictionary associated with a particular DBAPI connection is @@ -869,7 +874,7 @@ class _ConnectionFairy(object): """Mark this connection as invalidated. This method can be called directly, and is also called as a result - of the :meth:`.Connection.invalidate` method. When invoked, + of the :meth:`_engine.Connection.invalidate` method. When invoked, the DBAPI connection is immediately closed and discarded from further use by the pool. The invalidation mechanism proceeds via the :meth:`._ConnectionRecord.invalidate` internal method. |