diff options
Diffstat (limited to 'lib/sqlalchemy/engine/base.py')
| -rw-r--r-- | lib/sqlalchemy/engine/base.py | 104 |
1 files changed, 87 insertions, 17 deletions
diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py index a02e90aba..6c81f8b74 100644 --- a/lib/sqlalchemy/engine/base.py +++ b/lib/sqlalchemy/engine/base.py @@ -797,11 +797,22 @@ class Connectable(object): class Connection(Connectable): """Provides high-level functionality for a wrapped DB-API connection. - Provides execution support for string-based SQL statements as well - as ClauseElement, Compiled and DefaultGenerator objects. Provides - a :meth:`begin` method to return Transaction objects. - - The Connection object is **not** thread-safe. + Provides execution support for string-based SQL statements as well as + :class:`.ClauseElement`, :class:`.Compiled` and :class:`.DefaultGenerator` + objects. Provides a :meth:`begin` method to return :class:`.Transaction` + objects. + + The Connection object is **not** thread-safe. While a Connection can be + shared among threads using properly synchronized access, it is still + possible that the underlying DBAPI connection may not support shared + access between threads. Check the DBAPI documentation for details. + + The Connection object represents a single dbapi connection checked out + from the connection pool. In this state, the connection pool has no affect + upon the connection, including its expiration or timeout state. For the + connection pool to properly manage connections, connections should be + returned to the connection pool (i.e. ``connection.close()``) whenever the + connection is not in use. .. index:: single: thread safety; Connection @@ -812,9 +823,9 @@ class Connection(Connectable): _branch=False, _execution_options=None): """Construct a new Connection. - Connection objects are typically constructed by an - :class:`~sqlalchemy.engine.Engine`, see the ``connect()`` and - ``contextual_connect()`` methods of Engine. + The constructor here is not public and is only called only by an + :class:`.Engine`. See :meth:`.Engine.connect` and + :meth:`.Engine.contextual_connect` methods. """ self.engine = engine @@ -1154,7 +1165,22 @@ class Connection(Connectable): return self.execute(object, *multiparams, **params).scalar() def execute(self, object, *multiparams, **params): - """Executes and returns a ResultProxy.""" + """Executes the given construct and returns a :class:`.ResultProxy`. + + The construct can be one of: + + * a textual SQL string + * any :class:`.ClauseElement` construct that is also + a subclass of :class:`.Executable`, such as a + :func:`.select` construct + * a :class:`.FunctionElement`, such as that generated + by :attr:`.func`, will be automatically wrapped in + a SELECT statement, which is then executed. + * a :class:`.DDLElement` object + * a :class:`.DefaultGenerator` object + * a :class:`.Compiled` object + + """ for c in type(object).__mro__: if c in Connection.executors: @@ -1451,6 +1477,12 @@ class Connection(Connectable): class Transaction(object): """Represent a Transaction in progress. + The object provides :meth:`.rollback` and :meth:`.commit` + 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. + The Transaction object is **not** threadsafe. .. index:: @@ -1458,12 +1490,17 @@ class Transaction(object): """ def __init__(self, connection, parent): + """The constructor for :class:`.Transaction` is private + and is called from within the :class:`.Connection.begin` + implementation. + + """ self.connection = connection self._parent = parent or self self.is_active = True def close(self): - """Close this transaction. + """Close this :class:`.Transaction`. If this transaction is the base transaction in a begin/commit nesting, the transaction will rollback(). Otherwise, the @@ -1471,6 +1508,7 @@ class Transaction(object): This is used to cancel a Transaction without affecting the scope of an enclosing transaction. + """ if not self._parent.is_active: return @@ -1478,6 +1516,9 @@ class Transaction(object): self.rollback() def rollback(self): + """Roll back this :class:`.Transaction`. + + """ if not self._parent.is_active: return self._do_rollback() @@ -1487,6 +1528,8 @@ class Transaction(object): self._parent.rollback() def commit(self): + """Commit this :class:`.Transaction`.""" + if not self._parent.is_active: raise exc.InvalidRequestError("This transaction is inactive") self._do_commit() @@ -1783,7 +1826,20 @@ class Engine(Connectable, log.Identified): conn.close() def execute(self, statement, *multiparams, **params): - """Executes and returns a ResultProxy.""" + """Executes the given construct and returns a :class:`.ResultProxy`. + + The arguments are the same as those used by + :meth:`.Connection.execute`. + + Here, a :class:`.Connection` is acquired using the + :meth:`~.Engine.contextual_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 + will also be closed, which allows its associated DBAPI connection + resource to be returned to the connection pool. + + """ connection = self.contextual_connect(close_with_result=True) return connection.execute(statement, *multiparams, **params) @@ -1800,16 +1856,30 @@ class Engine(Connectable, log.Identified): return connection._execute_compiled(compiled, multiparams, params) def connect(self, **kwargs): - """Return a newly allocated Connection object.""" + """Return a new :class:`.Connection` object. + + The :class:`.Connection`, upon construction, will procure a DBAPI connection + from the :class:`.Pool` referenced by this :class:`.Engine`, + returning it back to the :class:`.Pool` after the :meth:`.Connection.close` + method is called. + + """ return self.Connection(self, **kwargs) def contextual_connect(self, close_with_result=False, **kwargs): - """Return a Connection object which may be newly allocated, - or may be part of some ongoing context. - - This Connection is meant to be used by the various - "auto-connecting" operations. + """Return a :class:`.Connection` object which may be part of some ongoing context. + + By default, this method does the same thing as :meth:`.Engine.connect`. + Subclasses of :class:`.Engine` may override this method + to provide contextual behavior. + + :param close_with_result: When True, the first :class:`.ResultProxy` created + by the :class:`.Connection` will call the :meth:`.Connection.close` method + of that connection as soon as any pending result rows are exhausted. + This is used to supply the "connectionless execution" behavior provided + by the :meth:`.Engine.execute` method. + """ return self.Connection(self, |