Metadata-Version: 2.1
Name: configoat
Version: 0.1.6
Summary: confiGOAT is a powerful, flexible, and developer-friendly configuration management tool.
Home-page: https://github.com/aag13/configoat
Author: Hasan-UL-Banna, Asadullah Al Galib
Author-email: hasanulbanna04056@gmail.com, asadullahgalib13@gmail.com
License: MIT license
Description: <h1 align="center"> confiGOAT </h1>
        
        confiGOAT is a powerful, flexible, and developer-friendly management tool for all your 
        environment variables and configurations. 🔥🔥🔥
        
        ## Features
        Here are some of the features that confiGOAT provides:
        
        - Manage all environment variables or configuration parameters from a single setup.
        - Support all development, testing, and production environments.
        - Define configurations once, use it everywhere.
        - Define configuration parameters using both YAML and Python scripts.
        - Cast values before using them.
        - Powerful reference mechanism to reuse variables *from any levels at any levels in any direction*.
        - Multiple resource types in the YAML to support the vast majority of use cases.
        - Support both simple use cases and complex, multi-layered nested configurations.
        - Use dynamic modules to access the parameters through import interface in Python.
        - Use a single exposed API to interact with the layered configurations.
        - Support nested structures to model the configurations as per business needs.
        
        🎉🚀🌟
        
        ## Installation
        
        confiGOAT can be installed with [pip](https://pip.pypa.io):
        
        ```bash
        pip install configoat
        ```
        
        Alternatively, you can grab the latest source code from [GitHub](https://github.com/aag13/configoat):
        
        ```bash
        git clone https://github.com/aag13/configoat
        cd configoat
        pip install .
        ```
        
        ## How to Use
        
        ### Initial Setup
        confiGOAT provides a user-friendly CLI command to initialize the configuration setup
        for your project. 
        
        1. Go to the root directory of your project and run the following command 
        in the terminal.
        
            ```bash
            configoat init
            ```
        
        2. For the directory name, enter the name of the folder that will contain all
        the configuration files and scripts. E.g. *"environments/"* will create a directory
        inside the root directory of your project. Default is *"configs/"*.
        3. For the main configuration file, provide a name that confiGOAT will look
        for when initializing the setup for your project. (we will see how to do that
        later). Default is *"main.yaml"*.
        4. While selecting the type of configurations, you have 3 options. Choose the one that
        best suits your specific project needs. 👇
           - **Single (Only one YAML file)** : Use this for small projects where all your configurations will fit 
           in one single YAML file.
           - **Nested (Parent-child YAML files)** : Use this for projects where it makes sense to structure the 
           configuration files in a nested hierarchy.
           - **Nested with Scripts (Includes .py scripts)** : Use this for large-scale projects where some  
           configurations need to be resolved using python scripts on top of a multi-layered hierarchy.
        
        For example, if you can fit all your configuration variables in a single file, choose option 1. Choose option 
        2 if you want to structure all the configuration parameters in separate files based on their types, such as, 
        security configurations in *security.yaml* file and database configurations in *database.yaml* file. Option 3 
        is best suited for cases where you need both the nested hierarchy structure and need to resolve values 
        for some parameters that require executing some code.
        
        ❄️❄️❄️
        
        ### Preparing Configuration Files
        Now that you have set up the configuration folder and starting file(s), you need to populate all your 
        configuration and environment variables in the generated YAML and python script files.
        1. First, open the *main.yaml* (or whatever name you gave during the initial setup) file.
        2. Each YAML file has 2 root properties, namely *doc* and *resources*. 👇
           - You can use *doc* to provide basic description on the type of environment or configuration variables 
           which are defined in this YAML. 
           - *resources* contains all the configuration variables that are defined in this file. If you want to 
           create a new variable, you need to define it inside *resources*. 
           ```yaml
           doc: 'This is the main config file where the processing starts from'
           resources:
           ...
           ```
        3. You can define 4 different types of resources in confiGOAT. 👇
           - *normal* : Use this type if the value of the variable will be different for different environments. You can
           use different data types for different environments, such as string, integer, float, boolean, list, and dictionary.
           ```yaml
           var1:
             type: 'normal'
             value:
               dev: 'value of var1 for dev'
               stage: 'value of var1 for stage'
               uat: 'value of var1 for uat'
               production: 'value of var1 for production'
               qa: 'value of var1 for qa'
           ```
           - *common* : Use this type if the value of the variable will be same across all environments. We support
           the following data types - string, integer, float, boolean, list, and dictionary.
           ```yaml
           var2:
             type: 'common'
             value: "value of var2"
           
           var3:
             type: 'common'
             value: False
           
           var4:
             type: 'common'
             value: 100
           
           var5:
             type: 'common'
             value: [ "Banana", "Mango", "Apple" ]
           
           var6:
             type: 'common'
             value: {
               "name": "Raihan The Boss",
               "age": 66,
               "address": {
                 "city": "Dhaka",
                 "country": "Bangladesh",
               }
             }
           ```
           - *nested* : Use this type for a nested YAML file (Available if you chose option 2 or 3 during setup). *path* 
           is the relative path from the project root folder to that nested YAML file, e.g. *configs/yamls/nested.yaml*. 
           All the variables which are defined in the specified nested YAML file will be available under the 
           namespace of the *var7* variable. ✨
           ```yaml
           var7:
             type: 'nested'
             path: 'path/from/project/root/to/nested.yaml'
           ```
           - *script* : Use this type for a python script file (Available if you chose option 3 during setup). *path* 
           is the relative path from the project root folder to that nested script file, e.g. *configs/scripts/script.py*. 
           Only the variables which are defined in the *variable_list* property will be available from specified 
           nested script file under the namespace of the *var9* variable. ✨
           ```yaml
           var9:
             type: 'script'
             variable_list: ['a', 'b', 'c', 'd', 'e']
             path: 'path/from/project/root/to/script.py'
           ```
        4. For the *nested* type, confiGOAT will process the specified YAML file **recursively**, so that if 
           the nested YAML file contains other *nested* variables, it will resolve all those nested YAML files 
           recursively as well. 👀
        5. If you want to reuse the value from another variable using reference, either in the same file or any file 
        in the configuration hierarchy, you need to use **$ref(variable_name)** format by replacing the 
        variable_name with the actual variable in your configuration that you want to refer to. 👇
        6. Let's consider a couple of scenarios to demonstrate how variable referencing works. 🌅
           - First, you need to understand the difference between the *source* and *target* variables. Here, 
           *source* variable is the one whose reference is being used and *target* variable is the one that is 
           using the reference. 🎁🎁
           - ***Target* variable in the main config YAML file** : If the *target* variable is in the main config file, 
           such as *main.yaml*, then you can accomplish that in two ways depending on where the *source* 
           variable is.
             - **Source variable in the main config file** : If the *source* variable is in the main config 
             file, then use *$ref(SIBLING)* in the *target variable*. This will get the value from a variable 
             called *SIBLING* to the *target* variable like this. ✨
             ```yaml
             target_var:
               type: 'common'
               value: "$ref(SIBLING)"
             ```
             - **Source variable in a nested file** : If there is a *nested* variable called *nested1* and inside 
             the YAML of this file, there exists a variable called *varAA*, then the full *dot notation path* to this variable 
             from the main config file is *nested1.varAA*. So use *$ref(nested1.varAA)* in the *target variable*. ✨
             ```yaml
             target_var:
               type: 'common'
               value: "$ref(nested1.varAA)"
             ```
           - ***Target* variable in any other YAML/script file** : If the *target* variable is in any file other than 
           the main config file, then you can accomplish that in two ways depending on where the *source* variable is.
             - **Source variable in the same file** : If the *source* variable is in the same file as the  
             *target variable*, then use *$ref(SIBLING)* in the *target variable*. This will get the value from a variable 
             called *SIBLING* to the *target* variable like this. ✨
             ```yaml
             target_var:
               type: 'common'
               value: "$ref(SIBLING)"
             ```
             - **Source variable in any other file** : If there is a *nested* variable called *nested1* in the 
             main config file and inside the YAML of this *nested* variable, there exists a variable called 
             *varAA*, then the full *dot notation path* to this variable is *@.nested1.varAA*. 
             So use *$ref(@.nested1.varAA)* in the *target variable*. ✨
             ```yaml
             target_var:
               type: 'common'
               value: "$ref(@.nested1.varAA)"
             ```
           - **So, when to use *@* in the reference**: If the *target* variable is in the root config file, then you don't need 
           to add *@* in the full *dot notation path*. Because you can use the dotted path to follow the nested 
           variable hierarchy since you are already in the root config file. However, if the *target* variable 
           is in anywhere other than the root config file, then you need to prepend the *dot notation path* 
           with *@* to indicate whether to start looking for the *nested* variable from the root file or the 
           current file. Starting the dotted path with *@* simply means to *start looking for this variable 
           from the root config file*. 🎂🎂
        
        NOTE: Referencing a variable is bidirectional and depth agnostic, meaning that any variable can be referenced 
        **at any depth from any depth in any direction**, as long as no circular dependency is created during the 
        referencing of another variable. *Circular Dependency* means that definitions of two variables are dependent 
        on each other and neither variable can be resolved due to this dependency. In case of any circular dependency, 
        confiGOAT will raise an exception indicating the circular dependency.
        
        🌟🌟🌟
        
        ### Using Configuration Parameters in the Project
        
        Now that you have prepared the configurations for your project, you need to use them in your project. 
        
        1. First, you need to initialize and load all the configuration and environment variables.
           ```python3
           from configoat import conf
           conf.initialize(config="configs/main.yaml", env="dev", module="all_config")
           ```
           - *config* denotes the path to the main configuration YAML file to start loading the variables from.
           - *env* denotes which environment the variables should be loaded for.
           - *module* denotes the name of the namespace under which all variables will be made available for the 
           dynamic module access.
           - In practice, you don't want to hardcode the environment value like this, *env="dev"*. This way, you 
           won't be able to change it dynamically on the different environments your app is running on. We 
           recommend getting this value from another source that can be resolved during runtime. E.g. if you are 
           using confiGOAT in a Django app, then using CI/CD or starting script, inject the environment value 
           as the command line argument during the project run. Then, before initialization, 
           fetch this value from *os* like below,
           ```python3
           import os
           from configoat import conf
           current_env = os.getenv("YOUR_ENVIRONMENT_VARIABLE")
           conf.initialize(config="configs/main.yaml", env=current_env, module="all_config")
           ```
        2. To access the configuration variables, you have 2 options.
           - *Dot notation* : You can use the *conf* object to access any variable by providing its full 
           *dot notation path* from the root configuration file. *@* denotes the root of the configuration, 
           i.e. the main configuration file. You can also pass the *conf* variable around like any other variable in python
           and access values like shown below.
           ```python3
           print(conf("@.VARIABLE_NAME"))
           print(conf("@.NESTED.VARIABLE_NAME"))
           
           print(conf.get("@.VARIABLE_NAME"))
           print(conf.get("@.NESTED.VARIABLE_NAME"))
           ```
           - *Dynamic module* : Use python's module and import mechanism to access any configuration 
           variable. In this approach, you import the module that you defined during the initialization step,
           e.g. *all_config*. When confiGOAT initialized your configuration variables, it also created dynamic 
           modules and attributes in those modules following your configuration nested hierarchy. All these 
           dynamic modules are inserted under the provided namespace, e.g. the *all_config* module name. After 
           initialization, you can import this module anywhere in your project and access the variables like any other modules 
           and their attributes. Some examples are given below on how variables can be accessed using dynamic module. 
           ```python3
           # accessing variables from the root module name, i.e. all_config
           import all_config
           print(all_config.var3)
           print(all_config.var2.var4)
           
           # importing all variables using * from the root module name, i.e. all_config
           from all_config import *
           print(var3)
           print(var2.var4)
           
           from all_config import var2 as current
           print(current.var4)
           ```
        
        **You can also provide a default value in case the variable is not found and a casting function to transform
        the final value before returning. Casting and default value features are available only when 
        accessing values using *conf()* or *conf.get()***.
        ```python3
        print(conf("@.VARIABLE_NAME", default=10, cast=int))
        
        print(conf.get("@.VARIABLE_NAME", default=10, cast=int))
        ```
        
        
        ## Issues
        
        Please let us know if you find any issue by [filing an issue.](https://github.com/aag13/configoat/issues)
        
        ## Maintainers
        
        - [@banna](https://github.com/Hasan-Ul-Banna) (Hasan-UL-Banna)
        - [@galib](https://github.com/aag13) (Asadullah Al Galib)
        
        👋
        
        
        
        
        
        =======
        History
        =======
        
Keywords: configoat
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django
Classifier: Framework :: Flask
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.5
Description-Content-Type: text/markdown
