From 913d3aee9eaba013152142114e8097c2436bd86e Mon Sep 17 00:00:00 2001 From: Nicolas Chauvat Date: Thu, 20 Jun 2013 10:16:00 +0200 Subject: [configuration] add comments to improve documentation --- configuration.py | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/configuration.py b/configuration.py index ef0dc0c..befcd5a 100644 --- a/configuration.py +++ b/configuration.py @@ -136,6 +136,9 @@ def _get_encoding(encoding, stream): # validation functions ######################################################## +# validators will return the validated value or raise optparse.OptionValueError +# XXX add to documentation + def choice_validator(optdict, name, value): """validate and return a converted value for option of type 'choice' """ @@ -230,6 +233,10 @@ def _call_validator(opttype, optdict, option, value): # user input functions ######################################################## +# user input functions will ask the user for input on stdin then validate +# the result and return the validated value or raise optparse.OptionValueError +# XXX add to documentation + def input_password(optdict, question='password:'): from getpass import getpass while True: @@ -264,6 +271,8 @@ INPUT_FUNCTIONS = { for opttype in VALIDATORS.keys(): INPUT_FUNCTIONS.setdefault(opttype, _make_input_function(opttype)) +# utility functions ############################################################ + def expand_default(self, option): """monkey patch OptionParser.expand_default since we have a particular way to handle defaults to avoid overriding values in the configuration @@ -299,6 +308,8 @@ def _validate(value, optdict, name=''): return _call_validator(_type, optdict, name, value) convert = deprecated('[0.60] convert() was renamed _validate()')(_validate) +# format and output functions ################################################## + def comment(string): """return string as a comment""" lines = [line.strip() for line in string.splitlines()] @@ -402,6 +413,7 @@ def rest_format_section(stream, section, options, encoding=None, doc=None): print >> stream, '' print >> stream, ' Default: ``%s``' % value.replace("`` ", "```` ``") +# Options Manager ############################################################## class OptionsManagerMixIn(object): """MixIn to handle a configuration from both a configuration file and @@ -735,6 +747,7 @@ class Method(object): assert self._inst, 'unbound method' return getattr(self._inst, self.method)(*args, **kwargs) +# Options Provider ############################################################# class OptionsProviderMixIn(object): """Mixin to provide options to an OptionsManager""" @@ -793,7 +806,6 @@ class OptionsProviderMixIn(object): def set_option(self, opt, value, action=None, optdict=None): """method called to set an option (registered in the options list) """ - # print "************ setting option", opt," to value", value if optdict is None: optdict = self.get_option_def(opt) if value is not None: @@ -895,6 +907,7 @@ class OptionsProviderMixIn(object): for optname, optdict in options: yield (optname, optdict, self.option_value(optname)) +# configuration ################################################################ class ConfigurationMixIn(OptionsManagerMixIn, OptionsProviderMixIn): """basic mixin for simple configurations which don't need the @@ -993,6 +1006,7 @@ class OptionsManager2ConfigurationAdapter(object): except AttributeError: return default +# other functions ############################################################## def read_old_config(newconfig, changes, configfile): """initialize newconfig from a deprecated configuration file -- cgit v1.2.1