Utilities for pandas.
Project description
birch |birch_icon|
##########
|PyPI-Status| |PyPI-Versions| |Build-Status| |Codecov| |LICENCE|
Simple hierarchical configuration for Python packages.
.. |birch_icon| image:: https://github.com/shaypal5/birch/blob/cc5595bbb78f784a3174a07157083f755fc93172/birch.png
:height: 87
:width: 40 px
:scale: 50 %
.. .. image:: https://github.com/shaypal5/birch/blob/b10a19a28cb1fc41d0c596df5bcd8390e7c22ee7/birch.png
.. code-block:: python
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'])
.. contents::
.. section-numbering::
Installation
============
.. code-block:: bash
pip install birch
Features
========
* Supported formats: JSON, YAML.
* Pure python.
* Supports Python 3.4+.
* Fully tested.
Use
===
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:
.. code-block:: python
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 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:
.. code-block:: python
>>> 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'
Hierarchical configuration
--------------------------
``birch`` supports a simple hierarchy between configuration mappings. The ``_`` character 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. It is also **partially** equivalent to the ``{'server_port': 55}`` mapping.
As such, hierarchical mapping can be accessed either using ``_`` to indicate a hierarchical path, or using dict-like item access:
.. code-block:: python
>>> 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, anf not use the ``_`` character within a name in configuration files.
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.
Configuring birch
-----------------
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.
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.
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.
Installing for development
----------------------------
Clone:
.. code-block:: bash
git clone git@github.com:shaypal5/birch.git
Install in development mode, including test dependencies:
.. code-block:: bash
cd birch
pip install -e '.[test]'
Or, if you are using ``pipenv``, use the following command to create a ``pipenv`` Python virtual environment with development dependencies:
.. code-block:: bash
cd birch
pipenv install --dev
Running the tests
-----------------
To run the tests use:
.. code-block:: bash
cd birch
pytest
Or, if you are using ``pipenv``:
.. code-block:: bash
cd birch
pipenv run pytest
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`_.
.. _`numpy docstring conventions`: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
.. _`these conventions`: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
Credits
=======
Created by `Shay Palachy <http://www.shaypalachy.com/>`_ (shay.palachy@gmail.com).
.. |PyPI-Status| image:: https://img.shields.io/pypi/v/birch.svg
:target: https://pypi.python.org/pypi/birch
.. |PyPI-Versions| image:: https://img.shields.io/pypi/pyversions/birch.svg
:target: https://pypi.python.org/pypi/birch
.. |Build-Status| image:: https://travis-ci.org/shaypal5/birch.svg?branch=master
:target: https://travis-ci.org/shaypal5/birch
.. |LICENCE| image:: https://img.shields.io/github/license/shaypal5/birch.svg
:target: https://github.com/shaypal5/birch/blob/master/LICENSE
.. |Codecov| image:: https://codecov.io/github/shaypal5/birch/coverage.svg?branch=master
:target: https://codecov.io/github/shaypal5/birch?branch=master
##########
|PyPI-Status| |PyPI-Versions| |Build-Status| |Codecov| |LICENCE|
Simple hierarchical configuration for Python packages.
.. |birch_icon| image:: https://github.com/shaypal5/birch/blob/cc5595bbb78f784a3174a07157083f755fc93172/birch.png
:height: 87
:width: 40 px
:scale: 50 %
.. .. image:: https://github.com/shaypal5/birch/blob/b10a19a28cb1fc41d0c596df5bcd8390e7c22ee7/birch.png
.. code-block:: python
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'])
.. contents::
.. section-numbering::
Installation
============
.. code-block:: bash
pip install birch
Features
========
* Supported formats: JSON, YAML.
* Pure python.
* Supports Python 3.4+.
* Fully tested.
Use
===
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:
.. code-block:: python
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 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:
.. code-block:: python
>>> 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'
Hierarchical configuration
--------------------------
``birch`` supports a simple hierarchy between configuration mappings. The ``_`` character 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. It is also **partially** equivalent to the ``{'server_port': 55}`` mapping.
As such, hierarchical mapping can be accessed either using ``_`` to indicate a hierarchical path, or using dict-like item access:
.. code-block:: python
>>> 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, anf not use the ``_`` character within a name in configuration files.
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.
Configuring birch
-----------------
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.
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.
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.
Installing for development
----------------------------
Clone:
.. code-block:: bash
git clone git@github.com:shaypal5/birch.git
Install in development mode, including test dependencies:
.. code-block:: bash
cd birch
pip install -e '.[test]'
Or, if you are using ``pipenv``, use the following command to create a ``pipenv`` Python virtual environment with development dependencies:
.. code-block:: bash
cd birch
pipenv install --dev
Running the tests
-----------------
To run the tests use:
.. code-block:: bash
cd birch
pytest
Or, if you are using ``pipenv``:
.. code-block:: bash
cd birch
pipenv run pytest
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`_.
.. _`numpy docstring conventions`: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
.. _`these conventions`: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
Credits
=======
Created by `Shay Palachy <http://www.shaypalachy.com/>`_ (shay.palachy@gmail.com).
.. |PyPI-Status| image:: https://img.shields.io/pypi/v/birch.svg
:target: https://pypi.python.org/pypi/birch
.. |PyPI-Versions| image:: https://img.shields.io/pypi/pyversions/birch.svg
:target: https://pypi.python.org/pypi/birch
.. |Build-Status| image:: https://travis-ci.org/shaypal5/birch.svg?branch=master
:target: https://travis-ci.org/shaypal5/birch
.. |LICENCE| image:: https://img.shields.io/github/license/shaypal5/birch.svg
:target: https://github.com/shaypal5/birch/blob/master/LICENSE
.. |Codecov| image:: https://codecov.io/github/shaypal5/birch/coverage.svg?branch=master
:target: https://codecov.io/github/shaypal5/birch?branch=master
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
birch-0.0.3.tar.gz
(23.7 kB
view hashes)
Built Distribution
birch-0.0.3-py2.py3-none-any.whl
(11.8 kB
view hashes)
Close
Hashes for birch-0.0.3-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ce5c5eb3da60c7444a7e6a3599b598ed8852fcaa269d4d6517ef4993a8497bc7 |
|
MD5 | fd9fdff0565afaf6f5c603143fa9d83f |
|
BLAKE2b-256 | abe2384f32dfa14ca62a031f795aab5392828e96b5c1b7339b180c37c3a15d29 |