Add app providers, tests, docs

docs/narr/index.rst

@@ -9,4 +9,5 @@ Documentation
    config/index
    cli/index
    handlers/index
+   providers/index
    db/index

docs/narr/providers/app.rst

@@ -0,0 +1,57 @@
+
+App Providers
+=============
+
+An :term:`app provider` is a :term:`provider` which can "extend" the
+main :term:`app handler`.
+
+The provider generally does this by adding extra methods to the app
+handler.  Note that it does this regardless of which app handler is
+configured to be used.
+
+:class:`~wuttjamaican.app.AppProvider` is the base class.
+
+
+Adding a new Provider
+---------------------
+
+First define your provider class.  Note that the method names should
+include a "prefix" unique to your project (``poser_`` in this case).
+This is to avoid naming collisions with the app handler itself, as
+well as other app providers.  So e.g. in ``poser/app.py``::
+
+   from wuttjamaican.app import AppProvider
+
+   class PoserAppProvider(AppProvider):
+       """
+       App provider for Poser system
+       """
+
+       # nb. method name uses 'poser_' prefix
+       def poser_do_something(self, **kwargs):
+           """
+           Do something for Poser
+           """
+           print("did something")
+
+Register the :term:`entry point` in your ``setup.cfg``:
+
+.. code-block:: ini
+
+   [options.entry_points]
+
+   wutta.providers =
+       poser = poser.app:PoserAppProvider
+
+Assuming you have not customized the app handler proper, then you will
+be using the *default* app handler yet it will behave as though it has
+the "provided" methods::
+
+   from wuttjamaican.conf import make_config
+
+   # make normal app
+   config = make_config()
+   app = config.get_app()
+
+   # whatever this does..
+   app.poser_do_something()

docs/narr/providers/arch.rst

@@ -0,0 +1,39 @@
+
+Architecture
+============
+
+:term:`Providers<provider>` are similar to a "plugin" concept in that
+multiple providers may be installed by different
+:term:`packages<package>`.  But whereas plugins are typically limited
+to a particular interface (method list/signatures etc.) a provider can
+also "bolt on" entirely new methods which may be used elsewhere in the
+:term:`app`.
+
+In that sense providers can perhaps be more accurately thought of as
+"extensions" rather than plugins.
+
+Providers may be related to :term:`handlers<handler>` in some cases,
+but not all.  But whereas there is only *one handler* configured for a
+given portion of the app, multiple providers of the same type would
+*all contribute* to the overall app.  In other words they are always
+enabled if installed.  (Some may require a :term:`config setting` to
+be "active" - but that is up to each provider.)
+
+There can be many "types" of providers; each pertains to a certain
+aspect of the overall app.  A given type of provider will apply to a
+certain "parent" class.
+
+
+What a Provider Does
+--------------------
+
+Each type of provider pertains to a certain parent class.  The app
+itself will define the need for a provider type.
+
+For instance there might be a "dashboard" class which can show various
+blocks of info (charts etc.).  Providers might be used to supplement the
+parent dashboard class, by adding extra blocks to the display.
+
+But in that example, providers look an awful lot like plugins.
+
+For a better (and real) example see :doc:`app`.

docs/narr/providers/index.rst

@@ -0,0 +1,10 @@
+
+Providers
+=========
+
+.. toctree::
+   :maxdepth: 2
+
+   overview
+   arch
+   app

docs/narr/providers/overview.rst

@@ -0,0 +1,13 @@
+
+Overview
+========
+
+The :term:`provider` concept is a way to "supplement" the main app
+logic.  It is different from a :term:`handler` though:
+
+Providers are *more* analagous to "plugins" than are handlers.  For
+instance multiple :term:`app providers<app provider>` may be installed
+by various packages and *each of these* will supplement the (one and
+only) :term:`app handler`.  See also :doc:`arch`.
+
+So far there is only one provider type defined; see :doc:`app`.