Drop of v.0.5.5

Author: vassilyl

.flake8

@@ -0,0 +1,2 @@
+[flake8]
+exclude = .git,.venv,__pycache__

.vscode/settings.json

@@ -0,0 +1,12 @@
+{
+    "python.pythonPath": "c:\\v\\github\\microsoft\\msrc-appconfig\\.venv\\Scripts\\python.exe",
+    "python.analysis.typeCheckingMode": "basic",
+    "python.analysis.extraPaths": [
+        "msrc-appconfig",
+        "msrc-appconfig/tests",
+        "msrc-appconfig-attrs",
+        "msrc-appconfig-dataclasses",
+        "msrc-appconfig-param"
+    ],
+    "python.testing.pytestEnabled": true
+}

API.md

@@ -0,0 +1,323 @@
+<!--
+    THIS FILE HAS BEEN AUTO-GENERATED BY api_md.py
+-->
+# msrc.appconfig
+
+Flexible typed application configuration.
+
+| Functions | |
+| --- | --- |
+| [gather_config](#gather_config) | Gathers configuration values from files, shell and command line. |
+| [set_global](#set_global) | Designates the `appconfig` as global application configuration object. |
+| [get_global](#get_global) | Get global application configuration object. |
+| [from_files](#from_files) | Collects configuration values from the specified files. |
+| [from_environ](#from_environ) | Collects configuration values from shell variables. |
+| [from_argv](#from_argv) | Collects configuration values from command line arguments. |
+| [from_dict](#from_dict) | Instantiates configuration object from a dictionary of values. |
+| [to_dict](#to_dict) | Extracts data from a configuration object. |
+| [optional_file](#optional_file) | Returns a list with the file `Path` if the file exists. |
+| [script_config_file](#script_config_file) | Returns a list with the default script configuration file. |
+| [config_files_in_parents](#config_files_in_parents) | Returns a list of configuration files in parent directories. |
+| [to_arg_dict](#to_arg_dict) | Generates a dictionary of cmdline options to reproduce the instance. |
+| [to_argv](#to_argv) | Generates a flat list of cmdline options to reproduce the instance. |
+
+## gather_config
+```python
+def msrc.appconfig.gather_config(
+    config_type: Type[~AppConfig],
+    override_defaults: Mapping[str, Union[str, Tuple[str, ...], List[str], int, Tuple[int, ...], List[int], float, Tuple[float, ...], List[float], bool, Tuple[bool, ...], List[bool], enum.Enum, Tuple[enum.Enum, ...], List[enum.Enum], Mapping[str, object]]] = {},
+    config_files: Sequence[Union[str, os.PathLike]] = [],
+    env_var_prefix: Union[str, NoneType] = None,
+    argv: Union[Sequence[str], NoneType] = None,
+    arg_aliases: Mapping[str, str] = {},
+    set_global: bool = False,
+    log_level: int = 20,
+) -> ~AppConfig
+```
+Gathers configuration values from files, shell and command line.
+
+The function is a main tool to build application configuration object
+for a script.
+
+`config_type` is the only required argument. Must be is a class object.
+The `config_type` can be a `typing.NamedTuple` or a class supported by
+one of the package extensions.
+
+`override_defaults` is a mapping that allows to override the defaults
+in the `config_type` class.
+
+`config_files` is a sequence of configuration file paths, strings
+or `PathLike` objects. The function reads the files in sequence.
+See also utility functions that help build the list for certain
+use cases: `script_config_file()`, `config_files_in_parents()`,
+`optional_file()`.
+See also `-c` command line option below.
+
+`env_var_prefix` is a prefix to look for shell environment variables
+that override configuration values. The default is main script file name
+followed by underscore. For example, if you run a script in `script.py`
+then by default environment variables `SCRIPT_<config-element>=<value>`
+override values from `config_type` class, `override_defaults` mapping
+and configuration files.
+See also `-e` command line option below.
+
+`argv` is an optional list of command line arguments to be used instead
+of `sys.argv`.
+
+`arg_aliases` is a mapping `{short_option: long_option}`, where
+`short_option` must be a string of length one, and `long_option` can be
+a configuration element path. E.g. `arg_aliases=dict(b="foo.bar")`
+allows to use `-b` option as an alias of `--foo.bar` option to set the
+`config.foo.bar` value with command line arguments. `arg_aliases` override
+the built-in short options (see below).
+
+`set_global` allows to set up global application configuration object.
+The default value is `False`. See `set_global()` function for details.
+
+`log_level` sets logging level for the package. The default is `INFO`.
+To log more details set `log_level` to `DEBUG`, to reduce the amount of
+logging set `log_level` to `WARN` or `ERROR`. Set it to `NOTSET`to prevent
+setting up the logging system by the package: `log_level=logging.NOTSET`.
+See also `-l` command line option below.
+
+The function uses standard argparser module to parse command line
+arguments. Four options amend configuration process, others override
+configuration values obtained from other sources.
+`-h [ELEMENT]` option prints general help or description of a
+confuguration element.
+`-l LEVEL|FILE` option sets up logging level overriding `log_level`
+argument. If file path is provided instead, the `logging.fileConfig()`
+function is called.
+`-c FILE ...` option specifies which configuration files to read. The files
+are appended to the list given in `config_files` argument`.
+See `msrc.config_type.read_files.from_file` function for details.
+`-e PREFIX` option overrides a prefix for environment variables to look up.
+See `msrc.config_type.read_environ.from_environ function for details.
+
+To prevent looking up shell variables set `env_var_prefix` to `"-"`.
+To prevent reading from `sys.argv` set `argv` to `()`.
+To prevent setting up logging set `log_level` to `logging.NOTSET` value.
+
+If `set_global==True`, sets up the collected configuration as
+a global object for current process. The shared object is easily accessible
+in other modules with `get_global()` function.
+
+Returns the collected configuration.
+
+## set_global
+```python
+def msrc.appconfig.set_global(
+    appconfig: ~AppConfig,
+) -> None
+```
+Designates the `appconfig` as global application configuration object.
+
+The configuration becomes available with 'get_global()' throughout the
+application code base. Must be called only once per process.
+
+Raises `RuntimeError` if a configuration has already been set up.
+Meant to be used primarily behind `if __name__=="__main__"` guards.
+
+Raises `TypeError` if type of appconfig is not a valid configuration
+schema.
+
+## get_global
+```python
+def msrc.appconfig.get_global(
+    appconfig: Type[~AppConfig],
+    default: Union[~AppConfig, NoneType] = None,
+) -> ~AppConfig
+```
+Get global application configuration object.
+
+`appconfig` must be a type. `appconfig` argument ensures an object
+returned by the function is an instance of this type, or `ValueError`
+is raised.
+
+`default` object must be an instance of `appconfig` type. The function
+returns `default` if no global application configuration has been set up.
+
+Raises `RuntimeError` if no global application configuration has been
+set up by `set_global()` or `gather_config(set_global=True)` and
+the `default` is `None`.
+
+For example, if `AppConfig` is an appconfig schema where all elements
+have default values, then the following line never raises `RuntimeError`:
+```python
+value = msrc.appconfig.get_global(AppConfig, AppConfig()).parameter
+```
+In contrast this line:
+```python
+value = msrc.appconfig.get_global(AppConfig).parameter
+```
+raises `RuntimeError` if global configuration hasn't been set up.
+The following code never raises exceptions and can be used to safely
+check for a generic configuration:
+```python
+cfg_none = object()
+cfg = msrc.appconfig.get_global(object, cfg_none)
+if cfg is cfg_none:
+    ...
+```
+
+## from_files
+```python
+def msrc.appconfig.from_files(
+    config_schema: Type,
+    files: Union[str, os.PathLike],
+) -> Mapping[str, Union[str, Tuple[str, ...], List[str], int, Tuple[int, ...], List[int], float, Tuple[float, ...], List[float], bool, Tuple[bool, ...], List[bool], enum.Enum, Tuple[enum.Enum, ...], List[enum.Enum], Mapping[str, object]]]
+```
+Collects configuration values from the specified files.
+
+Accepts files with the following extensions: .ini, .json, .yaml, .yml.
+Given a file with a different extension, tries to look up a file
+with the same name and one of recognized extensions.
+
+Each .json or .yaml/.yml  file must represent a JSON or YAML dictionary.
+The function ignores keys that are not in schema.
+A special key '_include' may contain a path or a list of paths to read.
+The function reads included files before processing the rest of the keys,
+i.e. values in the file may override values from included files.
+
+In case the same key is present in multiple files, the resulting dictionary
+contains a value from the last file.
+
+## from_environ
+```python
+def msrc.appconfig.from_environ(
+    config_schema: Type,
+    env_var_prefix: str = '',
+) -> Mapping[str, Union[str, Tuple[str, ...], List[str], int, Tuple[int, ...], List[int], float, Tuple[float, ...], List[float], bool, Tuple[bool, ...], List[bool], enum.Enum, Tuple[enum.Enum, ...], List[enum.Enum], Mapping[str, object]]]
+```
+Collects configuration values from shell variables.
+
+For a configuration element <element_name> takes value from an environment
+variable <env_var_prefix><element_name> if one exists.
+
+## from_argv
+```python
+def msrc.appconfig.from_argv(
+    config_schema: Type,
+    argv: Sequence[str],
+    arg_aliases: Mapping[str, str] = {},
+) -> Mapping[str, Union[str, Tuple[str, ...], List[str], int, Tuple[int, ...], List[int], float, Tuple[float, ...], List[float], bool, Tuple[bool, ...], List[bool], enum.Enum, Tuple[enum.Enum, ...], List[enum.Enum], Mapping[str, object]]]
+```
+Collects configuration values from command line arguments.
+
+The function employs standard module argparse to parse arguments.
+If a configuration element has underscores in its name the option may use
+either underscores or dashes.
+
+The optional `arg_aliases` argument allows to add short options to the
+command line interface. Aliases key must be a configuration element name,
+and corresponding value must be a single letter of the short option.
+
+Unrecognized `argv` elements, if any, are under `_unknown_args` key in
+the returned mapping.
+
+## from_dict
+```python
+def msrc.appconfig.from_dict(
+    config_schema: Type[~AppConfig],
+    data: Mapping[str, Union[str, Tuple[str, ...], List[str], int, Tuple[int, ...], List[int], float, Tuple[float, ...], List[float], bool, Tuple[bool, ...], List[bool], enum.Enum, Tuple[enum.Enum, ...], List[enum.Enum], Mapping[str, object]]],
+) -> ~AppConfig
+```
+Instantiates configuration object from a dictionary of values.
+
+## to_dict
+```python
+def msrc.appconfig.to_dict(
+    instance: ~AppConfig,
+    include_defaults: bool = False,
+) -> Mapping[str, Union[str, Tuple[str, ...], List[str], int, Tuple[int, ...], List[int], float, Tuple[float, ...], List[float], bool, Tuple[bool, ...], List[bool], enum.Enum, Tuple[enum.Enum, ...], List[enum.Enum], Mapping[str, object]]]
+```
+Extracts data from a configuration object.
+
+Returns a nested dictionary of configuration values.
+
+When `include_defaults` is False (the default value) the resulting
+dictionary doesn't contain elements with built-in default values.
+
+## optional_file
+```python
+def msrc.appconfig.optional_file(
+    file_path: Union[str, os.PathLike],
+) -> List[pathlib.Path]
+```
+Returns a list with the file `Path` if the file exists.
+
+Returns an empty list if `file_path` doesn't reference an existing file.
+
+Useful to build a list of configuration files, e.g.:
+```python
+cfg = gather_config(
+    AppConfig,
+    config_files=optional_file('config.yml')
+)
+```
+
+## script_config_file
+```python
+def msrc.appconfig.script_config_file(
+    ext: Union[str, NoneType] = None,
+) -> List[pathlib.Path]
+```
+Returns a list with the default script configuration file.
+
+`ext` is an optional configuration file extension. Must be one of
+supported extensions. If `ext` not specified, the function tries
+all supported extensions.
+
+A default configuration file has a name of a main script file or
+a package name if a package is being run. The function lookes for
+the file in the main script directory, or in current directory if
+a package is being run.
+
+Useful to build a list of configuration files, e.g.:
+```python
+cfg = gather_config(
+    AppConfig,
+    config_files=script_config_file('.yml')
+)
+```
+
+## config_files_in_parents
+```python
+def msrc.appconfig.config_files_in_parents(
+    file_name: str,
+    base_path: Union[NoneType, str, pathlib.Path] = None,
+) -> List[pathlib.Path]
+```
+Returns a list of configuration files in parent directories.
+
+`file_name` must be a file name with one of supported extensions.
+
+`base_path` is an optional final path. The default is main script
+directory, or current directory if a package is being run.
+
+Returns a list of all files found along the `base_path` starting
+from the root.
+
+Useful to build a list of configuration files, e.g.:
+```python
+cfg = gather_config(
+    AppConfig,
+    config_files=config_files_in_parents('config.yml')
+)
+```
+
+## to_arg_dict
+```python
+def msrc.appconfig.to_arg_dict(
+    instance: ~AppConfig,
+) -> Dict[str, Union[str, Tuple[str, ...]]]
+```
+Generates a dictionary of cmdline options to reproduce the instance.
+
+## to_argv
+```python
+def msrc.appconfig.to_argv(
+    instance: ~AppConfig,
+) -> List[str]
+```
+Generates a flat list of cmdline options to reproduce the instance.

CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing
+
+Welcome and thank you for your interest
+in contributing to `one-appconfig`! Before contributing to this
+project, please review this document for policies and procedures which
+will ease the contribution and review process for everyone. If you have
+questions, please contact Vassily Lyutsarev vassilyl@microsoft.com. This project adopted
+[Inner Source model](http://aka.ms/innersource).
+
+## Issues and Feature Requests
+
+Issues, bugs and proposed new features should be submitted to our [backlog](https://msrcambridge.visualstudio.com/One/_backlogs/backlog/msrc-appconfig/Issues/). The project uses [Basic process](https://docs.microsoft.com/en-us/azure/devops/boards/get-started/plan-track-work?view=azure-devops&tabs=basic-process) which assumes your input is filed
+as an _Issue_. You may also tag the issue with a Bug tag which is optional. Please specify in detail the versions of python and msrc-appconfig package, and a detailed repro for the issue.
+
+## Style Guidelines
+
+The project has adopted [PEP 8](https://www.python.org/dev/peps/pep-0008/) style for code.
+We use [flake8](https://pypi.org/project/flake8/) with default options to lint the code.
+Additionally, the [mypy](http://www.mypy-lang.org/) static type checker must run without issues on the code.
+
+## Pull Request Process
+
+1. Prepare your changes in a branch named `<your-alias>/<short-feature-description>`. 
+   Alternativly, you may create your personal
+   [fork](https://docs.microsoft.com/en-us/azure/devops/repos/git/forks?view=azure-devops) 
+   of the repository in Forks project.
+1. All new code must come with corresponding [pytest](https://docs.pytest.org/en/latest/) tests. Keep code coverage at 100%.
+1. Ensure CI build is successful and tests, including any added or updated tests, pass prior to submitting the pull request.
+1. Update any documentation, user and contributor, that is impacted by your changes.
+1. Do not change the version number in VERSION.txt.
+1. Do not merge your pull request, this is the responsibility of a core developer.
+
+## License Information
+
+The project can be used for Microsoft internal purposes without any limitation.
+To use the package outside of Microsoft contact Vassily Lyutsarev vassilyl@microsoft.com.