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()
andConfigFile.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 attributecolor = 'red'
. Replace it withcolor = Config('color', 'red', allowed_values=['red', 'green', 'blue'])
and callConfigFile.load()
(after the attribute has been created but before it’s value is used). Then a user can create a config file in theexpected location()
and can change the attribute withset color=green
. You don’t need to change the usage of the attribute becauseConfig
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.7)
Introduction and examples
- Introduction and examples
- Config and ConfigFile
- Quickstart
- Using the values of settings or environment variables
- Config file syntax
- Allowed key names
- Different values for different objects
- MultiConfig.reset
- Settings without default value
- Include
- Generating help
- Custom data type for regular expressions
- Custom data type for paths
- Adding new commands to the config file syntax
- Writing custom commands to the config file
- Customizing the config file syntax
- Auto completion with prompt_toolkit
- Auto completion with urwid
- Opening the config file in a text editor
- Config without classes
- Testing your application
- Environment variables
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.4.0, < 2.0.0",
]