Improve docs: introduce roles and add another example

docs/api_reference.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 Api Reference
 =============
 

docs/examples/eggsample-spam/eggsample_spam.py

@@ -0,0 +1,20 @@
+import eggsample
+
+@eggsample.hookimpl
+def eggsample_add_ingredients(ingredients):
+    """Here the caller expects us to return a list."""
+    if "egg" in ingredients:
+        spam = ["lovely spam", "wonderous spam"]
+    else:
+        spam = ["splendiferous spam", "magnificent spam"]
+    return spam
+
+@eggsample.hookimpl
+def eggsample_prep_condiments(condiments):
+    """Here the caller passes a mutable object, so we mess with it directly."""
+    try:
+        del condiments["steak sauce"]
+    except KeyError:
+        pass
+    condiments['spam sauce'] = 42
+    return f"Now this is what I call a condiments tray!"

docs/examples/eggsample-spam/setup.py

@@ -0,0 +1,5 @@
+from setuptools import setup
+
+setup(name="eggsample-spam", install_requires="eggsample",
+      entry_points={'eggsample': ['spam = eggsample_spam']},
+      py_modules=['eggsample_spam'])

docs/examples/eggsample/eggsample/__init__.py

@@ -0,0 +1,4 @@
+import pluggy
+
+hookimpl = pluggy.HookimplMarker("eggsample")
+"""Marker to be imported and used in plugins (and for own implementations)"""

docs/examples/eggsample/eggsample/hookspecs.py

@@ -0,0 +1,19 @@
+import pluggy
+
+hookspec = pluggy.HookspecMarker("eggsample")
+
+@hookspec
+def eggsample_add_ingredients(ingredients: tuple):
+    """Have a look at the ingredients and offer your own.
+
+    :param ingredients: the ingredients, don't touch them!
+    :return: a list of ingredients
+    """
+
+@hookspec
+def eggsample_prep_condiments(condiments: dict):
+    """Reorganize the condiments tray to your heart's content.
+
+    :param condiments: some sauces and stuff
+    :return: a witty comment about your activity
+    """

docs/examples/eggsample/eggsample/host.py

@@ -0,0 +1,51 @@
+import itertools
+import random
+
+import pluggy
+
+from eggsample import hookspecs, lib
+
+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 = None
+
+    def add_ingredients(self):
+        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)
+
+    def serve_the_food(self):
+        condiment_comments = self.hook.eggsample_prep_condiments(
+            condiments=condiments_tray)
+        print(f"Your food. Enjoy some {', '.join(self.ingredients)}")
+        print(f"Some condiments? We have {', '.join(condiments_tray.keys())}")
+        if any(condiment_comments):
+            print("\n".join(condiment_comments))
+
+if __name__ == '__main__':
+    main()

docs/examples/eggsample/eggsample/lib.py

@@ -0,0 +1,12 @@
+import eggsample
+
+@eggsample.hookimpl
+def eggsample_add_ingredients():
+    spices = ["salt", "pepper"]
+    you_can_never_have_enough_eggs = ["egg", "egg"]
+    ingredients = spices + you_can_never_have_enough_eggs
+    return ingredients
+
+@eggsample.hookimpl
+def eggsample_prep_condiments(condiments):
+    condiments["mint sauce"] = 1

docs/examples/eggsample/setup.py

@@ -0,0 +1,5 @@
+from setuptools import setup, find_packages
+
+setup(name="eggsample", install_requires="pluggy>=0.3,<1.0",
+      entry_points={'console_scripts': ['eggsample=eggsample.host:main']},
+      packages=find_packages())

docs/examples/firstexample.py → docs/examples/toy-example.py

@@ -5,26 +5,22 @@
 
 
 class MySpec(object):
-    """A hook specification namespace.
-    """
+    """A hook specification namespace."""
     @hookspec
     def myhook(self, arg1, arg2):
-        """My special little hook that you can customize.
-        """
+        """My special little hook that you can customize."""
 
 
 class Plugin_1(object):
-    """A hook implementation namespace.
-    """
+    """A hook implementation namespace."""
     @hookimpl
     def myhook(self, arg1, arg2):
         print("inside Plugin_1.myhook()")
         return arg1 + arg2
 
 
 class Plugin_2(object):
-    """A 2nd hook implementation namespace.
-    """
+    """A 2nd hook implementation namespace."""
     @hookimpl
     def myhook(self, arg1, arg2):
         print("inside Plugin_2.myhook()")
@@ -34,11 +30,9 @@ def myhook(self, arg1, arg2):
 # create a manager and add the spec
 pm = pluggy.PluginManager("myproject")
 pm.add_hookspecs(MySpec)
-
 # register plugins
 pm.register(Plugin_1())
 pm.register(Plugin_2())
-
 # call our `myhook` hook
 results = pm.hook.myhook(arg1=1, arg2=2)
 print(results)