From fe9fa59e7694989708ab16914dd2fca3e7d553dc Mon Sep 17 00:00:00 2001 From: Wirawan Purwanto Date: Thu, 11 Apr 2013 14:06:14 -0400 Subject: [PATCH] * params_flat.py: Documentation and note updates. --- params/params_flat.py | 58 +++++++++++++++++++++++++++---------------- 1 file changed, 37 insertions(+), 21 deletions(-) diff --git a/params/params_flat.py b/params/params_flat.py index f0d952a..2af9151 100644 --- a/params/params_flat.py +++ b/params/params_flat.py @@ -33,8 +33,8 @@ class Parameters(dict): This, hopefully, gets rid of kitchen-sink parameter passing, at least from programmer's point of view. - WARNING: This object is derived from python dict with ALL method names removed, - so as to avoid collosion of these names with user-defined parameters with the + WARNING: This object is derived from python dict with ALL method names removed, (#FIXME# Not true yet) + so as to avoid collision of these names with user-defined parameters with the same name. Names reserved by this class begin and end with an underscore. Names reserved by python begin and end with two underscores. @@ -59,6 +59,8 @@ class Parameters(dict): a = Parameters(...) updates = {'nblk': 7, 'nbasis': 32} a += updates + #FIXME# ^^^ right now this does not operate in-place, but + #FIXME# returns a new Parameters object, which may not be desirable or, to call a function with a combination of parameters: @@ -138,18 +140,10 @@ class Parameters(dict): function argument list (default: `_opts_'). * _userparam_ = the name of the explicitly defined user-defined parameter (of a dict type) in the function argument list (default: `_p'). - * _localvars_ = set to true to include function local variables in the - lookup chain. Default is False because it can be very confusing! - We just have no control on what local variables would be involved - in a function and the sheer potential of creating vars with the same name - as the value we want to look up---all will open up to infinite possibility - of surprises. - At present, the `_localvars_' attribute will not be propagated to the child - Parameters objects created by this parent object. - Caveat: only variables defined till the point of calling of the method - _create_() below will be searched in the lookup process. - Values defined or updated later will not be reflected in the lookup process. - (See params_flat_test.py, test2 and test2b routines.) + * _localvars_ = set to true to include function local variables by their names + in the lookup chain of the new Parameters object created by _create_() + method below. + See the documentation in _create_() method for cautionary notes. """ # Remove standard dict procedure names not beginning with "_": @@ -159,6 +153,7 @@ class Parameters(dict): # Store the user-defined overrides in its own container: dict.clear(self) if _opts_.get('_flatten_', False): + #FIXME# if p is a Parameters object, then we must recursively flatten it too for p in _override_dicts_: dict.update(self, p) dict.update(self, _opts_) @@ -180,7 +175,7 @@ class Parameters(dict): #if badkw in self: del self[badkw] -- recursive!!! if dict.__contains__(self,badkw): del self[badkw] def _copy_(self): - """Returns a copy of the Parameters() object.""" + """Returns a (shallow) copy of the Parameters() object.""" return Parameters(_no_null_=self._no_null_, _kwparam_=self._kwparam_, _userparam_=self._userparam_, @@ -278,6 +273,7 @@ class Parameters(dict): K = dict() _list_ = self.__dict__["_list_"] for D in _list_[::-1]: + #FIXME# if D is a Parameters object then we must recursively flatten it too K.update([ (k,D[k]) for k in D ]) return K @@ -308,22 +304,27 @@ class Parameters(dict): def __add__(self, srcdict): """Returns a copy of the Parameters() object, with the most-overriding parameters updated from the contents of srcdict.""" + # FIXME: this operation looks counterintuitive; may want to consider + # using "<<" alternate operator naming if we ever, ever use this. + # (And similarly, "<<=". rslt = self._copy_() rslt._update_(srcdict) return rslt - __or__ = __add__ + __or__ = __add__ # DON'T! def _create_(self, *defaults, **_options_): """Creates a new Parameters() object for standardized function-level parameter lookup. - This routine *must* be called by the function where we want to access these - parameters, and where some parameters are to be overriden via function + This routine *must* be called by the function where we want to use these + parameters, and their values can be overridden via function arguments, etc. - The order of lookup is definite: + The order of the lookup is deterministic: * local variables of the calling subroutine will take precedence (if _localvars_ is set to True) - * the excess keyword-based parameters, - * user-supplied Parameters-like object, which is + * the excess keyword-based parameters (given by pre-set variable name, + which by default is "_opts_") + * user-supplied Parameters-like object, which by default is the + keyword-based parameter "_p") * the dicts (passed in the `defaults' unnamed parameter list) is searched *last*. I suggest that this is used only as a last-effort safety net. @@ -355,6 +356,21 @@ class Parameters(dict): - _localvars_ (boolean) = whether to include the local vars in the lookup chain. Default: None; refer back to the object's _localvars_ attribute. + + Cautions for using `_localvar_` option: + 1) The default is False because it can be very confusing! + We just have no control on what local variables would be involved + in a function and the sheer potential of creating vars with the same name + as the value we want to look up---all will open up to infinite possibility + of surprises. + 2) At present, the value of the `_localvars_' option will not be + propagated to the Parameters objects created by this parent + object. + 3) Only local variables defined up to the calling of the _create_() method + will be captured. + Any new local variables or update to the variable values will not be + reflected in the Parameters object created by this method. + (See params_flat_test.py, test2 and test2b routines.) """ # Look up the stack of the calling function in order to retrieve its # local variables