Welcome to confattr’s documentation

confattr (config attributes) is a python library which has the primary use case to read and write config files [example] but it can also be used to parse the input from a command line and provide auto completion for it [example for prompt_toolkit/example for urwid]. This library has the following features:

  • Static type checking of the code is possible with e.g. mypy.

  • Values are checked and if the config file contains invalid syntax, unknown keys or invalid values a useful error messages is given to the user via a callback registered with ConfigFile.set_ui_callback().

  • It is possible to create a default config file with comments giving help and allowed values via ConfigFile.save(). [example]

  • It is possible to generate a help via ConfigFile.write_help() and ConfigFile.get_help(). [example]

  • Settings can be changed via environment variables, too. [example]

  • It is possible to use the values of settings and environment variables when assigning a new value to a setting. [example]

  • It is easy to integrate into existing projects, just replace an existing attribute with a Config instance. For example, assume a class has the attribute color = 'red'. Replace it with color = Config('color', 'red', allowed_values=['red', 'green', 'blue']) and call ConfigFile.load() (after the attribute has been created but before it’s value is used). Then a user can create a config file in the expected location() and can change the attribute with set color=green. You don’t need to change the usage of the attribute because Config implements the descriptor protocol.

  • It is easy to add custom commands by subclassing ConfigFileCommand. [example]

  • It is well documented.

  • Includes an example for test automation. [example]

  • Test coverage: 100% branch coverage (tested on Python 3.11.5 and Python 3.6.15)

Introduction and examples

Installation

You can install this library manually with pip

$ pip install confattr

or, if you intend to use it in an installable package, just add it to the dependencies of pyproject.toml

[project]
dependencies = [
    "confattr >= 1.0.1, < 2.0.0",
]

Reference

Indices and tables