Configurator library

YAML Configurations manager wrapper for 'everett' and 'pyyaml' packages.

Requirements

• Python 3

Installation

    pip install gns-configurator --extra-index-url https://pypi.fury.io/genesort/

Format and behaviour

configuration file

The configuration file should be in standart YAML format. See: https://en.wikipedia.org/wiki/YAML

Environment variables

The manager default behaviour is to look in the OS process environment before the configuration file. Environment variable will not be overwritten by the configuration file.

Custom tags

The YAML files loader can handle the following custom tags:

• '!join': Concatenating list of strings. For example:

      concatenated: [str1, _str2]
  

  Is equal to:

      concatenated: str1_str2
  

• '!include': Inserts the content of a file to a variable. For example, consider we have such YAML file named 'file.yaml':

     nested_var1: value1
     nested_var2: value2
  

  Then on the following file 'nesting' and 'included' will have the same value:

     nesting:
       nested_var1: value1
       nested_var2: value2
     included: !include file.yaml   
  

Usage

The YAML configuration manager contain 2 different attributes for parsed YAML file:

'pyYAML_dict' parsed dictionary

Python dictionary with the parsed YAML file content, where each namespace/variable is a key. Environment variables that are similiar to keys in the dictionary (namespace of environment variables are coverted to nested dictionaries) will overwrite the values. For Example, consider we have the following file named 'file.yaml':

    var1: val1
    some_namespace:
        var2: val2

Then the output of the following code:

    from configurator.manager import YamlConfigManager
    config_mgr = YamlConfigManager('file.yaml')
    print(config_mgr.pyYAML_dict)

Would be:

    {'var1': 'val1', 'some_namespace': {'var2': 'val2'}}

If we would execute the following command:

    $ export some_namespace_var2="overwritten by env var"

Then the output of the python code above would be:

    {'var1': 'val1', 'some_namespace': {'var2': 'overwritten by env var'}}

'everett' configuration manager

Python everett.manager.ConfigManager object. For details about everett.manager.ConfigManager see: https://everett.readthedocs.io/en/latest/. This attribute is the main feature of this tool, it allows namespaced configuration managing with compatibility to the OS process environment. For example, given 'file.yaml' from the 'overwritten_dict' parsed dictionary example, and the following environment:

    var1=env_var_val
    var2="not some_namespace_var2 value"
    some_namespace_var2="overwritten by env var"

For the following code (notice the mutliple ways to access namepaced variables):

    from configurator.manager import YamlConfigManager
    config_mgr = YamlConfigManager('file.yaml')
    print(config_mgr.everett_manager('var1')) #the environment variable value will be taken
    print(config_mgr.everett_manager('var2')) #notice that 'var2' and 'namespace_var2' are different
    #three different ways to access namespaced variables:
    print(config_mgr.everett_manager('namespace_var2'))
    print(config_mgr.everett_manager.with_namespace('some_namespace')('var2'))
    print(config_mgr.everett_manager.('var2', namespace='some_namespace'))

The output would be:

    'env_var_val'
    'not some_namespace_var2 value'
    'overwritten by env var'
    'overwritten by env var'
    'overwritten by env var'

Contact

Idan Budin idanb@genesort.com

External links:

• YAML files format - https://en.wikipedia.org/wiki/YAML
• Everett library documentation - https://everett.readthedocs.io/en/latest/