From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Mon, 9 Jun 2008 01:46:35 +0000 (+0000)
Subject: added some docstrings and some deprecations
X-Git-Tag: rel_0_4_7~21
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a26cb9ebc2f97045e108328898b7b04f65a6e5ff;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

added some docstrings and some deprecations
---

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 6fffbddb8c..c99a696250 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -275,6 +275,8 @@ class Query(object):
         pending changes** to the object already existing in the Session.  The
         `ident` argument is a scalar or tuple of primary key column values in
         the order of the table def's primary key columns.
+        
+        DEPRECATED.  Use query.populate_existing().get() instead.
         """
 
         ret = self._extension.load(self, ident, **kwargs)
@@ -940,9 +942,26 @@ class Query(object):
         return self.iterate_instances(result, querycontext=querycontext)
 
     def instances(self, cursor, *mappers_or_columns, **kwargs):
+        """Given a ResultProxy cursor as returned by connection.execute(), return an ORM result as a list.
+
+        e.g.::
+        
+            result = engine.execute("select * from users")
+            users = session.query(User).instances(result)
+
+        """
         return list(self.iterate_instances(cursor, *mappers_or_columns, **kwargs))
 
     def iterate_instances(self, cursor, *mappers_or_columns, **kwargs):
+        """Given a ResultProxy cursor as returned by connection.execute(), return an ORM result as an iterator.
+        
+        e.g.::
+        
+            result = engine.execute("select * from users")
+            for u in session.query(User).iterate_instances(result):
+                print u
+
+        """
         session = self.session
 
         context = kwargs.pop('querycontext', None)
diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index 57f23ace29..072db43921 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -788,16 +788,10 @@ class Session(object):
     def get(self, class_, ident, **kwargs):
         """Return an instance of the object based on the given
         identifier, or ``None`` if not found.
+        
+        DEPRECATED.  use session.query(class_).get(ident)
 
-        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 `entity_name` keyword argument may also be specified which
-        further qualifies the underlying Mapper used to perform the
-        query.
         """
-
         entity_name = kwargs.pop('entity_name', None)
         return self.query(class_, entity_name=entity_name).get(ident, **kwargs)
 
@@ -805,17 +799,9 @@ class Session(object):
         """Return an instance of the object based on the given
         identifier.
 
-        If not found, raises an exception.  The method will **remove
-        all pending changes** to the object already existing in the
-        ``Session``.  The `ident` argument is a scalar or tuple of primary
-        key columns in the order of the table def's primary key
-        columns.
+        DEPRECATED.  use session.query(class_).populate_existing().get(ident).
 
-        The `entity_name` keyword argument may also be specified which
-        further qualifies the underlying ``Mapper`` used to perform the
-        query.
         """
-
         entity_name = kwargs.pop('entity_name', None)
         return self.query(class_, entity_name=entity_name).load(ident, **kwargs)