From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Fri, 22 Apr 2011 22:41:13 +0000 (-0400)
Subject: document the behavior of get() regarding invalid usages as per [ticket:2144]
X-Git-Tag: rel_0_7_0~45
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0c1c6431bc64d98c0bfd517795e2965d32f0968a;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

document the behavior of get() regarding invalid usages as per [ticket:2144]
---

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index b7b2eccec8..ef42e0d3ab 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -628,12 +628,20 @@ class Query(object):
 
     def get(self, ident):
         """Return an instance of the object based on the 
-        given identifier, or None if not found.
+        given identifier, or ``None`` if not found.
 
-        The `ident` argument is a scalar or tuple of primary key column values
-        in the order of the mapper's "priamry key" setting, which
+        The ``ident`` argument is a scalar or tuple of 
+        primary key column values
+        in the order of the mapper's "primary key" setting, which
         defaults to the list of primary key columns for the 
         mapped :class:`.Table`.
+        
+        :meth:`get` returns only a single mapped instance, or
+        ``None``.  It is not intended to return rows or scalar
+        column values, therefore the :class:`.Query` must be 
+        constructed only against a single mapper or mapped class,
+        not a SQL expression or multiple entities.
+        Other usages raise an error.
 
         """