Commits

Anonymous committed a4272da

3rd attempt to fix the name problem

Comments (0)

Files changed (38)

src/AppFrameworks.rst

+
+*******************************************************************************
+Building Application Frameworks
+*******************************************************************************
+
+An application framework allows you to inherit from a class or set of classes
+and create a new application, reusing most of the code in the existing classes
+and overriding one or more methods in order to customize the application to your
+needs. A fundamental concept in the application framework is the *Template
+Method* which is typically hidden beneath the covers and drives the application
+by calling the various methods in the base class (some of which you have
+overridden in order to create the application).
+
+For example, whenever you create an applet you're using an application
+framework: you inherit from **JApplet** and then override **init( )**. The
+applet mechanism (which is a *Template Method*) does the rest by drawing the
+screen, handling the event loop, resizing, etc.
+
+Template Method
+=======================================================================
+
+An important characteristic of the *Template Method* is that it is defined in
+the base class and cannot be changed. It's sometimes a **private** method but
+it's virtually always **final**. It calls other base-class methods (the ones you
+override) in order to do its job, but it is usually called only as part of an
+initialization process (and thus the client programmer isn't necessarily able to
+call it directly)::
+
+    # appFrameworks/TemplateMethod.py
+    # Simple demonstration of Template Method.
+
+    class ApplicationFramework:
+        def __init__(self):
+            self.__templateMethod()
+        def __templateMethod(self):
+            for i in range(5):
+                self.customize1()
+                self.customize2()
+
+    # Create an "application":
+    class MyApp(ApplicationFramework):
+        def customize1(self):
+            print("Nudge, nudge, wink, wink! ",)
+        def customize2(self):
+            print("Say no more, Say no more!")
+
+    MyApp()
+
+
+
+The base-class constructor is responsible for performing the necessary
+initialization and then starting the "engine" (the template method) that runs
+the application (in a GUI application, this "engine" would be the main event
+loop). The client programmer simply provides definitions for **customize1( )**
+and **customize2( )** and the "application" is ready to run.
+
+We'll see *Template Method* numerous other times throughout the book.
+
+Exercises
+=======================================================================
+
+#.  Create a framework that takes a list of file names on the command line. It
+    opens each file except the last for reading, and the last for writing. The
+    framework will process each input file using an undetermined policy and
+    write the output to the last file. Inherit to customize this framework to
+    create two separate applications:
+
+        #. Converts all the letters in each file to uppercase.
+        #. Searches the files for words given in the first file.
+
+
+

src/CanonicalScript.rst

+..  index::
+    triple: script; command-line; canonical form
+
+****************************************************************************
+A Canonical Form for Command-Line Programs
+****************************************************************************
+
+Creating Python programs for command-line use involves a certain amount of
+repetitious coding, which can often be left off or forgotten. Here is a form
+which includes everthing.
+
+Note that if you are using Windows, you can add Python programs to your "File
+New" menu and automatically include the above text in the new file. `This
+article <http://articles.techrepublic.com.com/5100-10878_11-5034852.html>`_
+shows you how. Other operating systems have their own automation features.

src/ChangeInterface.rst

+
+********************************************************************************
+Changing the Interface
+********************************************************************************
+
+Sometimes the problem that you're solving is as simple as "I don't have the
+interface that I want." Two of the patterns in *Design Patterns* solve this
+problem: *Adapter* takes one type and produces an interface to some other type.
+*Façade* creates an interface to a set of classes, simply to provide a more
+comfortable way to deal with a library or bundle of resources.
+
+Adapter
+=======================================================================
+
+When you've got *this*, and you need *that*, *Adapter* solves the problem. The
+only requirement is to produce a *that*, and there are a number of ways you can
+accomplish this adaptation::
+
+    # changeInterface/Adapter.py
+    # Variations on the Adapter pattern.
+
+    class WhatIHave:
+        def g(self): pass
+        def h(self): pass
+
+    class WhatIWant:
+        def f(self): pass
+
+    class ProxyAdapter(WhatIWant):
+        def __init__(self, whatIHave):
+            self.whatIHave = whatIHave
+
+        def f(self):
+            # Implement behavior using
+            # methods in WhatIHave:
+            self.whatIHave.g()
+            self.whatIHave.h()
+
+    class WhatIUse:
+        def op(self, whatIWant):
+            whatIWant.f()
+
+    # Approach 2: build adapter use into op():
+    class WhatIUse2(WhatIUse):
+        def op(self, whatIHave):
+            ProxyAdapter(whatIHave).f()
+
+    # Approach 3: build adapter into WhatIHave:
+    class WhatIHave2(WhatIHave, WhatIWant):
+        def f(self):
+            self.g()
+            self.h()
+
+    # Approach 4: use an inner class:
+    class WhatIHave3(WhatIHave):
+        class InnerAdapter(WhatIWant):
+            def __init__(self, outer):
+                self.outer = outer
+            def f(self):
+                self.outer.g()
+                self.outer.h()
+
+        def whatIWant(self):
+            return WhatIHave3.InnerAdapter(self)
+
+    whatIUse = WhatIUse()
+    whatIHave = WhatIHave()
+    adapt= ProxyAdapter(whatIHave)
+    whatIUse2 = WhatIUse2()
+    whatIHave2 = WhatIHave2()
+    whatIHave3 = WhatIHave3()
+    whatIUse.op(adapt)
+    # Approach 2:
+    whatIUse2.op(whatIHave)
+    # Approach 3:
+    whatIUse.op(whatIHave2)
+    # Approach 4:
+    whatIUse.op(whatIHave3.whatIWant())
+
+I'm taking liberties with the term "proxy" here, because in *Design Patterns*
+they assert that a proxy must have an identical interface with the object that
+it is a surrogate for. However, if you have the two words together: "proxy
+adapter," it is perhaps more reasonable.
+
+Façade
+=======================================================================
+
+A general principle that I apply when I'm casting about trying to mold
+requirements into a first-cut object is "If something is ugly, hide it inside an
+object." This is basically what *Façade* accomplishes. If you have a rather
+confusing collection of classes and interactions that the client programmer
+doesn't really need to see, then you can create an interface that is useful for
+the client programmer and that only presents what's necessary.
+
+Façade is often implemented as singleton abstract factory. Of course, you can
+easily get this effect by creating a class containing **static** factory
+methods::
+
+    # changeInterface/Facade.py
+    class A:
+        def __init__(self, x): pass
+    class B:
+        def __init__(self, x): pass
+    class C:
+        def __init__(self, x): pass
+
+    # Other classes that aren't exposed by the
+    # facade go here ...
+
+    class Facade:
+        def makeA(x): return A(x)
+        makeA = staticmethod(makeA)
+        def makeB(x): return B(x)
+        makeB = staticmethod(makeB)
+        def makeC(x): return C(x)
+        makeC = staticmethod(makeC)
+
+    # The client programmer gets the objects
+    # by calling the static methods:
+    a = Facade.makeA(1);
+    b = Facade.makeB(1);
+    c = Facade.makeC(1.0);
+
+[rewrite this section using research from Larman's book]
+
+Example for Facade (?): my "nicer" version of the XML library.
+
+Exercises
+=======================================================================
+
+#.  Create an adapter class that automatically loads a two-dimensional array of
+    objects into a dictionary as key-value pairs.
+
+
+

src/Comprehensions.rst

+.. index::
+   pair: list; comprehension
+   pair: generator; comprehension
+
+********************************************************************************
+Comprehensions
+********************************************************************************
+
+History: where did they come from?
+
+They require a mind shift.
+
+What makes them so compelling (once you 'get it')?
+
+A two-level list comprehension using ``os.walk()``::
+
+    # Comprehensions/os_walk_comprehension.py
+    import os
+    restFiles = [os.path.join(d[0], f) for d in os.walk(".")
+                 for f in d[2] if f.endswith(".rst")]
+    for r in restFiles:
+        print(r)
+
+
+A More Complex Example
+==============================================================================
+
+..  note:: This is still under development. After finishing, it will get a full
+           description of all parts.
+
+::
+
+    # CodeManager.py
+    """
+    TODO: update() is still only in test mode; doesn't actually work yet.
+
+    Extracts, checks and updates code examples in ReST files.
+
+    You can just put in the codeMarker and the (indented) first line (containing the
+    file path) into your ReST file, then run the update program to automatically
+    insert the rest of the file.
+    """
+    import os, re, sys, shutil, inspect, difflib
+
+    restFiles = [os.path.join(d[0], f) for d in os.walk(".") if not "_test" in d[0]
+                 for f in d[2] if f.endswith(".rst")]
+
+    class Languages:
+        "Strategy design pattern"
+
+        class Python:
+            codeMarker = "::\n\n"
+            commentTag = "#"
+            listings = re.compile("::\n\n( {4}#.*(?:\n+ {4}.*)*)")
+
+        class Java:
+            codeMarker = "..  code-block:: java\n\n"
+            commentTag = "//"
+            listings = \
+                re.compile(".. *code-block:: *java\n\n( {4}//.*(?:\n+ {4}.*)*)")
+
+    def shift(listing):
+        "Shift the listing left by 4 spaces"
+        return [x[4:] if x.startswith("    ") else x for x in listing.splitlines()]
+
+    # TEST - makes duplicates of the rst files in a test directory to test update():
+    dirs = set([os.path.join("_test", os.path.dirname(f)) for f in restFiles])
+    if [os.makedirs(d) for d in dirs if not os.path.exists(d)]:
+        [shutil.copy(f, os.path.join("_test", f)) for f in restFiles]
+    testFiles = [os.path.join(d[0], f) for d in os.walk("_test")
+                 for f in d[2] if f.endswith(".rst")]
+
+    class Commands:
+        """
+        Each static method can be called from the command line. Add a new static
+        method here to add a new command to the program.
+        """
+
+        @staticmethod
+        def display(language):
+            """
+            Print all the code listings in the .rst files.
+            """
+            for f in restFiles:
+                listings = language.listings.findall(open(f).read())
+                if not listings: continue
+                print('=' * 60 + "\n" + f + "\n" + '=' * 60)
+                for n, l in enumerate(listings):
+                    print("\n".join(shift(l)))
+                    if n < len(listings) - 1:
+                        print('-' * 60)
+
+        @staticmethod
+        def extract(language):
+            """
+            Pull the code listings from the .rst files and write each
+            listing into its own file.
+            """
+            paths = set()
+            for f in restFiles:
+                for listing in language.listings.findall(open(f).read()):
+                    listing = shift(listing)
+                    path = listing[0][len(language.commentTag):].strip()
+                    if path in paths:
+                        print("ERROR: Duplicate file name: %s" % path)
+                        sys.exit(1)
+                    else:
+                        paths.add(path)
+                    path = os.path.join("..", "code", path)
+                    dirname = os.path.dirname(path)
+                    if dirname:
+                        if not os.path.exists(dirname):
+                            os.makedirs(dirname)
+                    file(path, 'w').write("\n".join(listing))
+
+        @staticmethod
+        def check(language):
+            """
+            Ensure that external code files exist and check which external files
+            have changed from what's in the .rst files. Generate files in the
+            _deltas subdirectory showing what has changed.
+            """
+            missing = []
+            listings = [shift(code) for f in restFiles for code in
+                        language.listings.findall(open(f).read())]
+            paths = [os.path.normpath(os.path.join("..", "code", path)) for path in
+                        [listing[0].strip()[len(language.commentTag):].strip()
+                         for listing in listings]]
+            for path, listing in zip(paths, listings):
+                if not os.path.exists(path):
+                    missing.append(path)
+                else:
+                    code = open(path).read().splitlines()
+                    for i in difflib.ndiff(listing, code):
+                        if i.startswith("+ ") or i.startswith("- "):
+                            d = difflib.HtmlDiff()
+                            if not os.path.exists("_deltas"):
+                                os.makedirs("_deltas")
+                            html = os.path.join("_deltas",
+                                os.path.basename(path).split('.')[0] + ".html")
+                            open(html, 'w').write(d.make_file(listing, code))
+                            print("change in %s; see %s" % (path, html))
+                            break
+            if missing:
+                print("Missing", language.__name__, "files:\n", "\n".join(missing))
+            return missing
+
+        @staticmethod
+        def update(language): # Test until it is trustworthy
+            """
+            Refresh external code files into ReST files.
+            """
+            if Commands.check(language):
+                print(language.__name__, "update aborted")
+                return
+            def _update(matchobj):
+                listing = shift(matchobj.group(1))
+                path = listing[0].strip()[len(language.commentTag):].strip()
+                filename = os.path.basename(path).split('.')[0]
+                path = os.path.join("..", "code", path)
+                code = open(path).read().splitlines()
+                return language.codeMarker + \
+                    "\n".join([("    " + line).rstrip() for line in listing])
+            for f in testFiles:
+                updated = language.listings.sub(_update, open(f).read())
+                open(f, 'w').write(updated)
+
+    if __name__ == "__main__":
+        commands = dict(inspect.getmembers(Commands, inspect.isfunction))
+        if len(sys.argv) < 2 or sys.argv[1] not in commands:
+            print("Command line options:\n")
+            for name in commands:
+                print(name + ": " + commands[name].__doc__)
+        else:
+            for language in inspect.getmembers(Languages, inspect.isclass):
+                commands[sys.argv[1]](language[1])
+
+           

src/Contributors.rst

+*******************************************************************************
+Contributors
+*******************************************************************************
+
+List of contributors.
+
+..  Note::  This needs some thought. I want to include everyone who makes a
+            contribution, but I'd also like to indicate people who have made
+            larger contributions -- there's no automatic way to do this now
+            that we have moved to BitBucket and are using Wikis to allow people
+            to make contributions more simply in the beginning.
+
+Thanks To
+===============================================================================
+
+  * BitBucket.org and the creators of Mercurial
+
+  * Creator(s) of Sphinx
+
+  * And of course, Guido and the team for their incessant improvement of Python,
+    especially for taking the risk in breaking backward compatibility in Python
+    3.0 to refactor the language.
+ 
+
+===============================================================================
+
+.. todo:: Yarko (example label of ToDo):
+
+    - update CSS styles for todo's & todo lists;
+    - look at http://sphinx.pocoo.org/ext/coverage.html for example.
+    - Autogenerated ToDoLists do not appear in LaTeX output - debug, fix;
+    - DONE:
+      - ToDo does not appear to be created by make dependencies (it's autogenerated);
+      - update Makefile to always re-generate todo lists;
+     
+
+

src/CoroutinesAndConcurrency.rst

+.. index::
+   coroutines
+   concurrency
+   threads
+   parallelism
+   multiprocessing
+   GIL: Global Interpreter Lock
+
+********************************************************************************
+Coroutines & Concurrency
+********************************************************************************
+
+Primary focus should be on:
+
+1) Using ``yield`` to create coroutines
+
+2) Using the new ``multiprocessing`` module
+
+and then showing some alternative techniques.
+
+foo bar :func:`input` baz.
+
+Further Reading
+================================================================================
+
+    `This article
+    <http://guidewiredevelopment.wordpress.com/2008/10/06/a-more-clearly-stated-version-of-my-argument/>`_
+    argues that large-scale parallelism -- which is what
+    ``multiprocessing`` supports -- is the more important problem to solve, and
+    that functional languages don't help that much with this problem.
+
+        

src/Decorator.rst

+********************************************************************************
+Decorator: Dynamic Type Selection
+********************************************************************************
+
+..  note:: I think we can rewrite this chapter to use Python decorators as
+           implementation (thus the decorators chapter should precede this one).
+
+The use of layered objects to dynamically and transparently add responsibilities
+to individual objects is referred to as the *decorator* pattern.
+
+Used when subclassing creates too many (& inflexible) classes
+
+All decorators that wrap around the original object must have the same basic
+interface
+
+Dynamic proxy/surrogate?
+
+This accounts for the odd inheritance structure
+
+Tradeoff: coding is more complicated when using decorators
+
+Basic Decorator Structure
+=======================================================================
+
+.. image:: _images/decorator.*
+
+
+A Coffee Example
+=======================================================================
+
+Consider going down to the local coffee shop, *BeanMeUp*, for a coffee.  There
+are typically many different drinks on offer -- espressos, lattes, teas, iced
+coffees, hot chocolate to name a few, as well as a number of extras (which cost
+extra too) such as whipped cream or an extra shot of espresso. You can also make
+certain changes to your drink at no extra cost, such as asking for decaf coffee
+instead of regular coffee.
+
+Quite clearly if we are going to model all these drinks and combinations, there
+will be sizeable class diagrams. So for clarity we will only consider a subset
+of the coffees: Espresso, Espresso Con Panna, Café Late, Cappuccino and Café
+Mocha. We'll include 2 extras - whipped cream ("whipped") and an extra shot of
+espresso; and three changes - decaf, steamed milk ("wet") and foamed milk
+("dry").
+
+Class for Each Combination
+=======================================================================
+
+One solution is to create an individual class for every combination. Each class
+describes the drink and is responsible for the cost etc. The resulting menu is
+huge, and a part of the class diagram would look something like this:
+
+.. image:: _images/coffeeExplosion.*
+
+The key to using this method is to find the particular combination you want.
+So, once you've found the drink you would like, here is how you would use it, as
+shown in the **CoffeeShop** class in the following code::
+
+    # decorator/nodecorators/CoffeeShop.py
+    # Coffee example with no decorators
+
+    class Espresso: pass
+    class DoubleEspresso: pass
+    class EspressoConPanna: pass
+
+    class Cappuccino:
+        def __init__(self):
+            self.cost = 1
+            self.description = "Cappucino"
+        def getCost(self):
+            return self.cost
+        def getDescription(self):
+            return self.description
+
+    class CappuccinoDecaf: pass
+    class CappuccinoDecafWhipped: pass
+    class CappuccinoDry: pass
+    class CappuccinoDryWhipped: pass
+    class CappuccinoExtraEspresso: pass
+    class CappuccinoExtraEspressoWhipped: pass
+    class CappuccinoWhipped: pass
+
+    class CafeMocha: pass
+    class CafeMochaDecaf: pass
+    class CafeMochaDecafWhipped:
+        def __init__(self):
+            self.cost = 1.25
+            self.description = \
+              "Cafe Mocha decaf whipped cream"
+        def getCost(self):
+            return self.cost
+        def getDescription(self):
+            return self.description
+
+    class CafeMochaExtraEspresso: pass
+    class CafeMochaExtraEspressoWhipped: pass
+    class CafeMochaWet: pass
+    class CafeMochaWetWhipped: pass
+    class CafeMochaWhipped: pass
+
+    class CafeLatte: pass
+    class CafeLatteDecaf: pass
+    class CafeLatteDecafWhipped: pass
+    class CafeLatteExtraEspresso: pass
+    class CafeLatteExtraEspressoWhipped: pass
+    class CafeLatteWet: pass
+    class CafeLatteWetWhipped: pass
+    class CafeLatteWhipped: pass
+
+    cappuccino = Cappuccino()
+    print((cappuccino.getDescription() + ": $" +
+      `cappuccino.getCost()`))
+
+    cafeMocha = CafeMochaDecafWhipped()
+    print((cafeMocha.getDescription()
+      + ": $" + `cafeMocha.getCost()`))
+
+
+
+And here is the corresponding output::
+
+    Cappucino: $1.0
+    Cafe Mocha decaf whipped cream: $1.25
+
+You can see that creating the particular combination you want is easy, since you
+are just creating an instance of a class. However, there are a number of
+problems with this approach. Firstly, the combinations are fixed statically so
+that any combination a customer may wish to order needs to be created up front.
+Secondly, the resulting menu is so huge that finding your particular combination
+is difficult and time consuming.
+
+The Decorator Approach
+=======================================================================
+
+Another approach would be to break the drinks down into the various components
+such as espresso and foamed milk, and then let the customer combine the
+components to describe a particular coffee.
+
+In order to do this programmatically, we use the Decorator pattern.  A Decorator
+adds responsibility to a component by wrapping it, but the Decorator conforms to
+the interface of the component it encloses, so the wrapping is transparent.
+Decorators can also be nested without the loss of this transparency.
+
+.. image:: _images/decoratedCoffee.*
+
+
+Methods invoked on the Decorator can in turn invoke methods in the component,
+and can of course perform processing before or after the invocation.
+
+So if we added **getTotalCost()** and **getDescription()** methods to the
+**DrinkComponent** interface, an Espresso looks like this::
+
+    # decorator/alldecorators/EspressoDecorator.py
+
+    class Espresso(Decorator):
+        cost = 0.75f
+        description = " espresso"
+        def __init__(DrinkComponent):
+            Decorator.__init__(self, component)
+
+        def getTotalCost(self):
+            return self.component.getTotalCost() + cost
+
+        def getDescription(self):
+            return self.component.getDescription() +
+                description
+
+
+You combine the components to create a drink as follows, as shown in the code
+below::
+
+    # decorator/alldecorators/CoffeeShop.py
+    # Coffee example using decorators
+
+    class DrinkComponent:
+        def getDescription(self):
+            return self.__class__.__name__
+        def getTotalCost(self):
+            return self.__class__.cost
+
+    class Mug(DrinkComponent):
+        cost = 0.0
+
+    class Decorator(DrinkComponent):
+        def __init__(self, drinkComponent):
+            self.component = drinkComponent
+        def getTotalCost(self):
+            return self.component.getTotalCost() + \
+              DrinkComponent.getTotalCost(self)
+        def getDescription(self):
+            return self.component.getDescription() + \
+              ' ' + DrinkComponent.getDescription(self)
+
+    class Espresso(Decorator):
+        cost = 0.75
+        def __init__(self, drinkComponent):
+            Decorator.__init__(self, drinkComponent)
+
+    class Decaf(Decorator):
+        cost = 0.0
+        def __init__(self, drinkComponent):
+            Decorator.__init__(self, drinkComponent)
+
+    class FoamedMilk(Decorator):
+        cost = 0.25
+        def __init__(self, drinkComponent):
+            Decorator.__init__(self, drinkComponent)
+
+    class SteamedMilk(Decorator):
+        cost = 0.25
+        def __init__(self, drinkComponent):
+            Decorator.__init__(self, drinkComponent)
+
+    class Whipped(Decorator):
+        cost = 0.25
+        def __init__(self, drinkComponent):
+            Decorator.__init__(self, drinkComponent)
+
+    class Chocolate(Decorator):
+        cost = 0.25
+        def __init__(self, drinkComponent):
+            Decorator.__init__(self, drinkComponent)
+
+    cappuccino = Espresso(FoamedMilk(Mug()))
+    print(cappuccino.getDescription().strip() + \)
+      ": $" + `cappuccino.getTotalCost()`
+
+    cafeMocha = Espresso(SteamedMilk(Chocolate(
+      Whipped(Decaf(Mug())))))
+
+    print(cafeMocha.getDescription().strip() + \)
+      ": $" + `cafeMocha.getTotalCost()`
+
+
+
+This approach would certainly provide the most flexibility and the smallest
+menu. You have a small number of components to choose from, but assembling the
+description of the coffee then becomes rather arduous.
+
+If you want to describe a plain cappuccino, you create it with::
+
+    plainCap = Espresso(FoamedMilk(Mug()))
+
+Creating a decaf Cafe Mocha with whipped cream requires an even longer
+description.
+
+Compromise
+=======================================================================
+
+The previous approach takes too long to describe a coffee. There will also be
+certain combinations that you will describe regularly, and it would be
+convenient to have a quick way of describing them.
+
+The 3rd approach is a mixture of the first 2 approaches, and combines
+flexibility with ease of use. This compromise is achieved by creating a
+reasonably sized menu of basic selections, which would often work exactly as
+they are, but if you wanted to decorate them (whipped cream, decaf etc.) then
+you would use decorators to make the modifications. This is the type of menu you
+are presented with in most coffee shops.
+
+.. image:: _images/compromiseDecoration.*
+
+Here is how to create a basic selection, as well as a decorated selection::
+
+    # decorator/compromise/CoffeeShop.py
+    # Coffee example with a compromise of basic
+    # combinations and decorators
+
+    class DrinkComponent:
+        def getDescription(self):
+            return self.__class__.__name__
+        def getTotalCost(self):
+            return self.__class__.cost
+
+    class Espresso(DrinkComponent):
+        cost = 0.75
+
+    class EspressoConPanna(DrinkComponent):
+        cost = 1.0
+
+    class Cappuccino(DrinkComponent):
+        cost = 1.0
+
+    class CafeLatte(DrinkComponent):
+        cost = 1.0
+
+    class CafeMocha(DrinkComponent):
+        cost = 1.25
+
+    class Decorator(DrinkComponent):
+        def __init__(self, drinkComponent):
+            self.component = drinkComponent
+        def getTotalCost(self):
+            return self.component.getTotalCost() + \
+              DrinkComponent.getTotalCost(self)
+        def getDescription(self):
+            return self.component.getDescription() + \
+              ' ' + DrinkComponent.getDescription(self)
+
+    class ExtraEspresso(Decorator):
+        cost = 0.75
+        def __init__(self, drinkComponent):
+            Decorator.__init__(self, drinkComponent)
+
+    class Whipped(Decorator):
+        cost = 0.50
+        def __init__(self, drinkComponent):
+            Decorator.__init__(self, drinkComponent)
+
+    class Decaf(Decorator):
+        cost = 0.0
+        def __init__(self, drinkComponent):
+            Decorator.__init__(self, drinkComponent)
+
+    class Dry(Decorator):
+        cost = 0.0
+        def __init__(self, drinkComponent):
+            Decorator.__init__(self, drinkComponent)
+
+    class Wet(Decorator):
+        cost = 0.0
+        def __init__(self, drinkComponent):
+            Decorator.__init__(self, drinkComponent)
+
+    cappuccino = Cappuccino()
+    print(cappuccino.getDescription() + ": $" + \)
+      `cappuccino.getTotalCost()`
+
+    cafeMocha = Whipped(Decaf(CafeMocha()))
+    print(cafeMocha.getDescription() + ": $" + \)
+      `cafeMocha.getTotalCost()`
+
+
+
+You can see that creating a basic selection is quick and easy, which makes sense
+since they will be described regularly.  Describing a decorated drink is more
+work than when using a class per combination, but clearly less work than when
+only using decorators.
+
+The final result is not too many classes, but not too many decorators either.
+Most of the time it's possible to get away without using any decorators at all,
+so we have the benefits of both approaches.
+
+Other Considerations
+=======================================================================
+
+What happens if we decide to change the menu at a later stage, such as by adding
+a new type of drink? If we had used the class per combination approach, the
+effect of adding an extra such as syrup would be an exponential growth in the
+number of classes. However, the implications to the all decorator or compromise
+approaches are the same - one extra class is created.
+
+How about the effect of changing the cost of steamed milk and foamed milk, when
+the price of milk goes up? Having a class for each combination means that you
+need to change a method in each class, and thus maintain many classes. By using
+decorators, maintenance is reduced by defining the logic in one place.
+
+Exercises
+=======================================================================
+
+#.  Add a Syrup class to the decorator approach described above. Then create a
+    Café Latte (you'll need to use steamed milk with an espresso) with syrup.
+
+#.  Repeat Exercise 1 for the compromise approach.
+
+#.  Implement the decorator pattern to create a Pizza restaurant, which has a
+    set menu of choices as well as the option to design your own pizza.  Follow
+    the compromise approach to create a menu consisting of a Margherita,
+    Hawaiian, Regina, and Vegetarian pizzas, with toppings (decorators) of
+    Garlic, Olives, Spinach, Avocado, Feta and Pepperdews. Create a Hawaiian
+    pizza, as well as a Margherita decorated with Spinach, Feta, Pepperdews and
+    Olives.

src/DeveloperGuide.rst

+*******************************************************************************
+Developer Guide
+*******************************************************************************
+
+Details for people participating in the book development process.
+
+Getting Started: The Easiest Approach
+===============================================================================
+
+If all of the details are a little overwhelming at first, there's an easy way
+for you to make contributions without learning about distributed version control
+and Sphinx:
+
+1.  Create an account at http://www.BitBucket.org.
+
+2.  In your account, you get a wiki. In your wiki, create a page for your
+    contribution. Just add your code and descriptions using plain text.
+
+3.  Point us to your wiki via the `newsgroup
+    <http://groups.google.com/group/python3patterns/>`_.
+
+4.  We'll take your contribution and do the necessary formatting.
+
+If you want to take another step, you can learn how to format your wiki page
+using Sphinx by looking at the source for pages in the book. You can try it
+right now -- on the left side of this page (in the HTML book) you'll see a
+header that says **This Page** and underneath it **Show Source**. Click on
+**Show Source** and you'll see the Sphinx source for this page. Just look at
+the page sources and imitate that.
+
+When you're ready, you can learn more about Sphinx and Mercurial and begin
+making contributions that way.
+
+The following sections are for those who are ready to build the book on their
+own machines.
+
+For Windows Users
+===============================================================================
+
+You need to install Cygwin; go to:
+
+    http://www.cygwin.com
+
+You need to install at least the ``make`` utility, but I find that ``chere``
+(command prompt here) is also very useful.
+
+Also install ``openssh`` (under **Net**), so you can create your RSA key
+for Mercurial.
+
+I've discovered that it's best if you *don't* install Python as part of
+Cygwin; instead use a single Python installation under windows. Cygwin will
+find the installation if it is on your Windows PATH.
+
+Because of this, you shouldn't select "mercurial" when you're
+installing Cygwin because that will cause Python to be installed. Instead,
+install them as standalone Windows applications (see below).
+
+Installing Sphinx
+===============================================================================
+
+Because we are sometimes pushing the boundaries of Sphinx, you'll need to get
+the very latest development version (a.k.a. the "tip").
+
+#. Get mercurial:
+
+    http://www.selenic.com/mercurial
+
+    Avoid installing the tortoiseHG part - it has caused trouble w/ Python
+    debuggers.
+
+#. To get the Sphinx trunk, start with:
+
+    ``$ hg clone http://www.bitbucket.org/birkenfeld/sphinx/``
+
+    and to update, use:
+
+    ``$ hg pull``
+
+    Once you update, run
+
+    ``$ python setup.py install``
+
+    (You can repeat this step whenever you need to update).
+
+    We may talk about minimum version numbers to process the book. Check your
+    version with:
+
+    ``$ hg identify -n``
+
+The full anouncement from Georg (Sphinx creator) is here:
+
+    http://groups.google.com/group/sphinx-dev/browse_thread/thread/6dd415847e5cbf7c
+
+Mercurial Cheat sheets & quick starts should be enough to answer your questions:
+
+    - http://edong.net/2008v1/docs/dongwoo-Hg-120dpi.png
+    - http://www.ivy.fr/mercurial/ref/v1.0/
+
+Getting the Development Branch of the Book
+===============================================================================
+
+This book uses BitBucket.org tools, and additional tools if necessary.
+
+#.  Sign up for an account at http://BitBucket.org.
+
+#.  You must create an rsa key. Under OSX and Linux, and if you installed
+    ``openssh with`` Cygwin under windows, you run ``ssh-keygen`` to generate
+    the key, and then add it to your BitBucket account.
+
+#.  Go to http://www.bitbucket.org/BruceEckel/python-3-patterns-idioms/, and
+    you'll see instructions for getting a branch for development.
+
+#.  Work on your branch and make local commits and commits to your BitBucket
+    account.
+
+Building the Book
+===============================================================================
+
+To ensure you have Cygwin installed correctly (if you're using windows) and
+to see what the options are, type:
+
+    ``make``
+
+at a shell prompt. Then you can use ``make html`` to build the HTML version of
+the book, or ``make htmlhelp`` to make the windows help version, etc.
+
+You can also use the ``build`` system I've created (as a book example; it is
+part of the distribution). This will call ``make`` and it simplifies many of the
+tasks involved. Type:
+
+    ``build help``
+
+to see the options.
+
+.. todo::   The remainder of this document needs rewriting. Rewrite this section
+            for BitBucket & Mercurial; make some project specific diagrams;
+
+Working with BitBucket and Mercurial
+===============================================================================
+
+.. note:: Adapted from a posting by Yarko Tymciurak
+
+
+This assumes that you have created a local branch on your private machine where
+you do work, and keep it merged with the trunk.
+
+That is, you've done:
+
+   - Forked a branch of http://www.bitbucket.org/BruceEckel/python-3-patterns-idioms/ (the main trunk; this fork will provide a place for review and comment)
+   - cloned the trunk to your local machine:
+     - hg clone https://my_login@bitbucket.org/BruceEckel/python-3-patterns-idioms/
+   - cloned your local copy of trunk to create a working directory:
+     - hg clone python-3-patterns-idioms devel
+
+.. ToDo:: This section still work in progress:
+
+   - ``hg branch lp:python3patterns``
+   - ``hg commit -m 'initial checkout'``
+   - (hack, hack, hack....)
+   - ``hg merge``   (pull new updates)
+   - ``hg commit -m 'checkin after merge...'``
+   - ... and so on...
+
+When you have a new function idea, or think you've found a bug, ask Bruce
+on the group.
+
+   -  If you have a new feature, register a blueprint on BitBucket and
+      describe what you're going to do.
+   -  If you have found a bug, make a bug report on BitBucket (later assign
+      it to yourself, and link your branch to it);
+   -  If you want to work on a project, look for an unassigned bug and try to
+      work it out - then proceed as below...
+
+When you are ready to share your work have others review, register a branch.
+
+
+.. note:: You can re-use one branch for multiple bug fixes.
+
+1.  Sign up for an account on BitBucket.org
+
+2.  Go to the project and select "register branch"
+    (``https://code.BitBucket.org/python3patterns/+addbranch``). Suggest you
+    create a hosted branch, then you can work locally, and pull/push as you make
+    progress (see
+    http://doc.Mercurial-vcs.org/latest/en/user-guide/index.html#organizing).
+
+3.  Once you have registered your branch, BitBucket will provide you with
+    instructions on how to pull and push to your personal development copy.
+
+4.  Link your bug report or blueprint to your branch.
+
+5.  Merge from your "parent" (the trunk, or others you are working with) as needed.
+
+6.  Push your working copy to BitBucket as your work is ready for others to
+    review or test.
+
+7.  Once you are done making your changes, have completed testing, and are
+    ready for the project team to inspect & test, please select "propose for
+    merging"
+
+8.  Somebody on the core team will make a test merge (it may include
+    merging with other patches). Once tests pass, and your branch is accepted,
+    it will be merged into the trunk.
+
+A Simple Overview Of Editing and Merging
+===============================================================================
+
+#.  ``hg pull http://www.bitbucket.org/BruceEckel/python-3-patterns-idioms/``
+
+#.  ``hg merge`` This brought up kdiff3 (note: this requires a separate
+    installation     of **kdiff3**)on any file's w/ conflicts, and you get to
+    just visually look - left-to-right at A:base, B:mine, and C:yours.... the
+    NICE thing is when you want BOTH the other and yours, you can click BOTH B &
+    C buttons --- sweeet! you can also review the "automatic" merges, choose
+    which - conflicts only, or any merge.
+
+#.  ... ``make html;  make latex`` ...... look at outputs (simultaneously,
+    comparatively)... make any changes.... repeat....
+
+#.  ``hg ci`` without a message, it brought up an editor with a list of all
+    changed files - so you can comment individually.
+
+
+********************************************************************************
+Factory: Encapsulating Object Creation
+********************************************************************************
+
+When you discover that you need to add new types to a system, the most sensible
+first step is to use polymorphism to create a common interface to those new
+types. This separates the rest of the code in your system from the knowledge of
+the specific types that you are adding. New types may be added without
+disturbing existing code ... or so it seems. At first it would appear that the
+only place you need to change the code in such a design is the place where you
+inherit a new type, but this is not quite true. You must still create an object
+of your new type, and at the point of creation you must specify the exact
+constructor to use. Thus, if the code that creates objects is distributed
+throughout your application, you have the same problem when adding new types-you
+must still chase down all the points of your code where type matters. It happens
+to be the *creation* of the type that matters in this case rather than the *use*
+of the type (which is taken care of by polymorphism), but the effect is the
+same: adding a new type can cause problems.
+
+The solution is to force the creation of objects to occur through a common
+*factory* rather than to allow the creational code to be spread throughout your
+system. If all the code in your program must go through this factory whenever it
+needs to create one of your objects, then all you must do when you add a new
+object is to modify the factory.
+
+Since every object-oriented program creates objects, and since it's very likely
+you will extend your program by adding new types, I suspect that factories may
+be the most universally useful kinds of design patterns.
+
+Simple Factory Method
+=======================================================================
+
+As an example, let's revisit the **Shape** system.
+
+One approach is to make the factory a **static** method of the base class::
+
+    # factory/shapefact1/ShapeFactory1.py
+    # A simple static factory method.
+    from __future__ import generators
+    import random
+
+    class Shape(object):
+        # Create based on class name:
+        def factory(type):
+            #return eval(type + "()")
+            if type == "Circle": return Circle()
+            if type == "Square": return Square()
+            assert 0, "Bad shape creation: " + type
+        factory = staticmethod(factory)
+
+    class Circle(Shape):
+        def draw(self): print("Circle.draw")
+        def erase(self): print("Circle.erase")
+
+    class Square(Shape):
+        def draw(self): print("Square.draw")
+        def erase(self): print("Square.erase")
+
+    # Generate shape name strings:
+    def shapeNameGen(n):
+        types = Shape.__subclasses__()
+        for i in range(n):
+            yield random.choice(types).__name__
+
+    shapes = \
+      [ Shape.factory(i) for i in shapeNameGen(7)]
+
+    for shape in shapes:
+        shape.draw()
+        shape.erase()
+
+
+
+The **factory( )** takes an argument that allows it to determine what type of
+**Shape** to create; it happens to be a **String** in this case but it could be
+any set of data. The **factory( )** is now the only other code in the system
+that needs to be changed when a new type of **Shape** is added (the
+initialization data for the objects will presumably come from somewhere outside
+the system, and not be a hard-coded array as in the above example).
+
+Note that this example also shows the new Python 2.2 **staticmethod( )**
+technique for creating static methods in a class.
+
+I have also used a tool which is new in Python 2.2 called a *generator*. A
+generator is a special case of a factory: it's a factory that takes no arguments
+in order to create a new object. Normally you hand some information to a factory
+in order to tell it what kind of object to create and how to create it, but a
+generator has some kind of internal algorithm that tells it what and how to
+build. It "generates out of thin air" rather than being told what to create.
+
+Now, this may not look consistent with the code you see above::
+
+    for i in shapeNameGen(7)
+
+looks like there's an initialization taking place. This is where a generator is
+a bit strange - when you call a function that contains a **yield** statement
+(**yield** is a new keyword that determines that a function is a generator),
+that function actually returns a generator object that has an iterator. This
+iterator is implicitly used in the **for** statement above, so it appears that
+you are iterating through the generator function, not what it returns. This was
+done for convenience of use.
+
+Thus, the code that you write is actually a kind of factory, that creates the
+generator objects that do the actual generation. You can use the generator
+explicitly if you want, for example::
+
+    gen = shapeNameGen(7)
+    print(gen.next())
+
+So **next( )** is the iterator method that's actually called to generate the
+next object, and it takes no arguments. **shapeNameGen( )** is the factory, and
+**gen** is the generator.
+
+Inside the generator-factory, you can see the call to **__subclasses__( )**,
+which produces a list of references to each of the subclasses of **Shape**
+(which must be inherited from **object** for this to work). You should be aware,
+however, that this only works for the first level of inheritance from **Item**,
+so if you were to inherit a new class from **Circle**, it wouldn't show up in
+the list generated by **__subclasses__( )**. If you need to create a deeper
+hierarchy this way, you must recurse the **__subclasses__( )** list.
+
+Also note that in **shapeNameGen( )** the statement::
+
+    types = Shape.__subclasses__()
+
+Is only executed when the generator object is produced; each time the **next(
+)** method of this generator object is called (which, as noted above, may happen
+implicitly), only the code in the **for** loop will be executed, so you don't
+have wasteful execution (as you would if this were an ordinary function).
+
+Preventing direct creation
+--------------------------------------------------------------------------------
+
+To disallow direct access to the classes, you can nest the classes within the
+factory method, like this::
+
+    # factory/shapefact1/NestedShapeFactory.py
+    import random
+
+    class Shape(object):
+        types = []
+
+    def factory(type):
+        class Circle(Shape):
+            def draw(self): print("Circle.draw")
+            def erase(self): print("Circle.erase")
+
+        class Square(Shape):
+            def draw(self): print("Square.draw")
+            def erase(self): print("Square.erase")
+
+        if type == "Circle": return Circle()
+        if type == "Square": return Square()
+        assert 0, "Bad shape creation: " + type
+
+    def shapeNameGen(n):
+        for i in range(n):
+            yield factory(random.choice(["Circle", "Square"]))
+
+    # Circle() # Not defined
+
+    for shape in shapeNameGen(7):
+        shape.draw()
+        shape.erase()
+
+
+
+
+Polymorphic Factories
+=======================================================================
+
+The static **factory( )** method in the previous example forces all the creation
+operations to be focused in one spot, so that's the only place you need to
+change the code. This is certainly a reasonable solution, as it throws a box
+around the process of creating objects. However, the *Design Patterns* book
+emphasizes that the reason for the *Factory Method* pattern is so that different
+types of factories can be subclassed from the basic factory (the above design is
+mentioned as a special case). However, the book does not provide an example, but
+instead just repeats the example used for the *Abstract Factory* (you'll see an
+example of this in the next section). Here is **ShapeFactory1.py** modified so
+the factory methods are in a separate class as virtual functions. Notice also
+that the specific **Shape** classes are dynamically loaded on demand::
+
+    # factory/shapefact2/ShapeFactory2.py
+    # Polymorphic factory methods.
+    from __future__ import generators
+    import random
+
+    class ShapeFactory:
+        factories = {}
+        def addFactory(id, shapeFactory):
+            ShapeFactory.factories.put[id] = shapeFactory
+        addFactory = staticmethod(addFactory)
+        # A Template Method:
+        def createShape(id):
+            if not ShapeFactory.factories.has_key(id):
+                ShapeFactory.factories[id] = \
+                  eval(id + '.Factory()')
+            return ShapeFactory.factories[id].create()
+        createShape = staticmethod(createShape)
+
+    class Shape(object): pass
+
+    class Circle(Shape):
+        def draw(self): print("Circle.draw")
+        def erase(self): print("Circle.erase")
+        class Factory:
+            def create(self): return Circle()
+
+    class Square(Shape):
+        def draw(self):
+            print("Square.draw")
+        def erase(self):
+            print("Square.erase")
+        class Factory:
+            def create(self): return Square()
+
+    def shapeNameGen(n):
+        types = Shape.__subclasses__()
+        for i in range(n):
+            yield random.choice(types).__name__
+
+    shapes = [ ShapeFactory.createShape(i)
+               for i in shapeNameGen(7)]
+
+    for shape in shapes:
+        shape.draw()
+        shape.erase()
+
+
+
+Now the factory method appears in its own class, **ShapeFactory**, as the
+**create( )** method. The different types of shapes must each create their own
+factory with a **create( )** method to create an object of their own type. The
+actual creation of shapes is performed by calling **ShapeFactory.createShape(
+)**, which is a static method that uses the dictionary in **ShapeFactory** to
+find the appropriate factory object based on an identifier that you pass it. The
+factory is immediately used to create the shape object, but you could imagine a
+more complex problem where the appropriate factory object is returned and then
+used by the caller to create an object in a more sophisticated way. However, it
+seems that much of the time you don't need the intricacies of the polymorphic
+factory method, and a single static method in the base class (as shown in
+**ShapeFactory1.py**) will work fine.
+
+Notice that the **ShapeFactory** must be initialized by loading its dictionary
+with factory objects, which takes place in the static initialization clause of
+each of the shape implementations.
+
+Abstract Factories
+=======================================================================
+
+The *Abstract Factory* pattern looks like the factory objects we've seen
+previously, with not one but several factory methods. Each of the factory
+methods creates a different kind of object. The idea is that at the point of
+creation of the factory object, you decide how all the objects created by that
+factory will be used. The example given in *Design Patterns* implements
+portability across various graphical user interfaces (GUIs): you create a
+factory object appropriate to the GUI that you're working with, and from then on
+when you ask it for a menu, button, slider, etc. it will automatically create
+the appropriate version of that item for the GUI. Thus you're able to isolate,
+in one place, the effect of changing from one GUI to another.
+
+As another example suppose you are creating a general-purpose gaming environment
+and you want to be able to support different types of games. Here's how it might
+look using an abstract factory::
+
+    # factory/Games.py
+    # An example of the Abstract Factory pattern.
+
+    class Obstacle:
+        def action(self): pass
+
+    class Character:
+        def interactWith(self, obstacle): pass
+
+    class Kitty(Character):
+        def interactWith(self, obstacle):
+            print("Kitty has encountered a",
+            obstacle.action())
+
+    class KungFuGuy(Character):
+        def interactWith(self, obstacle):
+            print("KungFuGuy now battles a",
+            obstacle.action())
+
+    class Puzzle(Obstacle):
+        def action(self):
+            print("Puzzle")
+
+    class NastyWeapon(Obstacle):
+        def action(self):
+            print("NastyWeapon")
+
+    # The Abstract Factory:
+    class GameElementFactory:
+        def makeCharacter(self): pass
+        def makeObstacle(self): pass
+
+    # Concrete factories:
+    class KittiesAndPuzzles(GameElementFactory):
+        def makeCharacter(self): return Kitty()
+        def makeObstacle(self): return Puzzle()
+
+    class KillAndDismember(GameElementFactory):
+        def makeCharacter(self): return KungFuGuy()
+        def makeObstacle(self): return NastyWeapon()
+
+    class GameEnvironment:
+        def __init__(self, factory):
+            self.factory = factory
+            self.p = factory.makeCharacter()
+            self.ob = factory.makeObstacle()
+        def play(self):
+            self.p.interactWith(self.ob)
+
+    g1 = GameEnvironment(KittiesAndPuzzles())
+    g2 = GameEnvironment(KillAndDismember())
+    g1.play()
+    g2.play()
+
+
+
+In this environment, **Character** objects interact with **Obstacle** objects,
+but there are different types of Characters and obstacles depending on what kind
+of game you're playing. You determine the kind of game by choosing a particular
+**GameElementFactory**, and then the **GameEnvironment** controls the setup and
+play of the game. In this example, the setup and play is very simple, but those
+activities (the *initial conditions* and the *state change*) can determine much
+of the game's outcome. Here, **GameEnvironment** is not designed to be
+inherited, although it could very possibly make sense to do that.
+
+This also contains examples of *Double Dispatching* and the *Factory Method*,
+both of which will be explained later.
+
+Of course, the above scaffolding of **Obstacle**, **Character** and
+**GameElementFactory** (which was translated from the Java version of this
+example) is unnecessary - it's only required for languages that have static type
+checking. As long as the concrete Python classes follow the form of the required
+classes, we don't need any base classes::
+
+    # factory/Games2.py
+    # Simplified Abstract Factory.
+
+    class Kitty:
+        def interactWith(self, obstacle):
+            print("Kitty has encountered a",
+            obstacle.action())
+
+    class KungFuGuy:
+        def interactWith(self, obstacle):
+            print("KungFuGuy now battles a",
+            obstacle.action())
+
+    class Puzzle:
+        def action(self): print("Puzzle")
+
+    class NastyWeapon:
+        def action(self): print("NastyWeapon")
+
+    # Concrete factories:
+    class KittiesAndPuzzles:
+        def makeCharacter(self): return Kitty()
+        def makeObstacle(self): return Puzzle()
+
+    class KillAndDismember:
+        def makeCharacter(self): return KungFuGuy()
+        def makeObstacle(self): return NastyWeapon()
+
+    class GameEnvironment:
+        def __init__(self, factory):
+            self.factory = factory
+            self.p = factory.makeCharacter()
+            self.ob = factory.makeObstacle()
+        def play(self):
+            self.p.interactWith(self.ob)
+
+    g1 = GameEnvironment(KittiesAndPuzzles())
+    g2 = GameEnvironment(KillAndDismember())
+    g1.play()
+    g2.play()
+
+
+Another way to put this is that all inheritance in Python is implementation
+inheritance; since Python does its type-checking at runtime, there's no need to
+use interface inheritance so that you can upcast to the base type.
+
+You might want to study the two examples for comparison, however. Does the first
+one add enough useful information about the pattern that it's worth keeping some
+aspect of it? Perhaps all you need is "tagging classes" like this::
+
+    class Obstacle: pass
+    class Character: pass
+    class GameElementFactory: pass
+
+Then the inheritance serves only to indicate the type of the derived classes.
+
+Exercises
+=======================================================================
+
+#.  Add a class **Triangle** to **ShapeFactory1.py**
+
+#.  Add a class **Triangle** to **ShapeFactory2.py**
+
+#.  Add a new type of **GameEnvironment** called **GnomesAndFairies** to
+    **GameEnvironment.py**
+
+#.  Modify **ShapeFactory2.py** so that it uses an *Abstract Factory* to create
+    different sets of shapes (for example, one particular type of factory object
+    creates "thick shapes," another creates "thin shapes," but each factory
+    object can create all the shapes: circles, squares, triangles etc.).
+
+
+
+
+********************************************************************************
+Fronting for an Implementation
+********************************************************************************
+
+Both *Proxy* and *State* provide a surrogate class that you use in your code;
+the real class that does the work is hidden behind this surrogate class. When
+you call a method in the surrogate, it simply turns around and calls the method
+in the implementing class. These two patterns are so similar that the *Proxy* is
+simply a special case of *State*. One is tempted to just lump the two together
+into a pattern called *Surrogate*, but the term "proxy" has a long-standing and
+specialized meaning, which probably explains the reason for the two different
+patterns.
+
+The basic idea is simple: from a base class, the surrogate is derived along with
+the class or classes that provide the actual implementation:
+
+..  image:: _images/surrogate.*
+
+
+When a surrogate object is created, it is given an implementation to which to
+send all of the method calls.
+
+Structurally, the difference between *Proxy* and *State* is simple: a *Proxy*
+has only one implementation, while *State* has more than one. The application of
+the patterns is considered (in *Design Patterns*) to be distinct: *Proxy* is
+used to control access to its implementation, while *State* allows you to change
+the implementation dynamically. However, if you expand your notion of
+"controlling access to implementation" then the two fit neatly together.
+
+Proxy
+=======================================================================
+
+If we implement *Proxy* by following the above diagram, it looks like this::
+
+    # fronting/ProxyDemo.py
+    # Simple demonstration of the Proxy pattern.
+
+    class Implementation:
+        def f(self):
+            print("Implementation.f()")
+        def g(self):
+            print("Implementation.g()")
+        def h(self):
+            print("Implementation.h()")
+
+    class Proxy:
+        def __init__(self):
+            self.__implementation = Implementation()
+        # Pass method calls to the implementation:
+        def f(self): self.__implementation.f()
+        def g(self): self.__implementation.g()
+        def h(self): self.__implementation.h()
+
+    p = Proxy()
+    p.f(); p.g(); p.h()
+
+It isn't necessary that **Implementation** have the same interface as **Proxy**;
+as long as **Proxy** is somehow "speaking for" the class that it is referring
+method calls to then the basic idea is satisfied (note that this statement is at
+odds with the definition for Proxy in GoF). However, it is convenient to have a
+common interface so that **Implementation** is forced to fulfill all the methods
+that **Proxy** needs to call.
+
+Of course, in Python we have a delegation mechanism built in, so it makes the
+**Proxy** even simpler to implement::
+
+    # fronting/ProxyDemo2.py
+    # Simple demonstration of the Proxy pattern.
+
+    class Implementation2:
+        def f(self):
+            print("Implementation.f()")
+        def g(self):
+            print("Implementation.g()")
+        def h(self):
+            print("Implementation.h()")
+
+    class Proxy2:
+        def __init__(self):
+            self.__implementation = Implementation2()
+        def __getattr__(self, name):
+            return getattr(self.__implementation, name)
+
+    p = Proxy2()
+    p.f(); p.g(); p.h();
+
+
+The beauty of using **__getattr__( )** is that **Proxy2** is completely generic,
+and not tied to any particular implementation (in Java, a rather complicated
+"dynamic proxy" has been invented to accomplish this same thing).
+
+State
+=======================================================================
+
+The *State* pattern adds more implementations to *Proxy*, along with a way to
+switch from one implementation to another during the lifetime of the surrogate::
+
+    # fronting/StateDemo.py
+    # Simple demonstration of the State pattern.
+
+    class State_d:
+        def __init__(self, imp):
+            self.__implementation = imp
+        def changeImp(self, newImp):
+            self.__implementation = newImp
+        # Delegate calls to the implementation:
+        def __getattr__(self, name):
+            return getattr(self.__implementation, name)
+
+    class Implementation1:
+        def f(self):
+            print("Fiddle de dum, Fiddle de dee,")
+        def g(self):
+            print("Eric the half a bee.")
+        def h(self):
+            print("Ho ho ho, tee hee hee,")
+
+    class Implementation2:
+        def f(self):
+            print("We're Knights of the Round Table.")
+        def g(self):
+            print("We dance whene'er we're able.")
+        def h(self):
+            print("We do routines and chorus scenes")
+
+    def run(b):
+        b.f()
+        b.g()
+        b.h()
+        b.g()
+
+    b = State_d(Implementation1())
+    run(b)
+    b.changeImp(Implementation2())
+    run(b)
+
+
+
+You can see that the first implementation is used for a bit, then the second
+implementation is swapped in and that is used.
+
+The difference between *Proxy* and *State* is in the problems that are solved.
+The common uses for *Proxy* as described in *Design Patterns* are:
+
+#.  **Remote proxy**. This proxies for an object in a different address space. A
+    remote proxy is created for you automatically by the RMI compiler **rmic**
+    as it creates stubs and skeletons.
+
+#.  **Virtual proxy**. This provides "lazy initialization" to create expensive
+    objects on demand.
+
+#.  **Protection proxy**. Used when you don't want the client programmer to have
+    full access to the proxied object.
+
+#.  **Smart reference**. To add additional actions when the proxied object is
+    accessed. For example, or to keep track of the number of references that are
+    held for a particular object, in order to implement the *copy-on-write*
+    idiom and prevent object aliasing. A simpler example is keeping track of the
+    number of calls to a particular method.
+
+You could look at a Python reference as a kind of protection proxy, since it
+controls access to the actual object on the heap (and ensures, for example, that
+you don't use a **null** reference).
+
+[[ Rewrite this: In *Design Patterns*, *Proxy* and *State* are not seen as
+related to each other because the two are given (what I consider arbitrarily)
+different structures. *State*, in particular, uses a separate implementation
+hierarchy but this seems to me to be unnecessary unless you have decided that
+the implementation is not under your control (certainly a possibility, but if
+you own all the code there seems to be no reason not to benefit from the
+elegance and helpfulness of the single base class). In addition, *Proxy* need
+not use the same base class for its implementation, as long as the proxy object
+is controlling access to the object it "fronting" for. Regardless of the
+specifics, in both *Proxy* and *State* a surrogate is passing method calls
+through to an implementation object.]]]
+
+
+

src/FunctionObjects.rst

+
+********************************************************************************
+Function Objects
+********************************************************************************
+
+In *Advanced C++:Programming Styles And Idioms (Addison-Wesley, 1992)*, Jim
+Coplien coins the term *functor* which is an object whose sole purpose is to
+encapsulate a function (since "functor" has a meaning in mathematics, in this
+book I shall use the more explicit term *function object*). The point is to
+decouple the choice of function to be called from the site where that function
+is called.
+
+This term is mentioned but not used in *Design Patterns*. However, the theme of
+the function object is repeated in a number of patterns in that book.
+
+Command: Choosing the Operation at Runtime
+=======================================================================
+
+This is the function object in its purest sense: a method that's an object. By
+wrapping a method in an object, you can pass it to other methods or objects as a
+parameter, to tell them to perform this particular operation in the process of
+fulfilling your request::
+
+    # functionObjects/CommandPattern.py
+
+    class Command:
+        def execute(self): pass
+
+    class Loony(Command):
+        def execute(self):
+            print("You're a loony.")
+
+    class NewBrain(Command):
+        def execute(self):
+            print("You might even need a new brain.")
+
+    class Afford(Command):
+        def execute(self):
+            print("I couldn't afford a whole new brain.")
+
+    # An object that holds commands:
+    class Macro:
+        def __init__(self):
+            self.commands = []
+        def add(self, command):
+            self.commands.append(command)
+        def run(self):
+            for c in self.commands:
+                c.execute()
+
+    macro = Macro()
+    macro.add(Loony())
+    macro.add(NewBrain())
+    macro.add(Afford())
+    macro.run()
+
+
+The primary point of *Command* is to allow you to hand a desired action to a
+method or object. In the above example, this provides a way to queue a set of
+actions to be performed collectively. In this case, it allows you to dynamically
+create new behavior, something you can normally only do by writing new code but
+in the above example could be done by interpreting a script (see the
+*Interpreter* pattern if what you need to do gets very complex).
+
+*Design Patterns* says that "Commands are an object-oriented replacement for
+callbacks." However, I think that the word "back" is an essential part of the
+concept of callbacks. That is, I think a callback actually reaches back to the
+creator of the callback. On the other hand, with a *Command* object you
+typically just create it and hand it to some method or object, and are not
+otherwise connected over time to the *Command* object. That's my take on it,
+anyway. Later in this book, I combine a group of design patterns under the
+heading of "callbacks."
+
+Strategy: Choosing the Algorithm at Runtime
+=======================================================================
+
+*Strategy* appears to be a family of *Command* classes, all inherited from the
+same base. But if you look at *Command*, you'll see that it has the same
+structure: a hierarchy of function objects. The difference is in the way this
+hierarchy is used. As seen in **patternRefactoring:DirList.py**, you use
+*Command* to solve a particular problem-in that case, selecting files from a
+list. The "thing that stays the same" is the body of the method that's being
+called, and the part that varies is isolated in the function object. I would
+hazard to say that *Command* provides flexibility while you're writing the
+program, whereas *Strategy*\'s flexibility is at run time.
+
+*Strategy* also adds a "Context" which can be a surrogate class that controls
+the selection and use of the particular strategy object-just like *State*!
+Here's what it looks like::
+
+    # functionObjects/StrategyPattern.py
+
+    # The strategy interface:
+    class FindMinima:
+        # Line is a sequence of points:
+        def algorithm(self, line) : pass
+
+    # The various strategies:
+    class LeastSquares(FindMinima):
+        def algorithm(self, line):
+            return [ 1.1, 2.2 ] # Dummy
+
+    class NewtonsMethod(FindMinima):
+        def algorithm(self, line):
+            return [ 3.3, 4.4 ]  # Dummy
+
+    class Bisection(FindMinima):
+        def algorithm(self, line):
+            return [ 5.5, 6.6 ] # Dummy
+
+    class ConjugateGradient(FindMinima):
+        def algorithm(self, line):
+            return [ 3.3, 4.4 ] # Dummy
+
+    # The "Context" controls the strategy:
+    class MinimaSolver:
+        def __init__(self, strategy):
+            self.strategy = strategy
+
+        def minima(self, line):
+            return self.strategy.algorithm(line)
+
+        def changeAlgorithm(self, newAlgorithm):
+            self.strategy = newAlgorithm
+
+    solver = MinimaSolver(LeastSquares())
+    line = [1.0, 2.0, 1.0, 2.0, -1.0, 3.0, 4.0, 5.0, 4.0]
+    print(solver.minima(line))
+    solver.changeAlgorithm(Bisection())
+    print(solver.minima(line))
+
+
+Note similarity with template method - TM claims distinction that it has more
+than one method to call, does things piecewise. However, it's not unlikely that
+strategy object would have more than one method call; consider Shalloway's order
+fulfullment system with country information in each strategy.
+
+Strategy example from standard Python: **sort( )** takes a second optional
+argument that acts as a comparator object; this is a strategy.
+
+.. note:: A better, real world example is numerical integration, shown here:
+          http://www.rosettacode.org/wiki/Numerical_Integration#Python
+
+Chain of Responsibility
+=======================================================================
+
+*Chain of Responsibility* might be thought of as a dynamic generalization of
+recursion using *Strategy* objects. You make a call, and each *Strategy* in a
+linked sequence tries to satisfy the call. The process ends when one of the
+strategies is successful or the chain ends. In recursion, one method calls
+itself over and over until a termination condition is reached; with *Chain of
+Responsibility*, a method calls itself, which (by moving down the chain of
+*Strategies*) calls a different implementation of the method, etc., until a
+termination condition is reached. The termination condition is either the bottom
+of the chain is reached (in which case a default object is returned; you may or
+may not be able to provide a default result so you must be able to determine the
+success or failure of the chain) or one of the *Strategies* is successful.
+
+Instead of calling a single method to satisfy a request, multiple methods in the
+chain have a chance to satisfy the request, so it has the flavor of an expert
+system. Since the chain is effectively a linked list, it can be dynamically
+created, so you could also think of it as a more general, dynamically-built
+**switch** statement.
+
+In the GoF, there's a fair amount of Thidiscussion of how to create the chain of
+responsibility as a linked list. However, when you look at the pattern it really
+shouldn't matter how the chain is maintained; that's an implementation detail.
+Since GoF was written before the Standard Template Library (STL) was
+incorporated into most C++ compilers, the reason for this is most likely (1)
+there was no list and thus they had to create one and (2) data structures are
+often taught as a fundamental skill in academia, and the idea that data
+structures should be standard tools available with the programming language may
+not have occurred to the GoF authors. I maintain that the implementation of
+*Chain of Responsibility* as a chain (specifically, a linked list) adds nothing
+to the solution and can just as easily be implemented using a standard Python
+list, as shown below. Furthermore, you'll see that I've gone to some effort to
+separate the chain-management parts of the implementation from the various
+*Strategies*, so that the code can be more easily reused.
+
+In **StrategyPattern.py**, above, what you probably want is to automatically
+find a solution. *Chain of Responsibility* provides a way to do this by chaining
+the *Strategy* objects together and providing a mechanism for them to
+automatically recurse through each one in the chain::
+
+    # functionObjects/ChainOfResponsibility.py
+
+    # Carry the information into the strategy:
+    class Messenger: pass
+
+    # The Result object carries the result data and
+    # whether the strategy was successful:
+    class Result:
+        def __init__(self):
+            self.succeeded = 0
+        def isSuccessful(self):
+            return self.succeeded
+        def setSuccessful(self, succeeded):
+            self.succeeded = succeeded
+
+    class Strategy:
+        def __call__(messenger): pass
+        def __str__(self):
+            return "Trying " + self.__class__.__name__ \
+              + " algorithm"
+
+    # Manage the movement through the chain and
+    # find a successful result:
+    class ChainLink:
+        def __init__(self, chain, strategy):
+            self.strategy = strategy
+            self.chain = chain
+            self.chain.append(self)
+
+        def next(self):
+            # Where this link is in the chain:
+            location = self.chain.index(self)
+            if not self.end():
+                return self.chain[location + 1]
+
+        def end(self):
+            return (self.chain.index(self) + 1 >=
+                    len(self.chain))
+
+        def __call__(self, messenger):
+            r = self.strategy(messenger)
+            if r.isSuccessful() or self.end(): return r
+            return self.next()(messenger)
+
+    # For this example, the Messenger
+    # and Result can be the same type:
+    class LineData(Result, Messenger):
+        def __init__(self, data):
+            self.data = data
+        def __str__(self): return `self.data`
+
+    class LeastSquares(Strategy):
+        def __call__(self, messenger):
+            print(self)
+            linedata = messenger
+            # [ Actual test/calculation here ]
+            result = LineData([1.1, 2.2]) # Dummy data
+            result.setSuccessful(0)
+            return result
+
+    class NewtonsMethod(Strategy):
+        def __call__(self, messenger):
+            print(self)
+            linedata = messenger
+            # [ Actual test/calculation here ]
+            result = LineData([3.3, 4.4]) # Dummy data
+            result.setSuccessful(0)
+            return result
+
+    class Bisection(Strategy):
+        def __call__(self, messenger):
+            print(self)
+            linedata = messenger
+            # [ Actual test/calculation here ]
+            result = LineData([5.5, 6.6]) # Dummy data
+            result.setSuccessful(1)
+            return result
+
+    class ConjugateGradient(Strategy):
+        def __call__(self, messenger):
+            print(self)
+            linedata = messenger
+            # [ Actual test/calculation here ]
+            result = LineData([7.7, 8.8]) # Dummy data
+            result.setSuccessful(1)
+            return result
+
+    solutions = []
+    ChainLink(solutions, LeastSquares()),
+    ChainLink(solutions, NewtonsMethod()),
+    ChainLink(solutions, Bisection()),
+    ChainLink(solutions, ConjugateGradient())
+
+    line = LineData([
+      1.0, 2.0, 1.0, 2.0, -1.0,
+      3.0, 4.0, 5.0, 4.0
+    ])
+
+    print(solutions[0](line))
+
+
+Exercises
+=======================================================================
+
+#.  Use *Command* in Chapter 3, Exercise 1.
+
+#.  Implement *Chain of Responsibility* to create an "expert system" that solves
+    problems by successively trying one solution after another until one
+    matches. You should be able to dynamically add solutions to the expert
+    system. The test for solution should just be a string match, but when a
+    solution fits, the expert system should return the appropriate type of
+    **ProblemSolver** object. What other pattern/patterns show up here?
+
+.. rubric:: Footnotes
+
+.. [#] In Python, all functions are already objects and so the *Command* pattern
+       is often redundant.
+
+.. [#] *Design Patterns*, Page 235.
+
+

src/GeneratorsIterators.rst

+.. index::
+   generators
+   iterators
+   itertools
+
+********************************************************************************
+Generators, Iterators, and Itertools
+********************************************************************************
+

src/Introduction.rst

+*******************************************************************************
+Introduction
+*******************************************************************************
+
+.. raw:: html
+
+   <font size="+1">The vision for this book.</font>
+
+A Team Effort
+===============================================================================
+
+This book is an experiment to see if we can combine everyone's best efforts to
+create something great.
+
+You can find the contributors right before this introduction. They are listed
+in order of *Karma Points*, a system Launchpad.net uses to keep track of
+contributions from everyone working on an open-source project.
+
+In my case, I will write new material, as well as rewriting other contributions
+to clarify and give voice, setting up the architecture and being the *Benevolent
+Dictator* for the book. But I definitely won't be doing everything; my goal is
+that this is a team project and that everyone who wants to will have something
+useful to contribute.
+
+We'll be using Launchpad.net's "Blueprints" facility to add "features" to the
+book, so that's where you'll find the main repository of things to do.
+
+What can you contribute? Anything as small as spelling and grammatical
+correctons, and as large as a whole chapter. Research into new topics and
+creating examples is what takes me the most time, so if you know something
+already or are willing to figure it out, don't worry if your writing or
+programming isn't perfect -- contribute it and I and the rest of the group will
+improve it.
+
+You may also have talents in figuring things out. Sphinx formatting, for
+example, or how to produce camera-ready formatting. These are all very useful
+things which will not only benefit this book but also any future book built on
+this template (every bit of the build system for the book will be out in the
+open, so if you want to take what we've done here and start your own book, you
+can).
+
+Of course, not everything can make it into the final print book, but things that
+don't fit into the main book can be moved into an "appendix book" or a "volume
+2" book or something like that.
+
+Not an Introductory Book
+===============================================================================
+
+Although there is an introduction for programmers, this book is not intended to
+be introductory. There are already lots of good introductory books out there.
+
+You can think of it as an "intermediate" or "somewhat advanced" book, but the
+"somewhat" modifier is very important here. Because it is not introductory, two
+difficult constraints are removed.
+
+#.  In an introductory book you are forced to describe everything in lock step,
+    never mentioning anything before it has been thoroughly introduced. That's
+    still a good goal, but we don't have to agonize over it when it doesn't
+    happen (just cross-reference the material).
+
+#.  In addition, the topics are not restricted; in this book topics are chosen
+    based on whether they are interesting and/or useful, not on whether they are
+    introductory or not.
+
+That said, people will still be coming to a topic without knowing about it and
+it will need to be introduced, as much as possible, as if they have never seen
+it before.
+
+The License
+===============================================================================
+
+Unless otherwise specified, the material in this book is published under a
+`Creative Commons Attribution-Share Alike 3.0 license
+<http://creativecommons.org/licenses/by-sa/3.0/>`_.
+
+If you make contributions, you must own the rights to your material and be able
+to place them under this license. Please don't contribute something unless you
+are sure this is the case (read your company's employment contract -- these
+often specify that anything you think of or create at any time of day or night
+belongs to the company).
+
+The Printed Book
+===============================================================================
+
+Because of the creative commons license, the electronic version of the book as
+well as all the sources are available, can be reproduced on other web sites,
+etc. (again, as long as you attribute it).
+
+You can print your own version of the book. I will be creating a printed version
+of the book for sale, with a nice cover and binding. Many people do like to have
+a print version of the book, and part of the motivation for doing a print
+version is to make some income off the effort I put into the book.
+
+But buying my particular print version of the book is optional. All of the tools
+will be downloadable so that you can print it yourself, or send it to a copy
+shop and have it bound, etc. The only thing you won't get is my cover and
+binding.
+
+Translations
+===============================================================================
+