Add config extension class, tests, docs

docs/narr/config/object.rst

@@ -54,3 +54,42 @@ to solve the "chicken-vs-egg" problem::
    config = make_config()
 
    app = config.get_app()
+
+
+Extending the Config Object
+---------------------------
+
+Some packages may need to "extend" the config object somehow, to add
+various attributes which they may reference later when certain code
+runs.
+
+A typical example would be for an "integration" package, which is
+responsible for communicating with a third party database.  This
+package might extend the config by loading some database connections
+based on config values, and attaching those directly to the config
+object (and usually, configuring a ``Session`` class).
+
+But here is a simpler example; add this to e.g. ``poser/config.py``::
+
+   from wuttjamaican.conf import WuttaConfigExtension
+
+   class PoserConfigExtension(WuttaConfigExtension):
+       """
+       Custom config extension for Poser
+       """
+       key = 'poser'
+
+       def configure(self, config):
+           foo = config.setdefault('poser.foo', 'bar')
+           config.poser_foo = foo
+
+Then you must register an :term:`entry point` in your ``setup.cfg``:
+
+.. code-block:: ini
+
+   [options.entry_points]
+   wutta.config.extensions =
+        poser = poser.config:PoserConfigExtension
+
+After your ``poser`` package is installed, the extension logic should
+automatically run when the config object is being made.

src/wuttjamaican/conf.py

@@ -573,6 +573,22 @@ class WuttaConfig:
         return self.app
 
 
+class WuttaConfigExtension:
+    """
+    Base class for all config extensions.
+    """
+    key = None
+
+    def __repr__(self):
+        return f"WuttaConfigExtension(key={self.key})"
+
+    def configure(self, config):
+        """
+        Subclass should override this method, to extend the config
+        object in any way necessary.
+        """
+
+
 def generic_default_files(appname):
     """
     Returns a list of default file paths which might be used for

tests/test_conf.py

@@ -382,6 +382,15 @@ configure_logging = true
         self.assertIs(type(app), AppHandler)
 
 
+class TestWuttaConfigExtension(TestCase):
+
+    def test_basic(self):
+        config = conf.WuttaConfig()
+        ext = conf.WuttaConfigExtension()
+        self.assertIsNone(ext.key)
+        self.assertEqual(repr(ext), 'WuttaConfigExtension(key=None)')
+
+
 class TestGenericDefaultFiles(TestCase):
 
     def test_linux(self):