Merge branch 'master' into ticket_2501ticket_2501

Conflicts:
	lib/sqlalchemy/orm/mapper.py

8 files changed, 41 insertions, 53 deletions

diff --git a/examples/dogpile_caching/__init__.py b/examples/dogpile_caching/__init__.py
index 00c386bda..bf67eeb17 100644
--- a/examples/dogpile_caching/__init__.py
+++ b/examples/dogpile_caching/__init__.py
@@ -40,45 +40,20 @@ exactly one SQL statement against two tables will be emitted - the
 displayed result however will utilize dozens of lazyloads that all
 pull from cache.
 
-The demo scripts themselves, in order of complexity, are run as follows::
+The demo scripts themselves, in order of complexity, are run as Python
+modules so that relative imports work::
 
-   python examples/dogpile_caching/helloworld.py
+   python -m examples.dogpile_caching.helloworld
 
-   python examples/dogpile_caching/relationship_caching.py
+   python -m examples.dogpile_caching.relationship_caching
 
-   python examples/dogpile_caching/advanced.py
+   python -m examples.dogpile_caching.advanced
 
-   python examples/dogpile_caching/local_session_caching.py
+   python -m examples.dogpile_caching.local_session_caching
 
-
-Listing of files:
-
-    environment.py - Establish the Session, a dictionary
-    of "regions", a sample cache region against a .dbm
-    file, data / cache file paths, and configurations,
-    bootstrap fixture data if necessary.
-
-    caching_query.py - Represent functions and classes
-    which allow the usage of Dogpile caching with SQLAlchemy.
-    Introduces a query option called FromCache.
-
-    model.py - The datamodel, which represents Person that has multiple
-    Address objects, each with PostalCode, City, Country
-
-    fixture_data.py - creates demo PostalCode, Address, Person objects
-    in the database.
-
-    helloworld.py - the basic idea.
-
-    relationship_caching.py - Illustrates how to add cache options on
-    relationship endpoints, so that lazyloads load from cache.
-
-    advanced.py - Further examples of how to use FromCache.  Combines
-    techniques from the first two scripts.
-
-    local_session_caching.py - Grok everything so far ?   This example
-    creates a new dogpile.cache backend that will persist data in a dictionary
-    which is local to the current session.   remove() the session
-    and the cache is gone.
+.. autosource::
+    :files: environment.py, caching_query.py, model.py, fixture_data.py, \
+          helloworld.py, relationship_caching.py, advanced.py, \
+          local_session_caching.py
 
 """
diff --git a/examples/dogpile_caching/advanced.py b/examples/dogpile_caching/advanced.py
index f1a18a4d7..feccaa3ba 100644
--- a/examples/dogpile_caching/advanced.py
+++ b/examples/dogpile_caching/advanced.py
@@ -1,15 +1,13 @@
 """advanced.py
 
 Illustrate usage of Query combined with the FromCache option,
-including front-end loading, cache invalidation, namespace techniques
-and collection caching.
+including front-end loading, cache invalidation and collection caching.
 
 """
 
 from .environment import Session
-from .model import Person, Address, cache_address_bits
+from .model import Person, cache_address_bits
 from .caching_query import FromCache, RelationshipCache
-from sqlalchemy.orm import joinedload
 
 def load_name_range(start, end, invalidate=False):
     """Load Person objects on a range of names.
@@ -23,7 +21,7 @@ def load_name_range(start, end, invalidate=False):
     The `Person.addresses` collections are also cached.  Its basically
     another level of tuning here, as that particular cache option
     can be transparently replaced with joinedload(Person.addresses).
-    The effect is that each Person and his/her Address collection
+    The effect is that each Person and their Address collection
     is cached either together or separately, affecting the kind of
     SQL that emits for unloaded Person objects as well as the distribution
     of data within the cache.
diff --git a/examples/dogpile_caching/caching_query.py b/examples/dogpile_caching/caching_query.py
index 7fe84bede..9ac0d431a 100644
--- a/examples/dogpile_caching/caching_query.py
+++ b/examples/dogpile_caching/caching_query.py
@@ -1,7 +1,8 @@
 """caching_query.py
 
-Represent persistence structures which allow the usage of
-dogpile.cache caching with SQLAlchemy.
+Represent functions and classes
+which allow the usage of Dogpile caching with SQLAlchemy.
+Introduces a query option called FromCache.
 
 The three new concepts introduced here are:
 
diff --git a/examples/dogpile_caching/environment.py b/examples/dogpile_caching/environment.py
index 36b9585b2..aeba65e19 100644
--- a/examples/dogpile_caching/environment.py
+++ b/examples/dogpile_caching/environment.py
@@ -10,7 +10,12 @@ from sqlalchemy.orm import scoped_session, sessionmaker
 from sqlalchemy.ext.declarative import declarative_base
 from dogpile.cache.region import make_region
 import os
-import md5
+from hashlib import md5
+import sys
+py2k = sys.version_info < (3, 0)
+
+if py2k:
+    input = raw_input
 
 # dogpile cache regions.  A home base for cache configurations.
 regions = {}
@@ -47,7 +52,7 @@ def md5_key_mangler(key):
     distill them into an md5 hash.
 
     """
-    return md5.md5(key).hexdigest()
+    return md5(key.encode('ascii')).hexdigest()
 
 # configure the "default" cache region.
 regions['default'] = make_region(
diff --git a/examples/dogpile_caching/helloworld.py b/examples/dogpile_caching/helloworld.py
index 4561097b6..22d7f97be 100644
--- a/examples/dogpile_caching/helloworld.py
+++ b/examples/dogpile_caching/helloworld.py
@@ -8,27 +8,27 @@ from .environment import Session
 from .model import Person
 from .caching_query import FromCache
 
-# load Person objects.  cache the result under the namespace "all_people".
+# load Person objects.  cache the result in the "default" cache region
 print("loading people....")
 people = Session.query(Person).options(FromCache("default")).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.
+# load again, using the same FromCache option. now they're cached,
+# so no SQL is emitted.
 print("loading people....again!")
 people = Session.query(Person).options(FromCache("default")).all()
 
-# want to load on some different kind of query ?  change the namespace
-# you send to FromCache
+# Specifying a different query produces a different cache key, so
+# these results are independently cached.
 print("loading people two through twelve")
 people_two_through_twelve = Session.query(Person).\
                             options(FromCache("default")).\
                             filter(Person.name.between("person 02", "person 12")).\
                             all()
 
-# the data is cached under the "namespace" you send to FromCache, *plus*
+# the data is cached under string structure of the SQL statement, *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...
diff --git a/examples/dogpile_caching/local_session_caching.py b/examples/dogpile_caching/local_session_caching.py
index cf0083d2e..e6c712b4a 100644
--- a/examples/dogpile_caching/local_session_caching.py
+++ b/examples/dogpile_caching/local_session_caching.py
@@ -1,5 +1,10 @@
 """local_session_caching.py
 
+Grok everything so far ?   This example
+creates a new dogpile.cache backend that will persist data in a dictionary
+which is local to the current session.   remove() the session
+and the cache is gone.
+
 Create a new Dogpile cache backend that will store
 cached data local to the current Session.
 
diff --git a/examples/dogpile_caching/model.py b/examples/dogpile_caching/model.py
index 622d31e6a..75c0ad28a 100644
--- a/examples/dogpile_caching/model.py
+++ b/examples/dogpile_caching/model.py
@@ -1,6 +1,7 @@
-"""Model.   We are modeling Person objects with a collection
-of Address objects.  Each Address has a PostalCode, which
-in turn references a City and then a Country:
+"""model.py
+
+The datamodel, which represents Person that has multiple
+Address objects, each with PostalCode, City, Country.
 
 Person --(1..n)--> Address
 Address --(has a)--> PostalCode
diff --git a/examples/dogpile_caching/relation_caching.py b/examples/dogpile_caching/relationship_caching.py
index d40752e48..320ced48a 100644
--- a/examples/dogpile_caching/relation_caching.py
+++ b/examples/dogpile_caching/relationship_caching.py
@@ -1,5 +1,8 @@
 """relationship_caching.py
 
+Illustrates how to add cache options on
+relationship endpoints, so that lazyloads load from cache.
+
 Load a set of Person and Address objects, specifying that
 related PostalCode, City, Country objects should be pulled from long
 term cache.