From: Mike Bayer Date: Tue, 18 Jan 2011 22:17:29 +0000 (-0500) Subject: - copy 0.7's docs for Session.connection(), Session.execute(), minus X-Git-Tag: rel_0_6_7~48 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d239319ff10967cd07929a963092612badcca5d2;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git - copy 0.7's docs for Session.connection(), Session.execute(), minus the "bind" argument and **kw on connection. --- diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py index d954449417..9e3e2b78fc 100644 --- a/lib/sqlalchemy/orm/session.py +++ b/lib/sqlalchemy/orm/session.py @@ -632,25 +632,32 @@ class Session(object): self.transaction.prepare() def connection(self, mapper=None, clause=None): - """Return the active Connection. + """Return a :class:`.Connection` object corresponding to this + :class:`.Session` object's transactional state. + + If this :class:`.Session` is configured with ``autocommit=False``, + either the :class:`.Connection` correspoinding to the current transaction + is returned, or if no transaction is in progress, a new one is begun + and the :class:`.Connection` returned. + + Alternatively, if this :class:`.Session` is configured with ``autocommit=True``, + an ad-hoc :class:`.Connection` is returned using the :meth:`.Engine.contextual_connect` + on the underlying :class:`.Engine`. + + Ambiguity in multi-bind or unbound :class:`.Session` objects can be resolved through + any of the optional keyword arguments. This ultimately makes usage of the + :meth:`.get_bind` method for resolution. - Retrieves the ``Connection`` managing the current transaction. Any - operations executed on the Connection will take place in the same - transactional context as ``Session`` operations. - - For ``autocommit`` Sessions with no active manual transaction, - ``connection()`` is a passthrough to ``contextual_connect()`` on the - underlying engine. - - Ambiguity in multi-bind or unbound Sessions can be resolved through - any of the optional keyword arguments. See ``get_bind()`` for more - information. - - mapper - Optional, a ``mapper`` or mapped class + :param mapper: + Optional :func:`.mapper` mapped class, used to identify + the appropriate bind. This argument takes precedence over + ``clause``. - clause - Optional, any ``ClauseElement`` + :param clause: + A :class:`.ClauseElement` (i.e. :func:`~.sql.expression.select`, + :func:`~.sql.expression.text`, + etc.) which will be used to locate a bind, if a bind + cannot otherwise be identified. """ return self._connection_for_bind(self.get_bind(mapper, clause)) @@ -664,52 +671,49 @@ class Session(object): def execute(self, clause, params=None, mapper=None, **kw): """Execute a clause within the current transaction. - Returns a :class:`~sqlalchemy.engine.base.ResultProxy` representing + Returns a :class:`.ResultProxy` representing results of the statement execution, in the same manner as that of an - :class:`~sqlalchemy.engine.base.Engine` or - :class:`~sqlalchemy.engine.base.Connection`. - - :meth:`Session.execute` accepts any executable clause construct, such - as :func:`~sqlalchemy.sql.expression.select`, - :func:`~sqlalchemy.sql.expression.insert`, - :func:`~sqlalchemy.sql.expression.update`, - :func:`~sqlalchemy.sql.expression.delete`, and - :func:`~sqlalchemy.sql.expression.text`, and additionally accepts + :class:`.Engine` or + :class:`.Connection`. + + :meth:`~.Session.execute` accepts any executable clause construct, such + as :func:`~.sql.expression.select`, + :func:`~.sql.expression.insert`, + :func:`~.sql.expression.update`, + :func:`~.sql.expression.delete`, and + :func:`~.sql.expression.text`, and additionally accepts plain strings that represent SQL statements. If a plain string is passed, it is first converted to a - :func:`~sqlalchemy.sql.expression.text` construct, which here means + :func:`~.sql.expression.text` construct, which here means that bind parameters should be specified using the format ``:param``. The statement is executed within the current transactional context of - this :class:`Session`. If this :class:`Session` is set for - "autocommit", and no transaction is in progress, an ad-hoc transaction - will be created for the life of the result (i.e., a connection is - checked out from the connection pool, which is returned when the - result object is closed). - - If the :class:`Session` is not bound to an - :class:`~sqlalchemy.engine.base.Engine` or - :class:`~sqlalchemy.engine.base.Connection`, the given clause will be - inspected for binds (i.e., looking for "bound metadata"). If the - session is bound to multiple connectables, the ``mapper`` keyword - argument is typically passed in to specify which bind should be used - (since the :class:`Session` keys multiple bind sources to a series of - :func:`mapper` objects). See :meth:`get_bind` for further details on - bind resolution. - + this :class:`.Session`, using the same behavior as that of + the :meth:`.Session.connection` method to determine the active + :class:`.Connection`. The ``close_with_result`` flag is + set to ``True`` so that an ``autocommit=True`` :class:`.Session` + with no active transaction will produce a result that auto-closes + the underlying :class:`.Connection`. + :param clause: - A ClauseElement (i.e. select(), text(), etc.) or - string SQL statement to be executed + A :class:`.ClauseElement` (i.e. :func:`~.sql.expression.select`, + :func:`~.sql.expression.text`, etc.) or string SQL statement to be executed. The clause + will also be used to locate a bind, if this :class:`.Session` + is not bound to a single engine already, and the ``mapper`` + argument is not passed. :param params: - Optional, a dictionary of bind parameters. + Optional dictionary of bind names mapped to values. :param mapper: - Optional, a ``mapper`` or mapped class + Optional :func:`.mapper` or mapped class, used to identify + the appropriate bind. This argument takes precedence over + ``clause`` when locating a bind. :param \**kw: - Additional keyword arguments are sent to :meth:`get_bind()` - which locates a connectable to use for the execution. + Additional keyword arguments are sent to :meth:`get_bind()`, + allowing additional arguments to be passed to custom + implementations of :meth:`get_bind`. """ clause = expression._literal_as_text(clause)