add more examples, start basic

5 files changed, 80 insertions, 14 deletions

diff --git a/examples/beaker_caching/README b/examples/beaker_caching/README
index 9a2db70c6..1eb93f873 100644
--- a/examples/beaker_caching/README
+++ b/examples/beaker_caching/README
@@ -22,11 +22,13 @@ exactly one SQL statement against two tables will be emitted - the
 displayed result however will utilize dozens of lazyloads that all
 pull from cache.
 
-Two endpoint scripts, "demo.py" and "ad_hoc.py", are run as follows:
+Three endpoint scripts, in order of complexity, are run as follows:
 
-   python examples/beaker_caching/demo.py
+   python examples/beaker_caching/helloworld.py
 
-   python examples/beaker_caching/ad_hoc.py
+   python examples/beaker_caching/relation_caching.py
+
+   python examples/beaker_caching/advanced.py
 
 
 Listing of files:
@@ -44,11 +46,10 @@ Address objects, each with PostalCode, City, Country
 fixture_data.py - creates demo PostalCode, Address, Person objects
 in the database.
 
-demo.py - The first script to run - illustrates loading a list of
-Person / Address objects.  When run a second time, most data is 
-cached and only one SQL statement is emitted.
+helloworld.py - the basic idea.
 
-ad_hoc.py - Further examples of how to use FromCache.  Illustrates
-front-end usage, cache invalidation, loading related collections
-from cache vs. eager loading of collections.
+relation_caching.py - Illustrates how to add cache options on
+relation endpoints, so that lazyloads load from cache.
 
+advanced.py - Further examples of how to use FromCache.  Combines
+techniques from the first two scripts.
diff --git a/examples/beaker_caching/ad_hoc.py b/examples/beaker_caching/advanced.py
index bb6b0823b..6a8db082c 100644
--- a/examples/beaker_caching/ad_hoc.py
+++ b/examples/beaker_caching/advanced.py
@@ -1,4 +1,4 @@
-"""ac_hoc.py
+"""advanced.py
 
 Illustrate usage of Query combined with the FromCache option, 
 including front-end loading, cache invalidation, namespace techniques
@@ -75,5 +75,5 @@ print "\n\nPeople plus addresses, two through twelve, addresses from cache"
 for p in load_name_range(2, 12):
     print p.format_full()
 
-print "\n\nIf this was the first run of ad_hoc.py, try "\
+print "\n\nIf this was the first run of advanced.py, try "\
         "a second run.  Only one SQL statement will be emitted."
diff --git a/examples/beaker_caching/helloworld.py b/examples/beaker_caching/helloworld.py
new file mode 100644
index 000000000..33454cf80
--- /dev/null
+++ b/examples/beaker_caching/helloworld.py
@@ -0,0 +1,62 @@
+"""helloworld.py
+
+Illustrate how to load some data, and cache the results.
+
+"""
+
+import __init__ # if running as a script
+from model import Person
+from meta import Session, FromCache
+
+# load Person objects.  cache the result under the namespace "all_people".
+print "loading people...."
+people = Session.query(Person).options(FromCache("default", "all_people")).all()
+
+# remove the Session.  next query starts from scratch.
+Session.remove()
+
+# load again, using the same FromCache option. now they're cached 
+# under "all_people", no SQL is emitted.
+print "loading people....again!"
+people = Session.query(Person).options(FromCache("default", "all_people")).all()
+
+# want to load on some different kind of query ?  change the namespace 
+# you send to FromCache
+print "loading people two through twelve"
+people_two_through_twelve = Session.query(Person).\
+                            options(FromCache("default", "people_on_range")).\
+                            filter(Person.name.between("person 02", "person 12")).\
+                            all()
+
+# the data is cached under the "namespace" you send to FromCache, *plus*
+# the bind parameters of the query.    So this query, having
+# different literal parameters under "Person.name.between()" than the 
+# previous one, issues new SQL...
+print "loading people five through fifteen"
+people_five_through_fifteen = Session.query(Person).\
+                            options(FromCache("default", "people_on_range")).\
+                            filter(Person.name.between("person 05", "person 15")).\
+                            all()
+
+
+# ... but using the same params as are already cached, no SQL
+print "loading people two through twelve...again!"
+people_two_through_twelve = Session.query(Person).\
+                            options(FromCache("default", "people_on_range")).\
+                            filter(Person.name.between("person 02", "person 12")).\
+                            all()
+
+
+# invalidate the cache for the three queries we've done.  Recreate
+# each Query, which includes at the very least the same FromCache, 
+# same list of objects to be loaded, and the same parameters in the 
+# same order, then call invalidate().
+print "invalidating everything"
+Session.query(Person).options(FromCache("default", "all_people")).invalidate()
+Session.query(Person).\
+            options(FromCache("default", "people_on_range")).\
+            filter(Person.name.between("person 02", "person 12")).invalidate()
+Session.query(Person).\
+            options(FromCache("default", "people_on_range")).\
+            filter(Person.name.between("person 05", "person 15")).invalidate()
+
diff --git a/examples/beaker_caching/model.py b/examples/beaker_caching/model.py
index 25ce162fc..4c043b42b 100644
--- a/examples/beaker_caching/model.py
+++ b/examples/beaker_caching/model.py
@@ -86,6 +86,9 @@ class Person(Base):
     def __str__(self):
         return self.name
     
+    def __repr__(self):
+        return "Person(name=%r)" % self.name
+        
     def format_full(self):
         return "\t".join([str(x) for x in [self] + list(self.addresses)])
         
diff --git a/examples/beaker_caching/demo.py b/examples/beaker_caching/relation_caching.py
index f2f038d28..b4508ba1e 100644
--- a/examples/beaker_caching/demo.py
+++ b/examples/beaker_caching/relation_caching.py
@@ -1,7 +1,7 @@
-"""demo.py
+"""relation_caching.py
 
 Load a set of Person and Address objects, specifying that 
-PostalCode, City, Country objects should be pulled from long 
+related PostalCode, City, Country objects should be pulled from long 
 term cache.
 
 """
@@ -15,7 +15,7 @@ for p in Session.query(Person).options(eagerload(Person.addresses), cache_addres
     print p.format_full()
 
 
-print "\n\nIf this was the first run of demo.py, SQL was likely emitted to "\
+print "\n\nIf this was the first run of relation_caching.py, SQL was likely emitted to "\
         "load postal codes, cities, countries.\n"\
         "If run a second time, only a single SQL statement will run - all "\
         "related data is pulled from cache.\n"\