# -*- coding: utf-8 -*-
from setuptools import setup

packages = \
['onacol']

package_data = \
{'': ['*']}

install_requires = \
['Cerberus>=1.3.4,<2.0.0',
 'cascadict>=0.8.4,<0.9.0',
 'ruamel.yaml>=0.17.10,<0.18.0']

setup_kwargs = {
    'name': 'onacol',
    'version': '0.3.1',
    'description': 'Oh No! Another Configuration Library',
    'long_description': '=============================================\nONACOL (Oh No! Another COnfiguration Library)\n=============================================\n\n.. image:: https://badge.fury.io/py/onacol.svg\n        :target: https://badge.fury.io/py/onacol\n\n.. image:: https://github.com/calcite/onacol/actions/workflows/test.yaml/badge.svg?branch=main\n        :target: https://github.com/calcite/onacol/actions/workflows/test.yaml\n\n.. image:: https://readthedocs.org/projects/onacol/badge/?version=latest\n        :target: https://onacol.readthedocs.io/en/latest/?version=latest\n        :alt: Documentation Status\n\n.. image:: https://coveralls.io/repos/github/calcite/onacol/badge.svg?branch=main\n        :target: https://coveralls.io/github/calcite/onacol?branch=main\n        :alt: Test coverage Status\n\n.. image:: https://img.shields.io/pypi/pyversions/onacol\n        :alt: PyPI - Python Version\n\nOnacol is a low-opinionated configuration management library with following\nfeatures:\n\n* YAML (=structured and hierarchical) configuration file support\n* Environment variables support (explicit and implicit)\n* CLI arguments support\n* Configuration merging/overwriting/layering\n* Parameter validation (via Cerberus_)\n* Configuration schema, documentation and default values are defined in\n  single YAML -> No code schema.\n* Minimal dependencies\n\nComparison with other Python configuration libraries/frameworks\n---------------------------------------------------------------\n\nAs the library name suggests, author is painfully aware this is not a unique\nsolution to the problem of application configuration. However, in the plethora\nof existing solutions, none was completely fulfilling the features/requirements\nmentioned above. So, with great reluctance,\n`I had to make my own <https://xkcd.com/927/>`_.\n\nFollowing table lists known/popular configuration frameworks and their\nfeatures relative to Onacol, but not comparing other features that some of those\nlibraries have and Onacol doesn\'t, so check them out - you may find it suits\nyour need better.\n\n\n.. list-table:: Popular configuration framework comparison\n    :widths: 30 10 10 10 10 10 10\n    :header-rows: 1\n\n    * - Framework\n      - YAML\n      - ENV vars\n      - CLI args\n      - Merging\n      - Validation\n      - No code schema\n    * - Hydra_\n      - ✔️\n      - ✔️\n      - ❓\n      - ✔️\n      - ✔️\n      - ✖️\n    * - Pydantic_\n      - ❓\n      - ❓\n      - ✔️\n      - ✔️\n      - ✔️\n      - ✖️\n    * - Dynaconf_\n      - ✔️\n      - ❓\n      - ✔️\n      - ✔️\n      - ✔️\n      - ✖️\n    * - python-dotenv_\n      - ✖️\n      - ✔️\n      - ✖️\n      - ✖️\n      - ✖️\n      - ✖️\n    * - `Gin Config`_\n      - ❓\n      - ❓\n      - ❓\n      - ❓\n      - ✔️\n      - ✖️\n    * - `Python Decouple`_\n      - ✖️\n      - ✖️\n      - ✔️\n      - ✔️\n      - ✖️\n      - ✖️\n    * - OmegaConf_\n      - ✔️\n      - ✔️\n      - ✔️\n      - ✔️\n      - ✔️\n      - ✖️\n    * - Confuse_\n      - ✔️\n      - ✔️\n      - ❓\n      - ✔️\n      - ✔️\n      - ✖️\n    * - Everett_\n      - ✔️\n      - ✔️\n      - ✔️\n      - ❓\n      - ✔️\n      - ✖️\n    * - parse_it_\n      - ✔️\n      - ✔️\n      - ✔️\n      - ✔️\n      - ❓\n      - ✖️\n    * - Grift_\n      - ✖️\n      - ✖️\n      - ✖️\n      - ❓\n      - ✔️\n      - ✖️\n    * - profig_\n      - ✖️\n      - ✔️\n      - ✖️\n      - ❓\n      - ✔️\n      - ✖️\n    * - tweak_\n      - ✔️\n      - ✖️\n      - ✖️\n      - ✔️\n      - ✖️\n      - ✖️\n    * - Bison_\n      - ✔️\n      - ❓\n      - ✔️\n      - ✔️\n      - ✔️\n      - ✖️\n    * - Config-Man_\n      - ✖️\n      - ✔️\n      - ✔️\n      - ❓\n      - ✔️\n      - ✖️\n    * - figga_\n      - ✔️\n      - ✖️\n      - ✔️\n      - ❓\n      - ✖️\n      - ✖️\n    * - **Onacol**\n      - ✔️\n      - ✔️\n      - ✔️\n      - ✔️\n      - ✔️\n      - ✔️\n\nInstallation\n------------\n\nAs usually with pip::\n\n    $ pip install onacol\n\nUsage\n-----\n\nDefault configuration file & schema\n+++++++++++++++++++++++++++++++++++\n\nThe whole point of this library is the definition of both default configuration\nand configuration schema in one YAML file (i.e. single source of configuration\ntruth).\n\nLet\'s start with a simple ``default_config.yaml`` file that is part of an example\napplication\'s package. This example file contains default values for the\nconfiguration.\n\n.. code-block:: yaml\n\n    general:\n        # Logging level for this application.\n        log_level: INFO\n\n    ui:\n        # Address and port of the UI webserver\n        addr: 0.0.0.0\n        port: 8888\n\n    sensors:\n        sensor_reset_interval: 30.0  # Sensor reset interval in seconds\n        connected_units:\n            - id: 0                     # Sensor ID <0, 16>\n              name: "Basic sensor"\n              min_trigger_limit: 30     # Minimal triggering limit [cm]\n              max_trigger_limit: 120    # Maximal triggering limit [cm]\n            - id: 1\n              name: "Additional sensor"\n              min_trigger_limit: 40\n              max_trigger_limit: 100\n\nThis file can be used as it is. However, we can add a schema definition to the\nstructure, that will allow parameter validation and automatic type conversion.\n\nThis is done by adding metadata to the YAML structure. Following metadata are\nrecognized by Onacol:\n\n* ``oc_schema``: Cerberus_ validator/schema definitions.\n* ``oc_default``: Default value (if metadata are attached to the YAML element, it\n  can no longer bear the value directly).\n* ``oc_schema_id``: Definition of a schema reference (see\n  `Repeating schema elements`_)\n\nSchema metadata are NOT MANDATORY. We can only provide them to parameters for\nwhich we think validation (or type conversion) may be useful.\n\n.. code-block:: yaml\n\n    general:\n        # Logging level for this application.\n        log_level: INFO\n\n    ui:\n        # Address and port of the UI webserver\n        addr:\n            oc_default: 0.0.0.0\n            oc_schema:\n                type: string\n                regex: "^(?:[0-9]{1,3}\\\\.){3}[0-9]{1,3}$"\n\n        port:\n            oc_default: 8888\n            oc_schema:\n                type: integer\n\n    sensors:\n        sensor_reset_interval:          # Sensor reset interval in seconds\n            oc_default: 30.0\n            oc_schema:\n                type: float\n                min: 0.0\n                max: 100.0\n        connected_units:\n            - id:                       # Sensor ID <0, 16>\n                oc_default: 0\n                oc_schema:\n                    type: integer\n                    min: 0\n                    max: 16\n              name: "Basic sensor"\n              min_trigger_limit:        # Minimal triggering limit [cm]\n                oc_default: 30\n                oc_schema:\n                    type: integer\n                    min: 0\n                    max: 200\n              max_trigger_limit:        # Maximal triggering limit [cm]\n                oc_default: 120\n                oc_schema:\n                    type: integer\n                    min: 0\n                    max: 200\n            - id: 1\n              name: "Additional sensor"\n              min_trigger_limit: 40\n              max_trigger_limit: 100\n\nNote that for list definitions, schema is added only to the first element of the\nlist. Other elements will be validated based on the first element\'s schema.\n\n\nLoading and validating configuration in an application\n++++++++++++++++++++++++++++++++++++++++++++++++++++++\n\nOnacol is used by the application via the ``ConfigManager`` instance.\n``ConfigManager`` can load configurations from multiple sources (files,\ncommand line optional arguments, environment variables), but does not do it\nautomatically - the sources and order is up to the app implementation.\n\nA complete minimalistic example of an application (using Click_ as a CLI\nframework):\n\n.. code-block:: python\n\n    """Console script for onacol_test."""\n    import sys\n    import click\n    import pkg_resources\n\n    from onacol import ConfigManager\n\n    # Localizing the defaults/schema configuration YAML in the package\n    DEFAULT_CONFIG_FILE = pkg_resources.resource_filename("onacol_test",\n                                                          "default_config.yaml")\n\n    # This must be here in order to retrieve args and options\n    # that are not Click related (see https://stackoverflow.com/a/32946412)\n    @click.command(context_settings=dict(\n        ignore_unknown_options=True,\n        allow_extra_args=True\n    ))\n    @click.pass_context\n    # The rest is the usual Click stuff\n    @click.option("--config", type=click.Path(exists=True), default=None,\n                  help="Path to the configuration file.")\n    @click.option("--get-config-template", type=click.File("w"), default=None,\n                  help="Write default configuration template to the file.")\n    def main(ctx, config, get_config_template):\n        # Wrap optional config file into a list\n        user_config_file = [config] if config else []\n\n        # Instantiate config_manager\n        config_manager = ConfigManager(DEFAULT_CONFIG_FILE,\n                                       env_var_prefix="OCTEST",\n                                       optional_files=user_config_file\n                                       )\n\n        # Generate configuration for the --get-config-template option\n        # Then finish the application\n        if get_config_template:\n            config_manager.generate_config_example(get_config_template)\n            return\n\n        # Load (implicit) environment variables\n        config_manager.config_from_env_vars()\n\n        # Parse all extra command line options\n        config_manager.config_from_cli_args(ctx.args)\n\n        # Validate the config\n        config_manager.validate()\n\n        # Finally, let\'s review interesting bits of the config\n        print("---------<Application configuration>-------------")\n        print(f"Log level: {config_manager.config[\'general\'][\'log_level\']}")\n        print(f"UI: {config_manager.config[\'ui\'][\'addr\']} "\n              f"(port: {config_manager.config[\'ui\'][\'port\']})")\n        print(f"Sensor reset interval: "\n              f"{config_manager.config[\'sensors\'][\'sensor_reset_interval\']}")\n        print(f"Sensors:")\n        for sensor in config_manager.config["sensors"]["connected_units"]:\n            print(f"\\t {sensor[\'name\']} [{sensor[\'id\']}] \\t Trigger limits: "\n                  f"({sensor[\'min_trigger_limit\']}, {sensor[\'max_trigger_limit\']})")\n\n\n    if __name__ == "__main__":\n        sys.exit(main())  # pragma: no cover\n\nIn this example, the application is bundling the ``default_config.yaml`` from\nthe examples above as the default configuration/schema file.\nThen it accepts additional configuration file via command\noption, and on the top it uses the environment variables and additional\nconfiguration via command line options. Configuration from all sources\nare layered/overwritten on the top of the current configuration.\n\nAs you can see in the code, the sources of configuration as well as their\nprioritization depend on the order of which ``ConfigManager`` methods are\ncalled, there is no default and even the validation must be called explicitly.\n\nConfiguration using additional file\n+++++++++++++++++++++++++++++++++++\n\nIn the example app, additional config file are loaded with the ``--config``\noptional command line argument, that is used in the ``ConfigManager``\'s\n``optional_files`` init option. There is also the ``ConfigManager.config_from_file``\nmethod to do this anytime after init.\n\nLet\'s use the following config file (``my_config.yaml``):\n\n.. code-block:: yaml\n\n    general:\n        log_level: DEBUG\n\n    ui:\n        port: 127.0.0.1\n\nAnd load it with the app::\n\n    $ python main.py --config my_config.yaml\n    ---------<Application configuration>-------------\n    Log level: DEBUG\n    UI: 127.0.0.1 (port: 8888)\n    Sensor reset interval: 30.0\n    Sensors:\n             Basic sensor [0]        Trigger limits: (30, 120)\n             Additional sensor [1]   Trigger limits: (40, 100)\n\nAs you can see, the relevant default config parameters have been overwritten,\nthe others stay default. This layering works over configuration dicts of\nunlimited depth, but does not work with lists (by design).\n\nConfiguration using environment variables\n+++++++++++++++++++++++++++++++++++++++++\n\nThere are two ways how to use environment variables with Onacol:\n\n* **Implicit way** - Onacol detects environment variables with defined prefix\n  and use them to overwrite current configuration.\n* **Explicit way** - environment variables are referenced in the configuration\n  files and Onacol resolves the references upon loading the file.\n\nUsing environment variables implicitly\n**************************************\n\nIn the example app source, we defined the ``env_var_prefix`` with value\n``OCTEST``. Using the ``ConfigManager.config_from_env_vars`` method  will then\nmake Onacol parse existing environment variables for names\nstarting with the chosen prefix, and then use the rest of the name as path for\nthe configuration structure (using uppercase and ``__`` as the level separator).\n\nLet\'s continue with the previous example::\n\n    $ export OCTEST_SENSORS__SENSOR_RESET_INTERVAL=20.1\n    $ python main.py --config my_config.yaml\n    Log level: DEBUG\n    UI: 127.0.0.1 (port: 8888)\n    Sensor reset interval: 20.1\n    Sensors:\n             Basic sensor[0] Trigger limits: (30, 120)\n             Additional sensor[1] Trigger limits: (40, 100)\n\nAgain, environment variable overwrites the original value. Environment variable\nvalues are always strings. However, as we defined schema and type for the\nconfiguration parameter ``sensor_reset_interval``, it was automatically\nconverted to integer. Although schema is not mandatory, it\'s always useful for\nparameters that can be configured via environment variables.\n\nWhen schema is not defined, Onacol tries to apply JSON conversion rules to\nthe value of the environment variable. That helps in most cases, but can\ncause problems if you pass value such as "1.2". In that case, it will be\nautomatically converted to float. If you want to receive it as string, you\nmust define schema for that particular config.\n\nIt is also possible to overwrite entire lists with environment variables.\nTo do that, use again JSON as format::\n\n    $ export OCTEST_SENSORS__CONNECTED_UNITS=\'[{"id": 2, "name": "JSON sensor", "min_trigger_limit": 10, "max_trigger_limit": 90}]\'\n    $ python main.py --config my_config.yaml\n    ---------<Application configuration>-------------\n    Log level: DEBUG\n    UI: 127.0.0.1 (port: 8888)\n    Sensor reset interval: 30.0\n    Sensors:\n             JSON sensor [2]         Trigger limits: (10, 90)\n\nAs explained above, lists are always overwritten completely, no layering.\nIt is not possible to use JSON to overwrite dicts in the configuration\nstructure.\n\nUsing environment variables explicitly\n**************************************\n\nEnvironment variables can be also explicitly referred in the configuration YAML\nfile with syntax ``${oc_env:ENV_VAR}``:\n\n.. code-block:: yaml\n\n    general:\n        log_level: DEBUG\n\n    ui:\n        addr: ${oc_env:MY_ADDR}\n\nThis reference is being resolved before the YAML is parsed (it\'s a primitive\nregex substitution). Therefore the YAML type conversion is used for non-string\nvalues. Explicit environment variable references can be only used in file-type\nconfiguration sources. Example::\n\n    $ export MY_ADDR=192.168.1.10\n    $ python main.py --config my_config.yaml\n    ---------<Application configuration>-------------\n    Log level: DEBUG\n    UI: 192.168.1.10 (port: 8888)\n    Sensor reset interval: 30.0\n    Sensors:\n             Basic sensor [0]        Trigger limits: (30, 120)\n             Additional sensor [1]   Trigger limits: (40, 100)\n\nIn explicitly used environment variables, where schema is not defined, then\nof course YAML default conversion rules are used.\n\nConfiguration using command-line options\n++++++++++++++++++++++++++++++++++++++++\n\nCommand-line optional arguments can be also parsed by Onacol to retrieve\nconfiguration parameters. The logic is very similar to the implicit usage of\nenvironment variables, but no prefix is used and the level separator is ``--``::\n\n    $ python main.py --config my_config.yaml --ui--port 8080  --sensors--sensor-reset-interval 15.8\n    ---------<Application configuration>-------------\n    Log level: DEBUG\n    UI: 127.0.0.1 (port: 8080)\n    Sensor reset interval: 15.8\n    Sensors:\n             Basic sensor [0]        Trigger limits: (30, 120)\n             Additional sensor [1]   Trigger limits: (40, 100)\n\nAs with implicit environment variable, config parameters with defined schema get\nautomatically converted to their types. It\'s also allowed to use JSON lists.\n\nGeneration of an example/template config file\n+++++++++++++++++++++++++++++++++++++++++++++\n\nDefault configuration/schema can be used to generate an example (template)\nconfig file with ``ConfigManager.generate_config_example`` method. This file\nhas the schema information stripped, but retains the comments  used in the\ndefaults YAML file.\n\nThe example app has the `--get-config-template` option to demonstrate it::\n\n    $ python main.py --get-config-template config_template.yaml\n\nwill generate following `config_template.yaml` file:\n\n.. code-block:: yaml\n\n    general:\n        # Logging level for this application.\n      log_level: INFO\n\n    ui:\n        # Address and port of the UI webserver\n      addr: 0.0.0.0\n      port: 8888\n    sensors:\n      sensor_reset_interval: 30.0       # Sensor reset interval in seconds\n      connected_units:\n      - id: 0                           # Sensor ID <0, 16>\n        name: Basic sensor\n        min_trigger_limit: 30           # Minimal triggering limit [cm]\n        max_trigger_limit: 120          # Maximal triggering limit [cm]\n      - id: 1\n        name: Additional sensor\n        min_trigger_limit: 40\n        max_trigger_limit: 100\n\nThe comments are retained by the magic of `Ruamel YAML`_, and there are some\nlimits. For proper retaining of comments, try to put the comments at the end\nof line and avoid above-line comments where the preceding element is a schema\nelement.\n\nExporting current configuration to a config file\n++++++++++++++++++++++++++++++++++++++++++++++++\n\nThe current state of the configuration can be dumped to a file using\nthe ``ConfigManager.export_current_config`` method.\n\nRepeating schema elements\n+++++++++++++++++++++++++\n\nIn case the configuration schema has repeating elements, it\'s possible to define\nschema for just one element, declare a reference for it with ``oc_schema_id``\nand then refer other elements to that schema definition directly with\n``oc_schema``:\n\n.. code-block:: yaml\n\n    network_interfaces:\n        ethernet_interface:\n            name:       # Element name\n                oc_default: "eth0"\n                oc_schema:\n                    type: string\n            id:\n                oc_default: 0\n                oc_schema:\n                    type: integer\n            ip_addr:\n                oc_default:  192.168.1.2\n                oc_schema:\n                    type: string\n                    regex: "^(?:[0-9]{1,3}\\\\.){3}[0-9]{1,3}$"\n\n            # Here we declare re-usable schema\n            oc_schema_id: network_interface_item\n        wifi_interface:\n            name: wifi\n            id: 1\n            ip_addr: 192.168.2.3\n            oc_schema: network_interface_item    # Here we reference the previously declared schema:\n\nConfiguration layering\n++++++++++++++++++++++\n\nWhen default or current configuration gets overwritten with new config values,\nthe previous values are kept internally and can be accessed. This is done using\nthe cascading features of CascaDict_ (the configuration structure is kept in\n``ConfigManager.config`` as ``CascaDict`` instance).\n\nIf you are not interested in this, just use it as if it was a regular ``dict``.\n\nOther notes\n+++++++++++\n\n* For any sort of configuration with variable amount of elements, use lists,\n  not dicts. Onacol is written on assumption that the configuration tree\n  consists of more-or-less fixed dicts and variable length lists.\n* To create a default config/schema that shall enforce the end user to overwrite\n  some parameters, use ``null`` as the default value and use schema with\n  ``nullable: false`` - see `Cerberos docs <https://docs.python-cerberus.org/en/stable/validation-rules.html#nullable>`_.\n  Validation will then report error when this value is not overwritten.\n\nLicense\n-------\nFree software: MIT license\n\nDocumentation\n-------------\n\nFull docs at https://onacol.readthedocs.io.\n\n.. _Cookiecutter: https://github.com/audreyr/cookiecutter\n.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage\n.. _Cerberus: https://docs.python-cerberus.org/en/stable/\n.. _Hydra: https://hydra.cc/\n.. _Config-Man: https://github.com/mmohaveri/config-man\n.. _Dynaconf: https://github.com/rochacbruno/dynaconf\n.. _Pydantic: https://pydantic-docs.helpmanual.io/\n.. _python-dotenv: https://github.com/theskumar/python-dotenv\n.. _`Gin Config`: https://github.com/google/gin-config\n.. _OmegaConf: https://github.com/omry/omegaconf\n.. _Confuse: https://github.com/beetbox/confuse\n.. _`Python Decouple`: https://github.com/henriquebastos/python-decouple\n.. _parse_it: https://github.com/naorlivne/parse_it\n.. _grift: https://github.com/kensho-technologies/grift\n.. _profig: https://github.com/dhagrow/profig\n.. _tweak: https://github.com/kislyuk/tweak\n.. _Bison: https://github.com/edaniszewski/bison\n.. _figga: https://github.com/berislavlopac/figga\n.. _Click: https://click.palletsprojects.com\n.. _CascaDict: https://github.com/JNevrly/cascadict\n.. _`Ruamel YAML`: https://yaml.readthedocs.io/en/latest/\n.. _Everett: https://github.com/willkg/everett\n',
    'author': 'Josef Nevrly',
    'author_email': None,
    'maintainer': None,
    'maintainer_email': None,
    'url': None,
    'packages': packages,
    'package_data': package_data,
    'install_requires': install_requires,
    'python_requires': '>=3.6,<4.0',
}


setup(**setup_kwargs)
