Skip to main content

manage user configuration for python packages

Project description

user_config

Manage user configuration for python projects.

For easy and well-documented user-defined configuration.

Badges

  • Documentation Status
  • https://travis-ci.org/nihlaeth/user_config.svg?branch=master
  • https://api.codacy.com/project/badge/Grade/bd13a0474ea44c8e8a95e10ef4d89585
  • https://api.codacy.com/project/badge/Coverage/bd13a0474ea44c8e8a95e10ef4d89585
  • https://img.shields.io/github/tag/nihlaeth/user_config.svg
  • https://img.shields.io/pypi/v/user_config.svg
  • https://img.shields.io/pypi/l/user_config.svg
  • https://img.shields.io/pypi/pyversions/user_config.svg
  • https://img.shields.io/pypi/status/user_config.svg

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

"""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:

$ 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:

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

Command line use without required value:

$ 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:

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

Generate configuration file:

$ 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

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

Testing

  • pytest
  • pytest-cov
  • coverage
  • codacy-coverage
$ 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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
user_config-1.0a10-py2.py3-none-any.whl (13.8 kB) Copy SHA256 hash SHA256 Wheel py2.py3 Apr 5, 2017
user_config-1.0a10.tar.gz (17.9 kB) Copy SHA256 hash SHA256 Source None Apr 5, 2017

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page