Metadata-Version: 1.1
Name: pyconverge
Version: 0.0.18
Summary: Resolve configurations from abstract hierarchies and templates
Home-page: https://github.com/drewboswell/converge
Author: Andrew Boswell
Author-email: drewboswell@gmail.com
License: Apache License 2.0
Description: |GitHub tag| |GitHub release| |PyPI| |Py Versions|
        
        |Build Status| |Coverage Status| |Quality Gate| |Code Smells| |File
        Complexity| |Vulnerabilities| |Technical Dept| |Lines of code|
        
        converge
        ========
        
        *Resolve Data from Abstract Hierarchies and Templates*
        
        Managing configuration is hard. More often than not you have high
        key/values duplication and storage.
        `DRY <https://en.wikipedia.org/wiki/Don't_repeat_yourself>`__ your
        tears, it's time for some hierarchical magic, so you can get back to the
        important stuff.
        
        This is where **converge** comes in. There are a few basic concepts when
        using or extend converge: \* Readers: get data from your backends \*
        Filters: filter data before or after resolution (*example: search &
        replace values, inject data post resolution*) \* Resolvers: convert
        abstract data to resolved data \* Writers: output your data to the
        format and backend you need
        
        Abstract hierarchies of data chewed up and spit out to your liking.
        
        Getting started
        ===============
        
        install pyconverge, this will add the ``converge`` command to your
        classpath using setup.py/PyPi
        
        .. code:: bash
        
            pip install pyconverge
            converge version
            converge --help
        
        Create a converge.yaml.template file in your project working directory,
        modify and move it to converge.yaml
        
        .. code:: bash
        
            # create the converge.yaml.template file
            converge init conf
            # modify your converge parameters
            vim converge.yaml.template
            # activate converge
            mv converge.yaml.template converge.yaml
            # verify the integrity of your configuration file
            converge check
        
        Try it out! You chould have a bunch more options!
        
        .. code:: bash
        
            converge --help
        
        Example: Simple testing
        =======================
        
        create a converge.yaml as described above
        
        .. code:: bash
        
            converge init conf
            mv converge.yaml.template converge.yaml
            converge check
        
        Create a sample repository structure
        
        .. code:: bash
        
            converge init repository target_directory
        
            # you should now have the following structure
            find target_directory/ -type d
            # this is where the application centric data goes
            ./data
            ./data/default
            ./data/default/shared
            ./data/default/app
            # the hierarchy file is situated here
            ./hierarchy
            # target (or host for most) centric data resides here
            ./targets
            ./targets/hosts
            ./targets/mapping
        
        Configuration
        =============
        
        converge.yaml
        -------------
        
        This file is a bit peculiar, it allows you to add programs, options,
        configurations on the fly. Let's try it out before adding the
        converge.yaml:
        
        .. code:: bash
        
            converge --help
            # positional arguments:
            #  {init,check,version}
            #    init                initialize configuration or repository
            #    check               run sanity check on configuration
            #    version             get converge version and build information
        
        Put the following in a converge.yaml:
        
        .. code:: yaml
        
            conf:
                default:
                    logging_level: "INFO"
            programs:
                # user command
                amazingcommand:
                    # arguments expected by the command
                    args:
                        - "argument_one"
                        - "argument_two"
                    # description for the python help
                    description: "application description"
                    modes:
                        amazing_mode_one:
                            - "com.insane.class.path.Class1"
                            - "com.insane.class.path.Class2"
                        amazing_mode_two:
                            - "com.insane.class.path.Class1"
                            - "com.insane.class.path.Class3"
        
        Now you should see a new option:
        
        .. code:: bash
        
            converge --help
            # positional arguments:
            #  {init,check,version,amazingcommand}
            #    init                initialize configuration or repository
            #    check               run sanity check on configuration
            #    version             get converge version and build information
            #    amazingcommand      application description <-- MAGIC STUFF with description!!
        
        And even more so there are sub-options available too:
        
        .. code:: bash
        
            converge amazingcommand --help
            # usage: converge-runner.py amazingcommand [-h]
            #                                         argument_one argument_two
            #                                         {amazing_mode_two,amazing_mode_one}
            #
            # positional arguments:
            #  argument_one
            #  argument_two
            #  {amazing_mode_two,amazing_mode_one}
        
        Classpath Execution Explained
        -----------------------------
        
        Those classpaths you listed under the modes, will be executed expecting
        a method matching the following:
        
        .. code:: python
        
            def run(self, data, conf, **kwargs):
                """
                Args:
                    data (dict): The data object that is passes and returned from all class runs
                    conf (dict): Dictionary of all configurations found in converge.yaml (directories, logging etc)
                    kwargs (object): magical python variable variable variables.
        
                Returns:
                    dict: the data object that will be passed to all following class-runs.
                """
                return data
        
        Example: Configuration for Java property files
        ==============================================
        
        A rough overview
        ================
        
        A general example in diagram form:
        
        .. figure:: docs/converge-diagram.png
           :alt: Converge Overview
        
           Alt text
        
        A Brief History of Pain
        =======================
        
        You may have hit some (or all) of these stages in the pursuit of
        configurability:
        
        *In short: from the file, to the GUI, back to the file you idiot.*
        #wevecomefullcircle \* Externalize configuration from your applications,
        to avoid re-releases due to simple conf tuning \* Realizing that you're
        now managing a million de-centralized files with no similar structure \*
        Create or use a centralized, GUI/DB based configuration management
        system (woohoo! configuration liberation!) \* Realizing that you are
        missing flexibility, automation is complex, added abstraction layers are
        painful.
        
        The better model is to accept any data format, process it and output it
        as you wish.
        
        Files are better because: \* you can use time tested versioning systems
        like git or mercurial to branch, release, rollback, check history \* you
        can automate the modification of files with any tool you want \* doing
        migrations/deployment/modifications on DB values/REST endpoints sucks
        (unnecessarily complex)
        
        .. |GitHub tag| image:: https://img.shields.io/github/tag/drewboswell/converge.svg
           :target: 
        .. |GitHub release| image:: https://img.shields.io/github/release/drewboswell/converge.svg
           :target: 
        .. |PyPI| image:: https://img.shields.io/pypi/v/pyconverge.svg
           :target: https://pypi.python.org/pypi/pyconverge/
        .. |Py Versions| image:: https://img.shields.io/pypi/pyversions/pyconverge.svg
           :target: https://pypi.python.org/pypi/pyconverge/
        .. |Build Status| image:: https://travis-ci.org/drewboswell/converge.svg?branch=master
           :target: https://travis-ci.org/drewboswell/converge
        .. |Coverage Status| image:: https://coveralls.io/repos/github/drewboswell/converge/badge.svg?branch=master
           :target: https://coveralls.io/github/drewboswell/converge?branch=master
        .. |Quality Gate| image:: https://sonarqube.com/api/badges/gate?key=drewboswell_converge
           :target: https://sonarqube.com/dashboard/index/drewboswell_converge
        .. |Code Smells| image:: https://sonarqube.com/api/badges/measure?key=drewboswell_converge&metric=code_smells
           :target: https://sonarqube.com/dashboard/index/drewboswell_converge
        .. |File Complexity| image:: https://sonarqube.com/api/badges/measure?key=drewboswell_converge&metric=file_complexity
           :target: https://sonarqube.com/dashboard/index/drewboswell_converge
        .. |Vulnerabilities| image:: https://sonarqube.com/api/badges/measure?key=drewboswell_converge&metric=vulnerabilities
           :target: https://sonarqube.com/dashboard/index/drewboswell_converge
        .. |Technical Dept| image:: https://sonarqube.com/api/badges/measure?key=drewboswell_converge&metric=sqale_debt_ratio
           :target: https://sonarqube.com/dashboard/index/drewboswell_converge
        .. |Lines of code| image:: https://sonarqube.com/api/badges/measure?key=drewboswell_converge&metric=ncloc
           :target: https://sonarqube.com/dashboard/index/drewboswell_converge
        
Keywords: configuration management development operations system sysadmin config converge
Platform: any
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Operating System :: OS Independent
Classifier: Topic :: Office/Business
