From 23fe3a3fcb7b8a74f51fcadb915b5b8fafea368e Mon Sep 17 00:00:00 2001 From: Aaron LI Date: Mon, 17 Oct 2016 14:11:10 +0800 Subject: configs/manager.py: Various updates to docstring and comments. No functional changes. --- fg21sim/configs/manager.py | 67 ++++++++++++++++++++++++++++++---------------- 1 file changed, 44 insertions(+), 23 deletions(-) (limited to 'fg21sim/configs') diff --git a/fg21sim/configs/manager.py b/fg21sim/configs/manager.py index 8d2cab5..bb06394 100644 --- a/fg21sim/configs/manager.py +++ b/fg21sim/configs/manager.py @@ -41,15 +41,35 @@ def _get_configspec(): class ConfigManager: - """Manager the configurations""" - def __init__(self, configs=None): - """Initialize the ConfigManager object with default configurations. - If user configs are given, they are also validated and get merged. + """Manage the default configurations with specifications, as well as + the user configurations. - Parameters - ---------- - configs: list (of config files) - (optional) list of user config files to be merged + Both the default configurations and user configurations are validated + against the bundled specifications. + + Parameters + ---------- + configs: list[str], optional + List of user config files to be merged + + Attributes + ---------- + _config : `~configobj.ConfigObj` + The current effective configurations. + _configspec : `~configobj.ConfigObj` + The configuration specifications bundled with this package. + userconfig : str + The filename and path to the user-provided configurations. + NOTE: + - This attribute only presents after loading the user configuration + by ``self.read_userconfig()``; + - This attribute is used to determine the absolute path of the + configs specifying the input templates or data files, therefore + allow the use of relative path for those configs. + """ + def __init__(self, configs=None): + """Initialize with the bundled default configurations and + specifications. """ configspec = _get_configspec() self._configspec = ConfigObj(configspec, interpolation=False, @@ -66,7 +86,7 @@ class ConfigManager: Parameters ---------- - config : str, list[str] + config : str, or list[str] Input config to be validated and merged. This parameter can be the filename of the config file, or a list contains the lines of the configs. @@ -91,11 +111,11 @@ class ConfigManager: NOTE ---- - The user configuration file can be loaded *only once*, - or *only one* user configuration file supported. - Since the *path* of the user configuration file is recorded, - and thus allow the use of *relative path* of some input files - (e.g., galactic/synchrotron/template) within the configurations. + The user configuration file can be loaded *only once*, i.e., + *only one* user configuration file supported. + Since the *path* of the user configuration file is recorded, and + thus allow the use of *relative path* of some input files (e.g., + "galactic/synchrotron/template") within the configurations. """ if hasattr(self, "userconfig"): raise ConfigError('User configuration already loaded from "%s"' % @@ -108,7 +128,7 @@ class ConfigManager: # self.read_config(config) self.userconfig = os.path.abspath(userconfig) - logger.info("Loaded user config: {0}".format(userconfig)) + logger.info("Loaded user config: {0}".format(self.userconfig)) def _validate(self, config): """Validate the config against the specification using a default @@ -146,14 +166,15 @@ class ConfigManager: Parameters ---------- - key : str / list[str] + key : str, or list[str] List of keys or a string separated by a specific character - (e.g., "/") to specify the item in the `self._config`, which + (e.g., "/") to specify the item in the ``self._config``, which is a nested dictionary. - e.g., `["section1", "key2"]`, `"section1/key2"` - sep : str (len=1) + e.g., ``["section1", "key2"]``, ``"section1/key2"`` + sep : str (len=1), optional If the above "keys" is a string, then this parameter specify the character used to separate the multi-level keys. + This parameter should be a string of length 1 (i.e., a character). References ---------- @@ -178,8 +199,8 @@ class ConfigManager: ------- path : str The absolute path (if user configuration loaded) or relative - path specified by the input key, or `None` if specified config - is `None`. + path specified by the input key, or ``None`` if specified + config is ``None``. Raises ------ @@ -234,8 +255,8 @@ class ConfigManager: NOTE ---- - ``basicConfig()`` will automatically create a ``Formatter`` with - the giving ``format`` and ``datefmt`` for each handlers if necessary, + ``basicConfig()`` will automatically create a ``Formatter`` with the + giving ``format`` and ``datefmt`` for each handlers if necessary, and then adding the handlers to the "root" logger. """ from logging import FileHandler, StreamHandler -- cgit v1.2.2