Commits

Mike Bayer committed 961c3a6

added some docstrings and some deprecations

Comments (0)

Files changed (2)

lib/sqlalchemy/orm/query.py

         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)
         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)

lib/sqlalchemy/orm/session.py

     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)
 
         """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)
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.