Metadata-Version: 2.1
Name: gns-configurator
Version: 1.1.33
Summary: Manage namespaced configurations for a project
Home-page: https://gitlab.com/genesort/pipeline2/gns-configurator-lib.git
Author: Idan Budin
Author-email: idanb@genesort.com
License: UNKNOWN
Description: # 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/
Platform: UNKNOWN
Description-Content-Type: text/markdown