[Checkins] SVN: zope.app.appsetup/trunk/ implement support functions for product configuration testing;

[Fred L. Drake, Jr.]

Log message for revision 88771:
  implement support functions for product configuration testing;
  see http://wiki.zope.org/zope3/ProductConfigurationAndTesting
  

Changed:
  U   zope.app.appsetup/trunk/CHANGES.txt
  U   zope.app.appsetup/trunk/setup.py
  U   zope.app.appsetup/trunk/src/zope/app/appsetup/product.py
  U   zope.app.appsetup/trunk/src/zope/app/appsetup/product.txt

-=-
Modified: zope.app.appsetup/trunk/CHANGES.txt
===================================================================
--- zope.app.appsetup/trunk/CHANGES.txt	2008-07-23 18:06:37 UTC (rev 88770)
+++ zope.app.appsetup/trunk/CHANGES.txt	2008-07-23 23:09:43 UTC (rev 88771)
@@ -2,7 +2,13 @@
 CHANGES
 =======
 
+Version 3.6.0 (2008-07-23)
+--------------------------
 
+- Added additional test support functions to set the configuration for a
+  single section, and save/restore the entire configuration.
+
+
 Version 3.5.0 (2008-06-17)
 --------------------------
 

Modified: zope.app.appsetup/trunk/setup.py
===================================================================
--- zope.app.appsetup/trunk/setup.py	2008-07-23 18:06:37 UTC (rev 88770)
+++ zope.app.appsetup/trunk/setup.py	2008-07-23 23:09:43 UTC (rev 88771)
@@ -25,7 +25,7 @@
 
 setup(
     name='zope.app.appsetup',
-    version='3.5.1dev',
+    version='3.6.1dev',
     author='Zope Corporation and Contributors',
     author_email='zope3-dev at zope.org',
     description="Zope app setup helper",

Modified: zope.app.appsetup/trunk/src/zope/app/appsetup/product.py
===================================================================
--- zope.app.appsetup/trunk/src/zope/app/appsetup/product.py	2008-07-23 18:06:37 UTC (rev 88770)
+++ zope.app.appsetup/trunk/src/zope/app/appsetup/product.py	2008-07-23 23:09:43 UTC (rev 88771)
@@ -28,6 +28,26 @@
     _configs.update(pconfigs)
 
 
+def setProductConfiguration(name, mapping):
+    """Set the configuration for a single product."""
+    if mapping is None:
+        if name in _configs:
+            del _configs[name]
+    else:
+        _configs[name] = mapping
+
+
+def saveConfiguration():
+    """Retrieve a shallow copy of the configuration state."""
+    return _configs.copy()
+
+
+def restoreConfiguration(state):
+    """Restore the configuration state based on a state value."""
+    _configs.clear()
+    _configs.update(state)
+
+
 class FauxConfiguration(object):
     """Configuration object that can be use from tests.
 

Modified: zope.app.appsetup/trunk/src/zope/app/appsetup/product.txt
===================================================================
--- zope.app.appsetup/trunk/src/zope/app/appsetup/product.txt	2008-07-23 18:06:37 UTC (rev 88770)
+++ zope.app.appsetup/trunk/src/zope/app/appsetup/product.txt	2008-07-23 23:09:43 UTC (rev 88771)
@@ -11,17 +11,19 @@
 code can use the API provided by the module to retrieve configuration sections
 for given names.
 
-There are two public functions in the module, and a class that can be used to
-help with testing:
+There are two public functions in the module that should be used in normal
+operations, and additional functions and a class that can be used to help with
+testing:
 
     >>> from zope.app.appsetup import product
 
 Let's look at the helper class first, since we'll use it in describing the
-public (application) interface.
+public (application) interface.  We'll follow that with the functions for
+normal operation, then the remaining test-support functions.
 
 
-Testing helper
---------------
+Faux configuration object
+-------------------------
 
 The ``FauxConfiguration`` class constructs objects that behave like the
 ZConfig section objects to the extent needed for the product configuration
@@ -86,3 +88,89 @@
 
     >>> product.getProductConfiguration("two")
     {'abc': 'def'}
+
+
+Test support functions
+----------------------
+
+Additional functions are provided that make it easier to manage configuration
+state in testing.
+
+The first can be used to provide configuration for a single name.  The
+function takes a name and either a configuration mapping or ``None`` as
+arguments.  If ``None`` is provided as the second argument, any configuration
+settings for the name are removed, if present.  If the second argument is not
+``None``, it will be used as the return value for ``getProductConfiguration``
+for the given name.
+
+    >>> product.setProductConfiguration("first", None)
+    >>> print product.getProductConfiguration("first")
+    None
+
+    >>> product.setProductConfiguration("first", {"key": "value1"})
+    >>> product.getProductConfiguration("first")
+    {'key': 'value1'}
+
+    >>> product.setProductConfiguration("first", {"key": "value2"})
+    >>> product.getProductConfiguration("first")
+    {'key': 'value2'}
+
+    >>> product.setProductConfiguration("first", {"alt": "another"})
+    >>> product.getProductConfiguration("first")
+    {'alt': 'another'}
+
+    >>> product.setProductConfiguration("second", {"you": "there"})
+    >>> product.getProductConfiguration("first")
+    {'alt': 'another'}
+    >>> product.getProductConfiguration("second")
+    {'you': 'there'}
+
+    >>> product.setProductConfiguration("first", None)
+    >>> print product.getProductConfiguration("first")
+    None
+
+The other two functions work in concert, saving and restoring the entirety of
+the configuration state.
+
+Our current configuration includes data for the "second" key, and none for the
+"first" key:
+
+    >>> print product.getProductConfiguration("first")
+    None
+    >>> print product.getProductConfiguration("second")
+    {'you': 'there'}
+
+Let's save this state:
+
+    >>> state = product.saveConfiguration()
+
+Now let's replace the kitchen sink:
+
+    >>> product.setProductConfigurations([
+    ...     product.FauxConfiguration("x", {"a": "b"}),
+    ...     product.FauxConfiguration("y", {"c": "d"}),
+    ...     ])
+
+    >>> print product.getProductConfiguration("first")
+    None
+    >>> print product.getProductConfiguration("second")
+    None
+
+    >>> product.getProductConfiguration("x")
+    {'a': 'b'}
+    >>> product.getProductConfiguration("y")
+    {'c': 'd'}
+
+The saved configuration state can be restored:
+
+    >>> product.restoreConfiguration(state)
+
+    >>> print product.getProductConfiguration("x")
+    None
+    >>> print product.getProductConfiguration("y")
+    None
+
+    >>> print product.getProductConfiguration("first")
+    None
+    >>> print product.getProductConfiguration("second")
+    {'you': 'there'}