Added __str__ to ParameterProvider.

Author: ajwdewit

pcse/base_classes.py

@@ -10,7 +10,7 @@
 import logging
 from datetime import date
 import cPickle
-from collections import Counter
+from collections import Counter, MutableMapping
 
 from .traitlets import (HasTraits, Any, Float, Int, Instance, Dict, Bool,
                         Enum, AfgenTrait)
@@ -1456,18 +1456,20 @@ def zerofy(self):
                 simobj.zerofy()
 
 
-class ParameterProvider(HasTraits):
-    """Simple class providing a dictionary-like single interface for parameter values.
+class ParameterProvider(MutableMapping):
+    """Class providing a dictionary-like interface over all parameter sets (crop, soil, site).
+    It acts very much like a ChainMap with some additional features.
 
-    The idea behind this class is twofold. First of all by encapsulating the four
-    different parameter types (e.g. sitedata, timerdata, etc) into a single object,
+    The idea behind this class is threefold. First of all by encapsulating the
+    different parameter sets (sitedata, cropdata, soildata) into a single object,
     the signature of the `initialize()` method of each `SimulationObject` can be
     harmonized across all SimulationObjects. Second, the ParameterProvider itself
     can be easily adapted when different sets of parameter values are needed. For
-    example when running PCSE with crop rotations, different sets of timerdata and
-    cropdata are needed, this can now be handled easily by enhancing
-    ParameterProvider to rotate new sets of timerdata and cropdata on a CROP_FINISH
-    signal.
+    example when running PCSE with crop rotations, different sets of cropdata
+    are needed, this can now be handled easily by enhancing
+    ParameterProvider to rotate a new set of cropdata when the engine receives a
+    CROP_START signal. Finally, specific parameter values can be easily changed
+    by setting an `override` on that parameter.
 
     See also the `MultiCropParameterProvider`
     """
@@ -1477,6 +1479,8 @@ class ParameterProvider(HasTraits):
     _cropdata = dict()
     _timerdata = dict()
     _override = dict()
+    _unique_parameters = list()
+    _iter = 0  # Counter for iterator
 
     def __init__(self, sitedata=None, timerdata=None, soildata=None, cropdata=None):
         if sitedata is not None:
@@ -1514,9 +1518,9 @@ def set_crop_type(self, crop_id=None, crop_start_type=None, crop_end_type=None):
         self._test_uniqueness()
 
     def set_override(self, varname, value, check=True):
-        """"Override the value of variable varname in the parameterprovider.
+        """"Override the value of parameter varname in the parameterprovider.
 
-        Overriding the value of particular variable is often useful for example
+        Overriding the value of particular parameter is often useful for example
         when running for different sets of parameters or for calibration
         purposes.
 
@@ -1534,7 +1538,10 @@ def set_override(self, varname, value, check=True):
             self._override[varname] = value
 
     def clear_override(self, varname=None):
-        """Removes variable varname from override, without arguments all variables are removed."""
+        """Removes parameter varname from the set of overridden parameters.
+
+        Without arguments all overridden parameters are removed.
+        """
 
         if varname is None:
             self._override.clear()
@@ -1543,24 +1550,46 @@ def clear_override(self, varname=None):
                 self._override.pop(varname)
             else:
                 msg = "Cannot clear varname '%s' from override" % varname
+                raise exc.PCSEError(msg)
 
     def _test_uniqueness(self):
-        # Check if parameter names are unique
+        """Check if parameter names are unique and raise an error if duplicates occur.
+
+        Note that the uniqueness is not tested for parameters in self._override as this
+        is specifically meant for overriding parameters.
+        """
         parnames = []
         for mapping in [self._sitedata, self._timerdata, self._soildata, self._cropdata]:
             parnames.extend(mapping.keys())
         unique = Counter(parnames)
         for parname, count in unique.items():
             if count > 1:
                 msg = "Duplicate parameter found: %s" % parname
-                raise RuntimeError(msg)
+                raise exc.PCSEError(msg)
+
+    @property
+    def _unique_parameters(self):
+        """Returns a list of unique parameter names across all sets of parameters.
+
+        This includes the parameters in self._override in order to be able to
+        iterate over all parameters in the ParameterProvider.
+        """
+        s = []
+        for mapping in self._maps:
+            s.extend(mapping.keys())
+        return sorted(list(set(s)))
 
     def __getitem__(self, key):
+        """Returns the value of the given parameter (key).
+
+        Note that the search order in self._map is such that self._override is tested first for the
+        existence of the key. Thus ensuring that overridden parameters will be found first.
+
+        :param key: parameter name to return
+        """
         for mapping in self._maps:
-            try:
+            if key in mapping:
                 return mapping[key]
-            except KeyError:
-                pass
         raise KeyError(key)
 
     def __contains__(self, key):
@@ -1569,6 +1598,59 @@ def __contains__(self, key):
                 return True
         return False
 
+    def __str__(self):
+        msg = "ParameterProvider providing %i parameters, %i parameters overridden: %s."
+        return msg % (len(self), len(self._override), self._override.keys())
+
+    def __setitem__(self, key, value):
+        """Override an existing parameter (key) by value.
+
+         The parameter that is overridden is added to self._override, note that only *existing*
+         parameters may be overridden this way. If it is needed to really add a *new* parameter
+         than use: ParameterProvider.set_override(key, value, check=False)
+
+        :param key: The name of the parameter to override
+        :param value: the value of the parameter
+        """
+        if key in self:
+            self._override[key] = value
+        else:
+            msg = ("Cannot override parameter '%s', parameter does not exist. "
+                  "to bypass this check use: set_override(parameter, value, check=False)") % key
+            raise exc.PCSEError(msg)
+
+    def __delitem__(self, key):
+        """Deletes a parameter from self._override.
+
+        Note that only parameters that exist in self._override can be deleted. This also means that
+        if an parameter is overridden its original value will return after a parameter is deleted.
+
+        :param key: The name of the parameter to delete
+        """
+        if key in self._override:
+            self._override.pop(key)
+        elif key in self:
+            msg = "Cannot delete default parameter: %s" % key
+            raise exc.PCSEError(msg)
+        else:
+            msg = "Parameter not found!"
+            raise KeyError(msg)
+
+    def __len__(self):
+        return len(self._unique_parameters)
+
+    def __iter__(self):
+        return self
+
+    def next(self):
+        i = self._iter
+        if i < len(self):
+            self._iter += 1
+            return self._unique_parameters[self._iter-1]
+        else:
+            self._iter = 0
+            raise StopIteration
+
 class MultiCropParameterProvider(ParameterProvider):
     """Parameter provider that allows multiple crop
     parameter sets to be specified. This ParameterProvider is