added some docstrings and some deprecations

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 6fffbddb8c91f8429c176c3ce720bb16b59e3544..c99a69625096f2bcf564afee2674e2cd6efa1880 100644 (file)
--- 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 57f23ace295b5936f9400a0b5b7c5496dfec6d2f..072db4392160c894c89141f279b28d72241ad040 100644 (file)
--- 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)