From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Wed, 17 Aug 2011 18:55:21 +0000 (-0400)
Subject: document session bind resolution order
X-Git-Tag: rel_0_7_3~69
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1aede1795b5ad88166f90b0486e53755a388fb4b;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

document session bind resolution order
---

diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index 0810fa31fd..1cdf1d7eb0 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -879,7 +879,31 @@ class Session(object):
         For a multiply-bound or unbound :class:`.Session`, the 
         ``mapper`` or ``clause`` arguments are used to determine the 
         appropriate bind to return.
-
+        
+        Note that the "mapper" argument is usually present
+        when :meth:`.Session.get_bind` is called via an ORM
+        operation such as a :meth:`.Session.query`, each 
+        individual INSERT/UPDATE/DELETE operation within a 
+        :meth:`.Session.flush`, call, etc.
+        
+        The order of resolution is:
+        
+        1. if mapper given and session.binds is present,
+           locate a bind based on mapper.
+        2. if clause given and session.binds is present,
+           locate a bind based on :class:`.Table` objects
+           found in the given clause present in session.binds.
+        3. if session.bind is present, return that.
+        4. if clause given, attempt to return a bind 
+           linked to the :class:`.MetaData` ultimately
+           associated with the clause.
+        5. if mapper given, attempt to return a bind
+           linked to the :class:`.MetaData` ultimately 
+           associated with the :class:`.Table` or other
+           selectable to which the mapper is mapped.
+        6. No bind can be found, :class:`.UnboundExecutionError`
+           is raised.
+         
         :param mapper:
           Optional :func:`.mapper` mapped class or instance of
           :class:`.Mapper`.   The bind can be derived from a :class:`.Mapper`