From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Tue, 17 Apr 2007 18:15:58 +0000 (+0000)
Subject: docs/examples for new with_parent() feature
X-Git-Tag: rel_0_3_7~65
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=8d7a271b8687dbcb58cac713f9e16e445d242881;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

docs/examples for new with_parent() feature
---

diff --git a/doc/build/content/adv_datamapping.txt b/doc/build/content/adv_datamapping.txt
index 585ac5990a..a905024d02 100644
--- 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 0961b435b1..16fdf2be88 100644
--- 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 3935797077..743624e993 100644
--- 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()