From 1f65ac6679298c7f18e8ff3b13d6694e357ed5d5 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Sat, 4 Sep 2010 21:02:35 -0400 Subject: roughly the finished product. --- lib/sqlalchemy/engine/base.py | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) (limited to 'lib/sqlalchemy/engine/base.py') diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py index 14ebf916b..20e7e2338 100644 --- a/lib/sqlalchemy/engine/base.py +++ b/lib/sqlalchemy/engine/base.py @@ -801,7 +801,20 @@ class Connection(Connectable): as ClauseElement, Compiled and DefaultGenerator objects. Provides a :meth:`begin` method to return Transaction objects. - The Connection object is **not** thread-safe. + 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. If your application has a need for management + of multiple connections or is otherwise long running (this includes all + web applications, threaded or not), don't hold a single connection open at + the module level. .. index:: single: thread safety; Connection -- cgit v1.2.1 From 703ce7f1791c1143eb983c38e3bd627984ea1953 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Sun, 5 Sep 2010 14:44:58 -0400 Subject: - rewrote the "connections" section - improved pool docs - typos etc. - ClauseElement.execute() and scalar() make no sense - these are depreacted. The official home is Executable. - alias() is not executable, allowing it is sloppy so this goes under the deprecated umbrella --- lib/sqlalchemy/engine/base.py | 71 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 57 insertions(+), 14 deletions(-) (limited to 'lib/sqlalchemy/engine/base.py') diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py index 20e7e2338..7098e695d 100644 --- a/lib/sqlalchemy/engine/base.py +++ b/lib/sqlalchemy/engine/base.py @@ -797,9 +797,10 @@ 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. + 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 @@ -825,9 +826,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 @@ -1167,7 +1168,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: @@ -1739,7 +1755,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) @@ -1756,16 +1785,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, -- cgit v1.2.1 From 900fe9c9accecd68ed1c25b03013ee4972338712 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Mon, 6 Sep 2010 11:48:22 -0400 Subject: doc updates --- lib/sqlalchemy/engine/base.py | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) (limited to 'lib/sqlalchemy/engine/base.py') diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py index 7098e695d..63d76efa0 100644 --- a/lib/sqlalchemy/engine/base.py +++ b/lib/sqlalchemy/engine/base.py @@ -1480,6 +1480,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:: @@ -1487,12 +1493,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 @@ -1500,6 +1511,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 @@ -1507,6 +1519,9 @@ class Transaction(object): self.rollback() def rollback(self): + """Roll back this :class:`.Transaction`. + + """ if not self._parent.is_active: return self._do_rollback() @@ -1516,6 +1531,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() -- cgit v1.2.1 From a191ded054899fe2d827b4341529f1a5ec1d711e Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Wed, 8 Sep 2010 15:43:24 -0400 Subject: edits --- lib/sqlalchemy/engine/base.py | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) (limited to 'lib/sqlalchemy/engine/base.py') diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py index 63d76efa0..79cadaea9 100644 --- a/lib/sqlalchemy/engine/base.py +++ b/lib/sqlalchemy/engine/base.py @@ -812,10 +812,7 @@ class Connection(Connectable): 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. If your application has a need for management - of multiple connections or is otherwise long running (this includes all - web applications, threaded or not), don't hold a single connection open at - the module level. + connection is not in use. .. index:: single: thread safety; Connection -- cgit v1.2.1