From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Fri, 22 Apr 2011 22:40:43 +0000 (-0400)
Subject: docuemnt the behavior of get(), part of [ticket:2144]
X-Git-Tag: rel_0_6_8~21
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=e500b445209f33e162d585eb15a9f8f045b1d01b;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

docuemnt the behavior of get(), part of [ticket:2144]
---

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index f8b45cdb65..30dae14c28 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -632,10 +632,21 @@ 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 table def's primary key columns.
+        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, or in the case of a single
+        column a deprecation warning is raised as of 0.6.8.
 
         """