Skip to main content

manage user configuration for python packages

Project description


Manage user configuration for python projects.

For easy and well-documented user-defined configuration.


  • Documentation Status

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:

Config format

Supported out of the box: ini

Other config formats can be supported via plug-ins.


  • 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)


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",
    general = GeneralSection()
    class AddressSection(Section):
        """shipping address"""
        street = StringOption(
            doc="street including house number",
        city = StringOption(required=True)
    address = AddressSection(required=False)

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

Command line help text:

$ python examples/ -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/ --age 211
hello there, unknown person!

Command line use without required value:

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

Command line use:

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

Generate configuration file:

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

## General information.

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

## your age
# age =
age =

## shipping address

## street including house number
# street =
street =

# city =
city =


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


  • 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.

Source Distribution

user_config-1.0a10.tar.gz (17.9 kB view hashes)

Uploaded Source

Built Distribution

user_config-1.0a10-py2.py3-none-any.whl (13.8 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page