work in fixes, suggestions from review

* fix typos
* use pluginmanager in a fashion closer to real world usage
* normalize whitespace after titles in docs

Author: obestwalter

docs/examples/eggsample-spam/eggsample_spam.py

@@ -5,7 +5,7 @@ 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"]
-    print(f"add {spam}")
+    print(f"Add {spam}")
     ingredients.extend(spam)
 
 @eggsample.hookimpl

docs/examples/eggsample/eggsample/__init__.py

@@ -1,7 +1,4 @@
 import pluggy
 
 hookimpl = pluggy.HookimplMarker("eggsample")
-"""Marker to be imported and used in plugins"""
-
-pm = pluggy.PluginManager("eggsample")
-"""The manager ... you know? to manage the plugins!"""
+"""Marker to be imported and used in plugins (and for own implementations)"""

docs/examples/eggsample/eggsample/host.py

@@ -1,29 +1,33 @@
 import random
 
-from eggsample import hookimpl, hookspecs, lib, pm
+import pluggy
+
+from eggsample import hookspecs, lib
 
 condiments_tray = {"pickled walnuts": 13, "steak sauce": 4, "mushy peas": 2}
 
-class FoodMaster2000:
-    def __init__(self):
+class EggselentCook:
+    def __init__(self, hook):
+        self.hook = hook
         self.ingredients = []
 
     def add_ingredients(self):
-        pm.hook.eggsample_add_ingredients(ingredients=self.ingredients)
+        self.hook.eggsample_add_ingredients(ingredients=self.ingredients)
 
     def prepare_the_food(self):
         random.shuffle(self.ingredients)
 
     def serve_the_food(self):
-        pm.hook.eggsample_prep_condiments(condiments=condiments_tray)
+        self.hook.eggsample_prep_condiments(condiments=condiments_tray)
         print(f"Your food: {', '.join(self.ingredients)}")
         print(f"Some condiments: {', '.join(condiments_tray.keys())}")
 
 def main():
-    pm.add_hookspecs(hookspecs)
-    pm.load_setuptools_entrypoints("eggsample")
-    pm.register(lib)
-    fm2000 = FoodMaster2000()
+    pluginmanager = pluggy.PluginManager("eggsample")
+    pluginmanager.add_hookspecs(hookspecs)
+    pluginmanager.load_setuptools_entrypoints("eggsample")
+    pluginmanager.register(lib)
+    fm2000 = EggselentCook(pluginmanager.hook)
     fm2000.add_ingredients()
     fm2000.prepare_the_food()
     fm2000.serve_the_food()

docs/index.rst

@@ -19,7 +19,6 @@ In essence, ``pluggy`` enables function `hooking`_ so you can build
 
 Why is it useful?
 *****************
-
 There are some established mechanisms for modifying the behavior of other
 programs/libraries in Python like
 `method overriding <https://en.wikipedia.org/wiki/Method_overriding>`_
@@ -41,7 +40,6 @@ and objects to work with.
 
 How does it work?
 *****************
-
 Let us start with a short overview of what is involved:
 
 * ``host`` or ``host program``: the program offering extensibility
@@ -57,7 +55,7 @@ Let us start with a short overview of what is involved:
     - the hook :ref:`implementations <impls>` provided by registered
       ``plugins`` (a.k.a ``hookimpl`` - see `callbacks`_)
     - the hook :ref:`caller <calling>` - a call loop triggered at appropriate
-      program positions in the ``host`` invoking the implementations
+      program positions in the ``host`` invoking the implementations and
       collecting the results
 
     ... where for each registered hook *specification*, a hook *call* will
@@ -98,7 +96,7 @@ the steak sauce from the condiments tray (nobody likes that anyway).
 .. note::
 
     **naming markers**: ``HookSpecMarker`` and ``HookImplMarker`` must be
-    the initialized with the name of the ``host`` project (the ``name``
+    initialized with the name of the ``host`` project (the ``name``
     parameter in ``setup()``) - so **eggsample** in our case.
 
     **naming plugin projects**: they should be named in the form of
@@ -132,7 +130,6 @@ Let's get cooking - we install the host and see what a program run looks like::
     Your food: egg, salt, pepper, egg
     Some condiments: pickled walnuts, steak sauce, mushy peas, mint sauce
 
-
 The plugin
 ^^^^^^^^^^
 ``eggsample-spam/eggsample_spam.py``
@@ -156,7 +153,6 @@ we get::
 
 More real world examples
 ------------------------
-
 To see how ``pluggy`` is used in the real world, have a look at these projects
 documentation and source code: