https://github.com/kislyuk/tweak
Python application configuration engine
https://github.com/kislyuk/tweak
Last synced: 3 months ago
JSON representation
Python application configuration engine
- Host: GitHub
- URL: https://github.com/kislyuk/tweak
- Owner: kislyuk
- License: apache-2.0
- Created: 2015-11-17T03:44:39.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2025-01-03T18:27:37.000Z (5 months ago)
- Last Synced: 2025-03-16T01:45:49.643Z (3 months ago)
- Language: Python
- Size: 65.4 KB
- Stars: 16
- Watchers: 3
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.rst
- Changelog: Changes.rst
- License: LICENSE
Awesome Lists containing this project
README
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) `_
* `Documentation (Read the Docs) `_
* `Package distribution (PyPI) `_
Bugs
~~~~
Please report bugs, issues, feature requests, etc. on `GitHub `_.
License
-------
Licensed under the terms of the `Apache License, Version 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/