- fix formatting on examples to list the description first, some flake8

Change-Id: I57144a559f20abab02e745d052be5ff84edec7f8
(cherry picked from commit c89729cf67f441359da8289104050b01eb53160b)

16 files changed, 107 insertions, 126 deletions

diff --git a/examples/association/basic_association.py b/examples/association/basic_association.py
index 3835e44f2..6714aa681 100644
--- a/examples/association/basic_association.py
+++ b/examples/association/basic_association.py
@@ -1,6 +1,4 @@
-"""basic_association.py
-
-illustrate a many-to-many relationship between an
+"""Illustrate a many-to-many relationship between an
 "Order" and a collection of "Item" objects, associating a purchase price
 with each via an association object called "OrderItem"
 
diff --git a/examples/association/dict_of_sets_with_default.py b/examples/association/dict_of_sets_with_default.py
index 4f0ff462d..fb9b6aa06 100644
--- a/examples/association/dict_of_sets_with_default.py
+++ b/examples/association/dict_of_sets_with_default.py
@@ -1,6 +1,4 @@
-"""dict_of_sets_with_default.py
-
-an advanced association proxy example which
+"""An advanced association proxy example which
 illustrates nesting of association proxies to produce multi-level Python
 collections, in this case a dictionary with string keys and sets of integers
 as values, which conceal the underlying mapped classes.
diff --git a/examples/association/proxied_association.py b/examples/association/proxied_association.py
index d5d48819f..3393fdd1d 100644
--- a/examples/association/proxied_association.py
+++ b/examples/association/proxied_association.py
@@ -1,6 +1,4 @@
-"""proxied_association.py
-
-same example as basic_association, adding in
+"""Same example as basic_association, adding in
 usage of :mod:`sqlalchemy.ext.associationproxy` to make explicit references
 to ``OrderItem`` optional.
 
diff --git a/examples/custom_attributes/listen_for_events.py b/examples/custom_attributes/listen_for_events.py
index 82bc860fa..0aeebc1d1 100644
--- a/examples/custom_attributes/listen_for_events.py
+++ b/examples/custom_attributes/listen_for_events.py
@@ -1,5 +1,4 @@
-"""
-Illustrates how to attach events to all instrumented attributes
+"""Illustrates how to attach events to all instrumented attributes
 and listen for change events.
 
 """
diff --git a/examples/dogpile_caching/advanced.py b/examples/dogpile_caching/advanced.py
index feccaa3ba..dc2ed0771 100644
--- a/examples/dogpile_caching/advanced.py
+++ b/examples/dogpile_caching/advanced.py
@@ -1,6 +1,4 @@
-"""advanced.py
-
-Illustrate usage of Query combined with the FromCache option,
+"""Illustrate usage of Query combined with the FromCache option,
 including front-end loading, cache invalidation and collection caching.
 
 """
diff --git a/examples/dogpile_caching/caching_query.py b/examples/dogpile_caching/caching_query.py
index 9ac0d431a..bcec213c8 100644
--- a/examples/dogpile_caching/caching_query.py
+++ b/examples/dogpile_caching/caching_query.py
@@ -1,6 +1,4 @@
-"""caching_query.py
-
-Represent functions and classes
+"""Represent functions and classes
 which allow the usage of Dogpile caching with SQLAlchemy.
 Introduces a query option called FromCache.
 
@@ -21,21 +19,21 @@ dogpile.cache constructs.
 """
 from sqlalchemy.orm.interfaces import MapperOption
 from sqlalchemy.orm.query import Query
-from sqlalchemy.sql import visitors
 from dogpile.cache.api import NO_VALUE
 
+
 class CachingQuery(Query):
     """A Query subclass which optionally loads full results from a dogpile
     cache region.
 
-    The CachingQuery optionally stores additional state that allows it to consult
-    a dogpile.cache cache before accessing the database, in the form
-    of a FromCache or RelationshipCache object.   Each of these objects
-    refer to the name of a :class:`dogpile.cache.Region` that's been configured
-    and stored in a lookup dictionary.  When such an object has associated
-    itself with the CachingQuery, the corresponding :class:`dogpile.cache.Region`
-    is used to locate a cached result.  If none is present, then the
-    Query is invoked normally, the results being cached.
+    The CachingQuery optionally stores additional state that allows it to
+    consult a dogpile.cache cache before accessing the database, in the form of
+    a FromCache or RelationshipCache object.   Each of these objects refer to
+    the name of a :class:`dogpile.cache.Region` that's been configured and
+    stored in a lookup dictionary.  When such an object has associated itself
+    with the CachingQuery, the corresponding :class:`dogpile.cache.Region` is
+    used to locate a cached result.  If none is present, then the Query is
+    invoked normally, the results being cached.
 
     The FromCache and RelationshipCache mapper options below represent
     the "public" method of configuring this state upon the CachingQuery.
diff --git a/examples/dogpile_caching/environment.py b/examples/dogpile_caching/environment.py
index aeba65e19..130dfdb2b 100644
--- a/examples/dogpile_caching/environment.py
+++ b/examples/dogpile_caching/environment.py
@@ -1,6 +1,4 @@
-"""environment.py
-
-Establish data / cache file paths, and configurations,
+"""Establish data / cache file paths, and configurations,
 bootstrap fixture data if necessary.
 
 """
@@ -25,10 +23,10 @@ regions = {}
 # using a callable that will associate the dictionary
 # of regions with the Query.
 Session = scoped_session(
-                sessionmaker(
-                    query_cls=caching_query.query_callable(regions)
-                )
-            )
+    sessionmaker(
+        query_cls=caching_query.query_callable(regions)
+    )
+)
 
 # global declarative base class.
 Base = declarative_base()
@@ -36,10 +34,11 @@ Base = declarative_base()
 root = "./dogpile_data/"
 
 if not os.path.exists(root):
-    input("Will create datafiles in %r.\n"
-                "To reset the cache + database, delete this directory.\n"
-                "Press enter to continue.\n" % root
-                )
+    input(
+        "Will create datafiles in %r.\n"
+        "To reset the cache + database, delete this directory.\n"
+        "Press enter to continue.\n" % root
+    )
     os.makedirs(root)
 
 dbfile = os.path.join(root, "dogpile_demo.db")
@@ -56,20 +55,20 @@ def md5_key_mangler(key):
 
 # configure the "default" cache region.
 regions['default'] = make_region(
-            # the "dbm" backend needs
-            # string-encoded keys
-            key_mangler=md5_key_mangler
-        ).configure(
-        # using type 'file' to illustrate
-        # serialized persistence.  Normally
-        # memcached or similar is a better choice
-        # for caching.
-        'dogpile.cache.dbm',
-        expiration_time=3600,
-        arguments={
-            "filename": os.path.join(root, "cache.dbm")
-        }
-    )
+    # the "dbm" backend needs
+    # string-encoded keys
+    key_mangler=md5_key_mangler
+).configure(
+    # using type 'file' to illustrate
+    # serialized persistence.  Normally
+    # memcached or similar is a better choice
+    # for caching.
+    'dogpile.cache.dbm',
+    expiration_time=3600,
+    arguments={
+        "filename": os.path.join(root, "cache.dbm")
+    }
+)
 
 # optional; call invalidate() on the region
 # once created so that all data is fresh when
@@ -80,6 +79,7 @@ regions['default'] = make_region(
 
 installed = False
 
+
 def bootstrap():
     global installed
     from . import fixture_data
diff --git a/examples/dogpile_caching/fixture_data.py b/examples/dogpile_caching/fixture_data.py
index f93f32fd9..465171891 100644
--- a/examples/dogpile_caching/fixture_data.py
+++ b/examples/dogpile_caching/fixture_data.py
@@ -1,6 +1,4 @@
-"""fixture_data.py
-
-Installs some sample data.   Here we have a handful of postal codes for a few US/
+"""Installs some sample data.   Here we have a handful of postal codes for a few US/
 Canadian cities.   Then, 100 Person records are installed, each with a
 randomly selected postal code.
 
@@ -9,6 +7,7 @@ from .environment import Session, Base
 from .model import City, Country, PostalCode, Person, Address
 import random
 
+
 def install():
     Base.metadata.create_all(Session().bind)
 
@@ -17,9 +16,9 @@ def install():
         ('Montreal', 'Canada', ('H2S 3K9', 'H2B 1V4', 'H7G 2T8')),
         ('Edmonton', 'Canada', ('T5J 1R9', 'T5J 1Z4', 'T5H 1P6')),
         ('New York', 'United States',
-                        ('10001', '10002', '10003', '10004', '10005', '10006')),
+         ('10001', '10002', '10003', '10004', '10005', '10006')),
         ('San Francisco', 'United States',
-                        ('94102', '94103', '94104', '94105', '94107', '94108'))
+         ('94102', '94103', '94104', '94105', '94107', '94108'))
     ]
 
     countries = {}
@@ -37,16 +36,16 @@ def install():
 
     for i in range(1, 51):
         person = Person(
-                    "person %.2d" % i,
-                    Address(
-                        street="street %.2d" % i,
-                        postal_code=all_post_codes[
-                                random.randint(0, len(all_post_codes) - 1)]
-                    )
-                )
+            "person %.2d" % i,
+            Address(
+                street="street %.2d" % i,
+                postal_code=all_post_codes[
+                    random.randint(0, len(all_post_codes) - 1)]
+            )
+        )
         Session.add(person)
 
     Session.commit()
 
     # start the demo fresh
-    Session.remove()
\ No newline at end of file
+    Session.remove()
diff --git a/examples/dogpile_caching/helloworld.py b/examples/dogpile_caching/helloworld.py
index 22d7f97be..0dbde5eaf 100644
--- a/examples/dogpile_caching/helloworld.py
+++ b/examples/dogpile_caching/helloworld.py
@@ -1,6 +1,4 @@
-"""helloworld.py
-
-Illustrate how to load some data, and cache the results.
+"""Illustrate how to load some data, and cache the results.
 
 """
 
@@ -24,9 +22,9 @@ people = Session.query(Person).options(FromCache("default")).all()
 # 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()
+    options(FromCache("default")).\
+    filter(Person.name.between("person 02", "person 12")).\
+    all()
 
 # the data is cached under string structure of the SQL statement, *plus*
 # the bind parameters of the query.    So this query, having
@@ -34,17 +32,17 @@ people_two_through_twelve = Session.query(Person).\
 # previous one, issues new SQL...
 print("loading people five through fifteen")
 people_five_through_fifteen = Session.query(Person).\
-                            options(FromCache("default")).\
-                            filter(Person.name.between("person 05", "person 15")).\
-                            all()
+    options(FromCache("default")).\
+    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")).\
-                            filter(Person.name.between("person 02", "person 12")).\
-                            all()
+    options(FromCache("default")).\
+    filter(Person.name.between("person 02", "person 12")).\
+    all()
 
 
 # invalidate the cache for the three queries we've done.  Recreate
@@ -54,9 +52,9 @@ people_two_through_twelve = Session.query(Person).\
 print("invalidating everything")
 Session.query(Person).options(FromCache("default")).invalidate()
 Session.query(Person).\
-            options(FromCache("default")).\
-            filter(Person.name.between("person 02", "person 12")).invalidate()
+    options(FromCache("default")).\
+    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()
+    options(FromCache("default", "people_on_range")).\
+    filter(Person.name.between("person 05", "person 15")).invalidate()
 
diff --git a/examples/dogpile_caching/local_session_caching.py b/examples/dogpile_caching/local_session_caching.py
index e6c712b4a..633252fc7 100644
--- a/examples/dogpile_caching/local_session_caching.py
+++ b/examples/dogpile_caching/local_session_caching.py
@@ -1,9 +1,6 @@
-"""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.
+"""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.
@@ -16,6 +13,7 @@ with the basic operation of CachingQuery.
 from dogpile.cache.api import CacheBackend, NO_VALUE
 from dogpile.cache.region import register_backend
 
+
 class ScopedSessionBackend(CacheBackend):
     """A dogpile backend which will cache objects locally on
     the current session.
@@ -77,8 +75,8 @@ if __name__ == '__main__':
     # query to load Person by name, with criterion
     # of "person 10"
     q = Session.query(Person).\
-                    options(FromCache("local_session")).\
-                    filter(Person.name == "person 10")
+        options(FromCache("local_session")).\
+        filter(Person.name == "person 10")
 
     # load from DB
     person10 = q.one()
diff --git a/examples/dogpile_caching/model.py b/examples/dogpile_caching/model.py
index 75c0ad28a..3eb02108c 100644
--- a/examples/dogpile_caching/model.py
+++ b/examples/dogpile_caching/model.py
@@ -1,6 +1,4 @@
-"""model.py
-
-The datamodel, which represents Person that has multiple
+"""The datamodel, which represents Person that has multiple
 Address objects, each with PostalCode, City, Country.
 
 Person --(1..n)--> Address
@@ -11,9 +9,10 @@ City --(has a)--> Country
 """
 from sqlalchemy import Column, Integer, String, ForeignKey
 from sqlalchemy.orm import relationship
-from .caching_query import FromCache, RelationshipCache
+from .caching_query import RelationshipCache
 from .environment import Base, bootstrap
 
+
 class Country(Base):
     __tablename__ = 'country'
 
@@ -23,6 +22,7 @@ class Country(Base):
     def __init__(self, name):
         self.name = name
 
+
 class City(Base):
     __tablename__ = 'city'
 
@@ -35,6 +35,7 @@ class City(Base):
         self.name = name
         self.country = country
 
+
 class PostalCode(Base):
     __tablename__ = 'postal_code'
 
@@ -51,6 +52,7 @@ class PostalCode(Base):
         self.code = code
         self.city = city
 
+
 class Address(Base):
     __tablename__ = 'address'
 
@@ -69,10 +71,12 @@ class Address(Base):
         return self.postal_code.country
 
     def __str__(self):
-        return "%s\t"\
-              "%s, %s\t"\
-              "%s" % (self.street, self.city.name,
+        return (
+            "%s\t%s, %s\t%s" % (
+                self.street, self.city.name,
                 self.postal_code.code, self.country.name)
+        )
+
 
 class Person(Base):
     __tablename__ = 'person'
@@ -98,10 +102,10 @@ class Person(Base):
 # which can be applied to Query(), causing the "lazy load"
 # of these attributes to be loaded from cache.
 cache_address_bits = RelationshipCache(PostalCode.city, "default").\
-                and_(
-                    RelationshipCache(City.country, "default")
-                ).and_(
-                    RelationshipCache(Address.postal_code, "default")
-                )
+    and_(
+        RelationshipCache(City.country, "default")
+).and_(
+        RelationshipCache(Address.postal_code, "default")
+)
 
-bootstrap()
\ No newline at end of file
+bootstrap()
diff --git a/examples/dogpile_caching/relationship_caching.py b/examples/dogpile_caching/relationship_caching.py
index 320ced48a..920d696f8 100644
--- a/examples/dogpile_caching/relationship_caching.py
+++ b/examples/dogpile_caching/relationship_caching.py
@@ -1,6 +1,4 @@
-"""relationship_caching.py
-
-Illustrates how to add cache options on
+"""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
@@ -13,16 +11,19 @@ from .model import Person, cache_address_bits
 from sqlalchemy.orm import joinedload
 import os
 
-for p in Session.query(Person).options(joinedload(Person.addresses), cache_address_bits):
+for p in Session.query(Person).options(
+        joinedload(Person.addresses), cache_address_bits):
     print(p.format_full())
 
 
-print("\n\nIf this was the first run of relationship_caching.py, SQL was likely emitted to "\
-        "load postal codes, cities, countries.\n"\
-        "If run a second time, assuming the cache is still valid, "\
-        "only a single SQL statement will run - all "\
-        "related data is pulled from cache.\n"\
-        "To clear the cache, delete the file %r.  \n"\
-        "This will cause a re-load of cities, postal codes and countries on "\
-        "the next run.\n"\
-        % os.path.join(root, 'cache.dbm'))
+print(
+    "\n\nIf this was the first run of relationship_caching.py, "
+    "SQL was likely emitted to "
+    "load postal codes, cities, countries.\n"
+    "If run a second time, assuming the cache is still valid, "
+    "only a single SQL statement will run - all "
+    "related data is pulled from cache.\n"
+    "To clear the cache, delete the file %r.  \n"
+    "This will cause a re-load of cities, postal codes and countries on "
+    "the next run.\n"
+    % os.path.join(root, 'cache.dbm'))
diff --git a/examples/generic_associations/discriminator_on_association.py b/examples/generic_associations/discriminator_on_association.py
index 7bb04cf85..c3501eefb 100644
--- a/examples/generic_associations/discriminator_on_association.py
+++ b/examples/generic_associations/discriminator_on_association.py
@@ -1,6 +1,4 @@
-"""discriminator_on_related.py
-
-Illustrates a mixin which provides a generic association
+"""Illustrates a mixin which provides a generic association
 using a single target table and a single association table,
 referred to by all parent tables.  The association table
 contains a "discriminator" column which determines what type of
diff --git a/examples/generic_associations/generic_fk.py b/examples/generic_associations/generic_fk.py
index e228c6ba4..31d2c138d 100644
--- a/examples/generic_associations/generic_fk.py
+++ b/examples/generic_associations/generic_fk.py
@@ -1,6 +1,4 @@
-"""generic_fk.py
-
-Illustrates a so-called "generic foreign key", in a similar fashion
+"""Illustrates a so-called "generic foreign key", in a similar fashion
 to that of popular frameworks such as Django, ROR, etc.  This
 approach bypasses standard referential integrity
 practices, in that the "foreign key" column is not actually
diff --git a/examples/generic_associations/table_per_association.py b/examples/generic_associations/table_per_association.py
index 4993492a4..d54d2f1fa 100644
--- a/examples/generic_associations/table_per_association.py
+++ b/examples/generic_associations/table_per_association.py
@@ -1,6 +1,4 @@
-"""table_per_association.py
-
-Illustrates a mixin which provides a generic association
+"""Illustrates a mixin which provides a generic association
 via a individually generated association tables for each parent class.
 The associated objects themselves are persisted in a single table
 shared among all parents.
diff --git a/examples/generic_associations/table_per_related.py b/examples/generic_associations/table_per_related.py
index aff6e40ce..51c9f1b26 100644
--- a/examples/generic_associations/table_per_related.py
+++ b/examples/generic_associations/table_per_related.py
@@ -1,6 +1,4 @@
-"""table_per_related.py
-
-Illustrates a generic association which persists association
+"""Illustrates a generic association which persists association
 objects within individual tables, each one generated to persist
 those objects on behalf of a particular parent class.