fix bug in example and some more improvements/clarfications.

* fix bug introduced when "fixing" the example
* reorder code: give the big picture first (main())
* split out function to get plugin manager
* use the two functions to demonstrate returning a result vs modifying
  an argument
* avoid too lont sentences.
* use pip --editable instead of -e for clarity

Author: obestwalter

docs/examples/eggsample-spam/eggsample_spam.py

@@ -2,15 +2,20 @@
 
 @eggsample.hookimpl
 def eggsample_add_ingredients(ingredients):
-    if len([e for e in ingredients if e == "egg"]) > 2:
-        ingredients.remove("egg")
-    spam = ["lovely spam", "wonderous spam", "splendiferous spam"]
+    """Here we get an immutable object, so we return something to the caller."""
+    if "egg" in ingredients:
+        spam = ["lovely spam", "wonderous spam"]
+    else:
+        spam = ["splendiferous spam", "magnificent spam"]
     print(f"Add {spam}")
     return spam
 
 @eggsample.hookimpl
 def eggsample_prep_condiments(condiments):
+    """Here we get a mutable object, so we just mess with it directly."""
     try:
         del condiments["steak sauce"]
     except KeyError:
         pass
+    condiments['spam sauce'] = 42
+    print(f"Now. this is what I call a condiments tray!")

docs/examples/eggsample/eggsample/hookspecs.py

@@ -3,15 +3,17 @@
 hookspec = pluggy.HookspecMarker("eggsample")
 
 @hookspec
-def eggsample_add_ingredients(ingredients):
-    """Change the used ingredients.
+def eggsample_add_ingredients(ingredients: tuple):
+    """Have a look at the ingredients and offer your own.
 
-    :param list ingredients: the ingredients to be modified
+    :param ingredients: the ingredients, don't touch them!
+    :return: a list of ingredients
     """
 
 @hookspec
-def eggsample_prep_condiments(condiments):
-    """Reorganize the condiments tray.
+def eggsample_prep_condiments(condiments: dict):
+    """Reorganize the condiments tray to your heart's content.
 
-    :param dict condiments: some sauces and stuff
+    :param condiments: some sauces and stuff
+    :return: will be ignored by caller
     """

docs/examples/eggsample/eggsample/host.py

@@ -1,3 +1,4 @@
+import itertools
 import random
 
 import pluggy
@@ -6,16 +7,34 @@
 
 condiments_tray = {"pickled walnuts": 13, "steak sauce": 4, "mushy peas": 2}
 
+def main():
+    pm = get_plugin_manager()
+    cook = EggsellentCook(pm.hook)
+    cook.add_ingredients()
+    cook.prepare_the_food()
+    cook.serve_the_food()
+
+def get_plugin_manager():
+    pm = pluggy.PluginManager("eggsample")
+    pm.add_hookspecs(hookspecs)
+    pm.load_setuptools_entrypoints("eggsample")
+    pm.register(lib)
+    return pm
+
 class EggsellentCook:
+    FAVORITE_INGREDIENTS = ("egg", "egg", "egg")
+
     def __init__(self, hook):
         self.hook = hook
-        self.ingredients = []
+        self.ingredients = None
 
     def add_ingredients(self):
-        more_ingredients = self.hook.eggsample_add_ingredients(
-            ingredients=self.ingredients)
-        # each hook implementation returned a list of ingredients
-        self.ingredients.extend(more_ingredients)
+        results = self.hook.eggsample_add_ingredients(
+            ingredients=self.FAVORITE_INGREDIENTS)
+        my_ingredients = list(self.FAVORITE_INGREDIENTS)
+        # Each hook returns a list - so we chain this list of lists
+        other_ingredients = list(itertools.chain(*results))
+        self.ingredients = my_ingredients + other_ingredients
 
     def prepare_the_food(self):
         random.shuffle(self.ingredients)
@@ -25,15 +44,5 @@ def serve_the_food(self):
         print(f"Your food: {', '.join(self.ingredients)}")
         print(f"Some condiments: {', '.join(condiments_tray.keys())}")
 
-def main():
-    pluginmanager = pluggy.PluginManager("eggsample")
-    pluginmanager.add_hookspecs(hookspecs)
-    pluginmanager.load_setuptools_entrypoints("eggsample")
-    pluginmanager.register(lib)
-    cook = EggsellentCook(pluginmanager.hook)
-    cook.add_ingredients()
-    cook.prepare_the_food()
-    cook.serve_the_food()
-
 if __name__ == '__main__':
     main()

docs/examples/eggsample/eggsample/lib.py

@@ -1,10 +1,12 @@
 import eggsample
 
 @eggsample.hookimpl
-def eggsample_add_ingredients(ingredients):
-    basics = ["egg", "egg", "salt", "pepper"]
-    print(f"Add {basics}")
-    return basics
+def eggsample_add_ingredients():
+    spices = ["salt", "pepper"]
+    you_can_never_have_enough_eggs = ["egg", "egg"]
+    ingredients = spices + you_can_never_have_enough_eggs
+    print(f"Add {ingredients}")
+    return ingredients
 
 @eggsample.hookimpl
 def eggsample_prep_condiments(condiments):

docs/index.rst

@@ -35,7 +35,7 @@ between ``host`` and ``plugins``.
 
 The ``pluggy`` approach puts the burden on the designer of the
 ``host program`` to think carefully about which objects are really
-needed in a hook implementation, which gives `plugin` creators a clear
+needed in a hook implementation. This gives `plugin` creators a clear
 framework for how to extend the ``host`` via a well defined set of functions
 and objects to work with.
 
@@ -91,8 +91,8 @@ Now let us demonstrate how this plays together in a vaguely real world scenario.
 Let's assume our ``host program`` is called **eggsample** where some eggs will
 be prepared and served with a tray containing condiments. As everybody knows:
 the more cooks are involved the better the food, so let us make the process
-pluggable and write a plugin that improves the meal with some spam and removes
-the steak sauce from the condiments tray (nobody likes that anyway).
+pluggable and write a plugin that improves the meal with some spam and replaces
+the steak sauce (nobody likes that anyway) with spam sauce (it's a thing - trust me).
 
 .. note::
 
@@ -124,11 +124,11 @@ The host
 
 Let's get cooking - we install the host and see what a program run looks like::
 
-    $ pip install -e pluggy/docs/examples/eggsample
+    $ pip install --editable pluggy/docs/examples/eggsample
     $ eggsample
 
-    Add ['egg', 'egg', 'salt', 'pepper']
-    Your food: egg, salt, pepper, egg
+    Add ['salt', 'pepper', 'egg', 'egg']
+    Your food: pepper, egg, egg, egg, egg, salt, egg
     Some condiments: pickled walnuts, steak sauce, mushy peas, mint sauce
 
 The plugin
@@ -144,13 +144,14 @@ The plugin
 Let's get cooking with more cooks - we install the plugin and and see what
 we get::
 
-    $ pip install -e pluggy/docs/examples/eggsample-spam
+    $ pip install --editable pluggy/docs/examples/eggsample-spam
     $ eggsample
 
-    Add ['egg', 'egg', 'salt', 'pepper']
-    add ['lovely spam', 'wonderous spam', 'splendiferous spam']
-    Your food: egg, lovely spam, egg, pepper, salt, wonderous spam, splendiferous spam
-    Some condiments: pickled walnuts, mushy peas, mint sauce
+    Add ['salt', 'pepper', 'egg', 'egg']
+    Add ['lovely spam', 'wonderous spam']
+    Now, this is what I call a condiments tray!
+    Your food: wonderous spam, pepper, egg, egg, egg, egg, lovely spam, egg, salt
+    Some condiments: pickled walnuts, mushy peas, mint sauce, spam sauce
 
 More real world examples
 ------------------------