- document get_bind(), [ticket:1053]

- ensure mapper has "None" default for get_bind()

diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index 4da21e560901be804b5c6b2c7653129c892047c0..61fe1b7bca714d46f2639dba2709b96686d7ee81 100644 (file)
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -638,7 +638,8 @@ class Session(object):
         If this :class:`.Session` is configured with ``autocommit=False``,
         either the :class:`.Connection` corresponding to the current transaction
         is returned, or if no transaction is in progress, a new one is begun
-        and the :class:`.Connection` returned.
+        and the :class:`.Connection` returned (note that no transactional state
+        is established with the DBAPI until the first SQL statement is emitted).
         
         Alternatively, if this :class:`.Session` is configured with ``autocommit=True``,
         an ad-hoc :class:`.Connection` is returned using :meth:`.Engine.contextual_connect` 
@@ -802,16 +803,32 @@ class Session(object):
         """
         self.__binds[table] = bind
 
-    def get_bind(self, mapper, clause=None):
-        """Return an engine corresponding to the given arguments.
+    def get_bind(self, mapper=None, clause=None):
+        """Return a "bind" to which this :class:`.Session` is bound.
+        
+        The "bind" is usually an instance of :class:`.Engine`, 
+        except in the case where the :class:`.Session` has been
+        explicitly bound directly to a :class:`.Connection`.
 
-        All arguments are optional.
+        For a multiply-bound or unbound :class:`.Session`, the 
+        ``mapper`` or ``clause`` arguments are used to determine the 
+        appropriate bind to return.
 
-        mapper
-          Optional, a ``Mapper`` or mapped class
+        :param mapper:
+          Optional :func:`.mapper` mapped class or instance of
+          :class:`.Mapper`.   The bind can be derived from a :class:`.Mapper`
+          first by consulting the "binds" map associated with this
+          :class:`.Session`, and secondly by consulting the :class:`.MetaData`
+          associated with the :class:`.Table` to which the :class:`.Mapper`
+          is mapped for a bind.
 
-        clause
-          Optional, A ClauseElement (i.e. select(), text(), etc.)
+        :param clause:
+            A :class:`.ClauseElement` (i.e. :func:`~.sql.expression.select`, 
+            :func:`~.sql.expression.text`, 
+            etc.).  If the ``mapper`` argument is not present or could not produce
+            a bind, the given expression construct will be searched for a bound
+            element, typically a :class:`.Table` associated with bound 
+            :class:`.MetaData`.
 
         """
         if mapper is clause is None: