docs/examples for new with_parent() feature

diff --git a/doc/build/content/adv_datamapping.txt b/doc/build/content/adv_datamapping.txt
index 585ac5990a1537915ce6e76ecfd3f3981f7573e6..a905024d0228643c6951664c6be89f7a832c2de5 100644 (file)
--- a/doc/build/content/adv_datamapping.txt
+++ b/doc/build/content/adv_datamapping.txt
@@ -269,16 +269,23 @@ So there are several techniques that can be used individually or combined togeth
             'children':relation(MyOtherClass, lazy=None)
         })
 
-* To load child objects, just use a query:
+* To load child objects, just use a query.  Of particular convenience is that `Query` is a generative object, so you can return
+it as is, allowing additional criterion to be added as needed:
 
         {python}
         class Organization(object):
             def __init__(self, name):
                 self.name = name
-            def find_members(self, criterion):
-                """locate a subset of the members associated with this Organization"""
-                return object_session(self).query(Member).select(and_(member_table.c.name.like(criterion), org_table.c.org_id==self.org_id), from_obj=[org_table.join(member_table)])
-    
+            member_query = property(lambda self: object_session(self).query(Member).with_parent(self))
+
+        myorg = sess.query(Organization).get(5)
+        
+        # get all members
+        members = myorg.member_query.list()
+        
+        # query a subset of members using LIMIT/OFFSET
+        members = myorg.member_query[5:10]
+        
 * Use `passive_deletes=True` to disable child object loading on a DELETE operation, in conjunction with "ON DELETE (CASCADE|SET NULL)" on your database to automatically cascade deletes to child objects.   Note that "ON DELETE" is not supported on SQLite, and requires `InnoDB` tables when using MySQL:
 
         {python}

diff --git a/doc/build/content/datamapping.txt b/doc/build/content/datamapping.txt
index 0961b435b111e4732172197489d8c76828526f42..16fdf2be887b27433543bc5c173e0ac744b1c579 100644 (file)
--- a/doc/build/content/datamapping.txt
+++ b/doc/build/content/datamapping.txt
@@ -563,6 +563,21 @@ To traverse more deeply into relationships, specify multiple relationship names
 
 The `join()` method is an easier-to-use version of the `join_by()`, `join_to()` and `join_via()` methods, all of which produce `ClauseElements` that can be constructed into a query criterion.  Consult the generated documentation for information on these methods.
 
+#### Joining from a Parent Object {@name=joinparent}
+
+(new in 0.3.7) To help in navigating collections, the `with_parent()` generative method adds join criterion which corresponds to instances which belong to a particular parent.  This method makes use of the same "lazy loading" criterion used to load relationships normally, which means it also works seamlessly for self-referential relationships.  For example, to load all the `Address` objects which belong to a particular `User`:
+
+    {python}
+    # load a user
+    someuser = session.query(User).get(2)
+    
+    # load the addresses of that user
+    addresses = session.query(Address).with_parent(someuser).list()
+    
+    # filter the results
+    someaddresses = session.query(Address).with_parent(someuser).filter_by(email_address="foo@bar.com").list()
+    
+
 #### Eager Loading {@name=eagerload}
 
 Eager Loading describes the loading of parent and child objects across a relation using a single query.  The purpose of eager loading is strictly one of performance enhancement; eager loading has **no impact** on the results of a query, except that when traversing child objects within the results, lazy loaders will not need to issue separate queries to load those child objects.

diff --git a/examples/collections/large_collection.py b/examples/collections/large_collection.py
index 39357970770b1229adb3057a56f69d6a0a5baa12..743624e99344eaf3f90a72ad3b032b624d595f2e 100644 (file)
--- a/examples/collections/large_collection.py
+++ b/examples/collections/large_collection.py
@@ -18,9 +18,8 @@ meta.create_all()
 class Organization(object):
     def __init__(self, name):
         self.name = name
-    def find_members(self, criterion):
-        """locate a subset of the members associated with this Organization"""
-        return object_session(self).query(Member).select(and_(member_table.c.name.like(criterion), org_table.c.org_id==self.org_id), from_obj=[org_table.join(member_table)])
+    member_query = property(lambda self:object_session(self).query(Member).with_parent(self), 
+        doc="""locate a subset of the members associated with this Organization""")
     
 class Member(object):
     def __init__(self, name):
@@ -60,7 +59,7 @@ sess.clear()
 # reload. load the org and some child members
 print "-------------------------\nload subset of members"
 org = sess.query(Organization).get(org.org_id)
-members = org.find_members('%member t%')
+members = org.member_query.filter_by(member_table.c.name.like('%member t%')).list()
 print members
 
 sess.clear()