- 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 d954449417e823f5bc385b65608d9b4408c9ad5f..9e3e2b78fc25816445ba83f16e5bd62093fc9781 100644 (file)
--- 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)