user-config

user_config

Manage user configuration for python projects.

For easy and well-documented user-defined configuration.

Links

• home: https://github.com/nihlaeth/user_config
• pypi: https://pypi.python.org/pypi/user-config
• documentation: http://user-config.readthedocs.io/en/latest/

Badges

• .. image:: https://readthedocs.org/projects/user-config/badge/?version=latest :target: http://user-config.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status
• .. image:: https://travis-ci.org/nihlaeth/user_config.svg?branch=master :target: https://travis-ci.org/nihlaeth/user_config
• .. image:: https://api.codacy.com/project/badge/Grade/bd13a0474ea44c8e8a95e10ef4d89585 :target: https://www.codacy.com/app/nihlaeth/user_config?utm_source=github.com&utm_medium=referral&utm_content=nihlaeth/user_config&utm_campaign=Badge_Grade
• .. image:: https://api.codacy.com/project/badge/Coverage/bd13a0474ea44c8e8a95e10ef4d89585 :target: https://www.codacy.com/app/nihlaeth/user_config?utm_source=github.com&utm_medium=referral&utm_content=nihlaeth/user_config&utm_campaign=Badge_Coverage
• .. image:: https://img.shields.io/github/tag/nihlaeth/user_config.svg :target: https://github.com/nihlaeth/user_config/releases
• .. image:: https://img.shields.io/pypi/v/user_config.svg :target: https://pypi.python.org/pypi?:action=display&name=user-config
• .. image:: https://img.shields.io/pypi/l/user_config.svg :target: https://pypi.python.org/pypi?:action=display&name=user-config
• .. image:: https://img.shields.io/pypi/pyversions/user_config.svg :target: https://pypi.python.org/pypi?:action=display&name=user-config
• .. image:: https://img.shields.io/pypi/status/user_config.svg :target: https://pypi.python.org/pypi?:action=display&name=user-config

Fallback order

1. command line arguments
2. user config files in ~/.config/<app>/config.<extension>
3. global config files in /etc/xdg/<app>/config.<extension>
4. default values

For directories on operating systems than linux, see: https://github.com/ActiveState/appdirs

Config format

Supported out of the box: ini

Other config formats can be supported via plug-ins.

Requirements

• Linux, or Os X, or Windows (but not Windows Vista)
• python 2.7 or newer (python 3.6 supported)
• relatively new versions of setuptools and pip (version requirement to follow)

Examples

Simple configuration example

.. code-block:: python

"""Usage example for user_config."""
from user_config import Config, Section, StringOption, IntegerOption

class MyConfig(Config):

    """This will be displayed in the configuration documentation."""

    application = "my_application"
    author = "me"

    class GeneralSection(Section):
        """General information."""
        name = StringOption(
            doc="your name",
            default="unknown person")
        age = IntegerOption(
            doc="your age",
            required=True)
    general = GeneralSection()
    class AddressSection(Section):
        """shipping address"""
        street = StringOption(
            doc="street including house number",
            required=True)
        city = StringOption(required=True)
    address = AddressSection(required=False)

if __name__ == "__main__":
    CONFIG = MyConfig()
    print("hello there, {}!".format(CONFIG.general.name))

Command line help text:

.. code-block:: shell

$ python examples/simple_example.py -h
usage: my_application [-h] [--generate-config] [--city CITY] [--street STREET]
                      [--age AGE] [--name NAME]

This will be displayed in the configuration documentation. Command line
arguments overwrite configuration found in:
/root/.config/my_application/config.cfg /etc/xdg/my_application/config.cfg

optional arguments:
  -h, --help         show this help message and exit
  --generate-config  print a complete configuration file with current settings
  --city CITY
  --street STREET    street including house number
  --age AGE          your age
  --name NAME        your name

Command line use with default value:

.. code-block:: shell

$ python examples/simple_example.py --age 211
hello there, unknown person!

Command line use without required value:

.. code-block:: shell

$ python examples/simple_example.py
Traceback (most recent call last):
  File "examples/simple_example.py", line 29, in <module>
    CONFIG = MyConfig()
  File "/git/user_config/user_config/user_config/__init__.py", line 622, in __init__
    self._elements[element].validate_data(self._data)
  File "/git/user_config/user_config/user_config/__init__.py", line 464, in validate_data
    self._elements[element].validate_data(self._data)
  File "/git/user_config/user_config/user_config/__init__.py", line 380, in validate_data
    self.element_name))
user_config.MissingData: no value was provided for required option age

Command line use:

.. code-block:: shell

$ python examples/simple_example.py --age 211 --name mystery_user
hello there, mystery_user!

Generate configuration file:

.. code-block:: shell

$ python examples/simple_example.py --generate-config
## This will be displayed in the configuration documentation.

[general]
## General information.

## your name
# name = unknown person
name = tamara

## your age
## REQUIRED
# age = 
age = 


[address]
## shipping address
## OPTIONAL_SECTION

## street including house number
## REQUIRED
# street = 
street = 

## REQUIRED
# city = 
city = 

Documentation

.. code-block:: shell

$ pip install -e ".[doc]"
$ python setup.py build_sphinx

Testing

• pytest
• pytest-cov
• coverage
• codacy-coverage

.. code-block:: shell

$ python -m pytest --cov=user_config --cov-report xml

Planned features

• multi matching sections / wildcard sections
• yaml config format
• json config format
• hook for overwriting config from database or other storage function