Utilities for pandas.
Project description
Simple hierarchical configuration for Python packages.
from birch import Birch
cfg = Birch('mypackage')
# read both the MYPACKAGE_SERVER_HOSTNAME environment variable
# and ~/.mypackage/cfg.json containing {'server': {'port': 55}}
connect(cfg['SERVER__HOSTNAME'], cfg['server']['port'])
1 Installation
pip install birch
2 Features
Supported formats: JSON, YAML.
Pure python.
Supports Python 3.4+.
Fully tested.
3 Use
3.1 Basic use
birch provides a simple way to read simple hierarchical configuration for your Python package or application from both environment variables and configuration files.
birch uses namespaces to manage configuration values. The access to each namespace is done via a Birch object initialized with that namespace. Though written with a specific use case in mind, where a single package uses a single namespace to manage its configuration, any number of namespaces can be used. For example:
from birch import Birch
zubat_cfg = Birch('zubat')
golbat_cfg = Birch('golbat')
Each namespace encompasses all values set by either environment variables starting with <uppercase_namespace>_ or <uppercase_namespace>__, or defined within cfg files (of a supported format) located in the ~/.<namespace> directory.
For example, the zubat namespace encompasses environment variables such as ZUBAT_HOSTNAME and ZUBAT__PORT, and all mappings in the ~/.zubat/cfg.json file (if it exists).
Once defined in such a way, the Birch object can be used to access the values of mappings of both types (with or without the namespace suffix; casing is also ignored). For example:
>>> os.environ['ZUBAT_SERVER_HOST'] = 'www.zubat.com'
>>> os.environ['ZUBAT_SERVER_PORT'] = '87'
>>> from birch import Birch
>>> zubat_cfg = Birch('zubat')
>>>> zubat_cfg['ZUBAT_SERVER_HOST']
'www.zubat.com'
>>> zubat_cfg['SERVER_PORT']
'87'
>>> zubat_cfg['server_port']
'87'
3.2 Hierarchical configuration
birch supports a simple hierarchy between configuration mappings. __ (two underscore characters) is used to signal a hierarchical mapping, so the ZUBAT__SERVER__PORT environment variable is equivalent to {'server': {'port': 55}} mapping given in a ~/.zubat/cfg.json file, for example.
As such, hierarchical mapping can be accessed either using __ to indicate a hierarchical path, or using dict-like item access:
>>> os.environ['ZUBAT__SERVER__HOST'] = 'www.zubat.com'
>>> from birch import Birch
>>> zubat_cfg = Birch('zubat')
>>>> zubat_cfg['SERVER__HOST']
'www.zubat.com'
>>>> zubat_cfg['SERVER']['HOST']
'www.zubat.com'
This is not true for non-hierarchical mappings; so, {'server__port': 55} can only be accessed with zubat_cfg['SERVER__PORT'], and not using zubat_cfg['SERVER']['PORT'].
Also, note that casing is not ignored for levels after the first, so a mapping given by the ZUBAT__SERVER__PORT environment variable cannot be read with zubat_cfg['server']['port'], but only with zubat_cfg['SERVER']['PORT'] or zubat_cfg['server']['PORT'].
As such, a good practice is to only use upper-case strings for mapping access.
3.3 Resolution order
A namespace is always loaded with matching environment variables after all configuration files has been loaded, and corresponding mappings will thus override their file-originating counterparts; e.g. the ZUBAT__SERVER__PORT environment variable will overwrite the value of the mapping {'server': {'port': 55}} given in a ~/.zubat/cfg.json file.
The loading order of different files, while deterministic, is undefined and not part of the API. Thus, cfg files with different file extensions can not be relied upon to provide private-vs-shared configuration functionality.
3.4 Configuring birch
3.4.1 Configuration directories
By default birch looks for files only in the ~/.<namespace> directory. You can set a different set of directories to read by populating the directories constructor parameter with a different directory path, or a list of paths.
3.4.2 File formats
By default, birch will only try to read cfg.json files. To dictate a different set of supported format, populate the supported_formats constructor parameter with the desired formats.
For example, Birch('zubat', supported_formats=['json', 'yaml']) will read both cfg.json and cfg.yaml files, while Birch('golbat', supported_formats='yaml') will ony read cfg.yaml (and cfg.yml) files.
Currently supported formats are:
JSON - Looks for cfg.json files.
YAML - Looks for cfg.yaml and cfg.yml files.
4 Contributing
Package author and current maintainer is Shay Palachy (shay.palachy@gmail.com); You are more than welcome to approach him for help. Contributions are very welcomed.
4.1 Installing for development
Clone:
git clone git@github.com:shaypal5/birch.git
Install in development mode, including test dependencies:
cd birch
pip install -e '.[test]'
4.2 Running the tests
To run the tests use:
cd birch
pytest
4.3 Adding documentation
The project is documented using the numpy docstring conventions, which were chosen as they are perhaps the most widely-spread conventions that are both supported by common tools such as Sphinx and result in human-readable docstrings. When documenting code you add to this project, follow these conventions.
Additionally, if you update this README.rst file, use python setup.py checkdocs to validate it compiles.
5 Credits
Created by Shay Palachy (shay.palachy@gmail.com).
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for birch-0.0.6-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 13006fa60853bf41e89057c369dc081e3b6b059f6dd9c8d5a6c5189a2f6c70be |
|
MD5 | 2b694ab4a11d100efa0b777964a43ac6 |
|
BLAKE2b-256 | 3ddea8558c195b365a63a6dbef59522cb8519479e21206728f866c1ac07ec985 |