Metadata-Version: 1.1
Name: tweak
Version: 1.0.0
Summary: Application configuration engine
Home-page: https://github.com/kislyuk/tweak
Author: Andrey Kislyuk
Author-email: kislyuk@gmail.com
License: Apache Software License
Description: tweak: Application configuration engine
        =======================================
        Tweak is a Python helper class to ingest and serialize app-specific configuration.
        
        Tweak provides a self-contained (no dependencies outside the standard library), Python 2 and 3 compatible configuration
        manager. It automatically saves and restores your application's configuration in your user home directory. It uses JSON or
        (optionally) YAML for serialization. It supports dict-like methods and access semantics, hierarchical configuration sources,
        and array merge operators for layering configuration options (see below).
        
        Installation
        ------------
        If your package does not permit dependency management, you can copy the ``Config`` class directly into your
        application from https://github.com/kislyuk/tweak/blob/master/tweak/__init__.py. Otherwise:
        
        ::
        
            pip install tweak
        
        Synopsis
        --------
        
        .. code-block:: python
        
            from tweak import Config
        
            config = Config()
            config.host, config.port = "example.com", 9000
            config.nested_config = {}
            config.nested_config.foo = True
        
        After restarting your application::
        
            config = Config()
            print(config)
            >>> {'host': 'example.com', 'port': 9000, 'nested_config': {'foo': True}}
        
        Using an ``argparse.Namespace`` object returned by ``argparse.parse_args()``::
        
            parser = argparse.ArgumentParser()
            ...
            args = parser.parse_args()
            if args.foo is not None:
                config.foo = args.foo
            elif "foo" not in config:
                raise Exception("foo unconfigured")
        
            config.update(vars(args))
        
        Using YAML::
        
            config = Config(use_yaml=True)
            ...
        
        Pass ``Config(save_on_exit=False)`` to disable automatic configuration saving on Python shutdown (this is useful if you
        only want to read the config, never write it, or if you want to call ``config.save()`` manually). Pass
        ``Config(autosave=True)`` to make ``save()`` run any time an assignment happens to a config object.
        
        Configuration ingestion order
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        Tweak supports ingesting configuration from a configurable array of sources. Each source is a JSON or YAML file.
        Configuration sources that follow the first source update the configuration using recursive dictionary merging. Sources are
        enumerated in the following order:
        
        - Site-wide configuration source, ``/etc/NAME/config.(yml|json)``
        - User configuration source, ``~/.config/NAME/config.(yml|json)``
        - Any sources listed in the colon-delimited variable ``NAME_CONFIG_FILE``
        
        Array merge operators
        ~~~~~~~~~~~~~~~~~~~~~
        
        When loading a chain of configuration sources, Tweak uses recursive dictionary merging to combine the
        sources. Additionally, when the original config value is a list, Tweak supports array manipulation operators::
        
            In [1]: from tweak import Config
        
            In [2]: c = Config()
        
            In [3]: c.update(x=[1, 2, 3])
        
            In [4]: c
            Out[4]: {'x': [1, 2, 3]}
        
            In [5]: c.update(x={"$append": 4})
        
            In [6]: c
            Out[6]: {'x': [1, 2, 3, 4]}
        
            In [7]: c.update(x={"$extend": [5, 6]})
        
            In [8]: c
            Out[8]: {'x': [1, 2, 3, 4, 5, 6]}
        
            In [9]: c.update(x={"$insert": {0: 0}})
        
            In [10]: c
            Out[10]: {'x': [0, 1, 2, 3, 4, 5, 6]}
        
            In [11]: c.update(x={"$extendleft": [-2, -1]})
        
            In [12]: c
            Out[12]: {'x': [-2, -1, 0, 1, 2, 3, 4, 5, 6]}
        
            In [13]: c.update(x={"$remove": 0})
        
            In [14]: c
            Out[14]: {'x': [-2, -1, 1, 2, 3, 4, 5, 6]}
        
        Each operator (``$append``, ``$extend``, ``$insert``, ``$extendleft``, ``$remove``) must be the only key in the
        dictionary representing the update, and the value being updated must be a list. For example, in the following set of two
        YAML files, the second file extends the list in the first file.
        
        ``/etc/NAME/config.yml``::
        
            x:
             - y
             - z
        
        ``~/.config/NAME/config.yml``::
        
            x:
             $extend:
               - a
               - b
        
        Include directives
        ~~~~~~~~~~~~~~~~~~
        
        The optional ``Config(allow_includes=True)`` keyword argument can be used to trigger processing of include directives in
        config files. For each config source file ingested, a top level ``include`` key can contain a string or array of
        strings. Each of these strings will be globbed and ingested before the file contianing the directive (e.g. ``{"include":
        "config.d/*"}`` to ingest a directory of config files).
        
        Authors
        -------
        * Andrey Kislyuk
        
        Links
        -----
        * `Project home page (GitHub) <https://github.com/kislyuk/tweak>`_
        * `Documentation (Read the Docs) <https://tweak.readthedocs.io/en/latest/>`_
        * `Package distribution (PyPI) <https://pypi.python.org/pypi/tweak>`_
        
        Bugs
        ~~~~
        Please report bugs, issues, feature requests, etc. on `GitHub <https://github.com/kislyuk/tweak/issues>`_.
        
        License
        -------
        Licensed under the terms of the `Apache License, Version 2.0 <http://www.apache.org/licenses/LICENSE-2.0>`_.
        
        .. image:: https://travis-ci.org/kislyuk/tweak.png
                :target: https://travis-ci.org/kislyuk/tweak
        .. image:: https://img.shields.io/coveralls/kislyuk/tweak.svg
                :target: https://coveralls.io/r/kislyuk/tweak?branch=master
        .. image:: https://img.shields.io/pypi/v/tweak.svg
                :target: https://pypi.python.org/pypi/tweak
        .. image:: https://img.shields.io/pypi/l/tweak.svg
                :target: https://pypi.python.org/pypi/tweak
        .. image:: https://readthedocs.org/projects/tweak/badge/?version=latest
                :target: https://tweak.readthedocs.io/
        
Platform: MacOS X
Platform: Posix
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Development Status :: 5 - Production/Stable
Classifier: Topic :: Software Development :: Libraries :: Python Modules
