Add docs for handlers, app handler

docs/narr/handlers/app.rst

@@ -0,0 +1,68 @@
+
+App Handler
+===========
+
+There is one special "global" type of :term:`handler` which
+corresponds to the :term:`app` itself, whereas all other handlers
+correspond to some "portion" of the app.
+
+The :term:`app handler` provides:
+
+* various "global" utilities
+* primary interface for obtaining all other handlers
+
+The base class and default app handler is
+:class:`wuttjamaican.app.AppHandler`.
+
+The :term:`config object` is responsible for creating the app handler
+via :meth:`~wuttjamaican.conf.WuttaConfig.get_app()`::
+
+   from wuttjamaican.conf import make_config
+
+   config = make_config()
+   app = config.get_app()
+
+
+Overriding the App Handler
+--------------------------
+
+It is expected that many apps will want a more customized app handler.
+To do this, first create your app handler class e.g. in
+``poser/app.py``::
+
+   from wuttjamaican.app import AppHandler
+
+   class PoserAppHandler(AppHandler):
+       """
+       Custom app handler for the Poser system.
+       """
+
+       def make_session(self, **kwargs):
+           """
+           Override this method to specify extra/default params etc.
+           """
+           #kwargs.setdefault('foo', 'bar')
+           session = super().make_session(**kwargs)
+           return session
+
+       def hello(self):
+           """
+           Extra method to print a hello message.
+           """
+           print("hello from", self.appname)
+
+
+Then in your config file, specify that your app handler should be used
+instead of the default.  Note that the config section will need to
+match whatever the :term:`app name` is.  (And note that the app name
+is not necessarily the same as your :term:`package` name!)
+
+.. code-block:: ini
+
+   # nb. this is the default
+   [wutta]
+   app.handler = poser.app:PoserAppHandler
+
+   # but if appname is 'foobar' then it should be this
+   [foobar]
+   app.handler = poser.app:PoserAppHandler

docs/narr/handlers/arch.rst

@@ -0,0 +1,31 @@
+
+Architecture
+============
+
+Handlers are similar to a "plugin" concept in that multiple handlers
+may be installed e.g. by different packages.  But whereas one might
+"enable" multiple plugins, only *one* handler may be used, for a given
+purpose.
+
+There can be many "types" of handlers; each is responsible for a
+certain aspect of the overall app.  So it can be thought of as,
+"*Which* plugin should *handle* this aspect of the app?"
+
+
+What a Handler Does
+-------------------
+
+Each type of handler does something different.  For instance there
+might be an "auth handler" responsible for authenticating user
+credentials.
+
+The app itself will define the need for a handler.  For instance if a
+user login mechanism is needed, then the app might define the "auth
+handler" (e.g. ``AuthHandler``) base class, and add a way to locate
+and use it at runtime.
+
+Other packages might then also define "auth handlers" derived from the
+base class, and perhaps a way for the app to locate them as well.
+
+The app should probably have a way for the "choice" of auth handler to
+be configurable, and possibly expose this choice via admin UI.

docs/narr/handlers/index.rst

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

docs/narr/handlers/overview.rst

@@ -0,0 +1,10 @@
+
+Overview
+========
+
+The :term:`handler` concept is central to the :term:`app` architecture.
+
+They are analogous to "plugins" but only *one* handler is used for a
+given purpose.  See :doc:`arch`.
+
+So far there is only one handler type defined; see :doc:`app`.