From 73b1d6c15199e6d4c825a080cd81f3305850a35b Mon Sep 17 00:00:00 2001
From: "Karl O. Pinc" <kop@karlpinc.com>
Date: Mon, 31 Aug 2020 10:05:33 -0500
Subject: [PATCH] Add documentation of component checking

---
 README.rst | 103 +++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 93 insertions(+), 10 deletions(-)

diff --git a/README.rst b/README.rst
index d585991..34f6039 100644
--- a/README.rst
+++ b/README.rst
@@ -336,10 +336,19 @@ in production is not recommended.
 Writing Plugable Components
 ---------------------------
 
-Your setup.py must include a ``pgwui.components`` entry point.\ [#f1]_
-The value assigned to the given module must be the name of the PGWUI
-component which the module impliments.  There must also be a
-``pgwui.check_settings`` entrypoint conforming to the following::
+In order to be a PGWUI component that is auto-configurable your
+setup.py must include a ``pgwui.components`` entry point.\ [#f1]_ More
+detail is provided below.
+
+You module can (should) check the settings it receives for validity.
+Expected checks are for missing required settings and unknown
+settings.  It is also desirable to check that setting values conform
+to expectations; boolean settings contain only boolean values, and
+other settings contain only the expected values.
+
+To check settings your component must contain a function of one argument,
+as follows:
+
 
    def check_settings(component_config):
 
@@ -354,19 +363,69 @@ component which the module impliments.  There must also be a
        of UnknownSettingKeyError but it may be anything with a string
        representation.
 
+PGWUI_Common contains helpers to use when checking settings.  An
+example setting checker from PGWUI_Upload is::
+
+   from pgwui_common import checkset
+
+
+   PGWUI_COMPONENT = 'pgwui_upload'
+   UPLOAD_SETTINGS = ['menu_label',
+                      ]
+   REQUIRED_SETTINGS = []
+   BOOLEAN_SETTINGS = []
+
+
+   def check_settings(component_config):
+       '''Check that all pgwui_upload specific settings are good.
+       This includes:
+         checking for unknown settings
+         checking for missing required settings
+         checking the boolean settings
+         checking that the values of other settings are valid
+       '''
+       return (
+           checkset.unknown_settings(
+               PGWUI_COMPONENT, UPLOAD_SETTINGS, component_config)
+           .extend(checkset.require_settings(
+               PGWUI_COMPONENT, REQUIRED_SETTINGS, component_config)
+               .extend(checkset.boolean_settings(
+                   PGWUI_COMPONENT, BOOLEAN_SETTINGS, component_config))))
+
+When establishing the entrypoint for your PGWUI componenent the name
+of the entrypoint is the name of the pgwui component.  The value
+assigned to the given module must be the name of the PGWUI component
+which the module impliments.  So the syntax is:
+
+   entry_points={'pgwui.components': '.COMPONENTNAME = MODULEPATH', ...}
+
+
+Where MODULEPATH is a period separated list of module names.
+(MODULENAME{.MODULENAME}...)
+
+There must also be a ``pgwui.check_settings`` entrypoint to specify
+the setting checker.  The syntax is:
+
+   entry_points={'pgwui.check_settings':
+                 '.COMPONENTNAME = MODULEPATH:FUNCTIONNAME', ...}
+
 In the case of the ``pgwui_upload`` module, both the module name and
 the component name are "pgwui_upload".  The check_settings module name
 is ``check_settings`` and the function which does the check has the
-same name.  So the entry point assignment looks like::
+same name.  So the entry point assignment in setup.py looks like::
 
     # Setup an entry point to support PGWUI autoconfigure discovery.
-    entry_points={'pgwui.components': '.pgwui_upload = pgwui_upload',
-                  'pgwui.check_settings':
-                      '.pgwui_upload = check_settings:check_settings'}
+    entry_points={
+        'pgwui.components': '.pgwui_upload = pgwui_upload',
+        'pgwui.check_settings':
+        '.pgwui_upload = pgwui_upload.check_settings:check_settings'}
 
 
-Your module's ``__init__.py`` must setup the component's default
-configuration::
+Your package's ``__init__.py`` must setup the component's default
+configuration.  It should contain a ``includeme(config)``
+function. This is used by Pyramid to initialize the component at
+module load time, and should establish defaults for settings as part
+of it's initialization::
 
    '''Provide a way to configure PGWUI.
    '''
@@ -394,6 +453,30 @@ configuration::
        config.scan()
 
 
+The PGWUI_Testing component contains fixtures to test that your
+component's entry points are correctly setup::
+
+   from pgwui_testing import testing
+
+   # Activiate our pytest plugin
+   pytest_plugins = ("pgwui",)
+
+
+   # Module packaging test
+
+   def test_pgwui_upload_is_pgwui_component(pgwui_component_entry_point):
+       '''Ensure that pgwui_upload is a pgwui.component entry point
+       '''
+       assert pgwui_component_entry_point('pgwui_upload') is True
+
+   def test_check_setting_is_pgwui_check_settings(
+           pgwui_check_settings_entry_point):
+       '''Ensure that pgwui_upload has a pgwui.check_settings entry point
+       '''
+       assert (pgwui_check_settings_entry_point('pgwui_upload.check_settings')
+               is True)
+
+
 Complete Documentation
 ----------------------
 
-- 
2.34.1