# 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.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",
    ]

## Reference

- confattr package
  - Submodules
  - Module contents
- confattr.config module
  - `Config`
  - `ConfigId`
  - `DictConfig`
  - `ExplicitConfig`
  - `InstanceSpecificDictMultiConfig`
  - `MultiConfig`
  - `MultiDictConfig`
  - `TimingError`
  - `is_mapping_with_enum_keys()`
- confattr.configfile module
  - `ArgPos`
  - `ArgumentParser`
  - `ConfigFile`
  - `ConfigFileArgparseCommand`
  - `ConfigFileCommand`
  - `ConfigFileWriter`
  - `DEFAULT_COMMAND`
  - `Echo`
  - `FormattedWriter`
  - `Help`
  - `HelpWriter`
  - `Include`
  - `Message`
  - `MultipleParseExceptions`
  - `NotificationLevel`
  - `ParseException`
  - `PathType`
  - `SaveKwargs`
  - `SectionLevel`
  - `Set`
  - `TextIOWriter`
  - `UiNotifier`
  - `UnknownCommand`
- confattr.formatters module
  - `AbstractCollection`
  - `AbstractFormatter`
  - `CopyableAbstractFormatter`
  - `Dict`
  - `Hex`
  - `List`
  - `Primitive`
  - `Set`
  - `format_primitive_value()`
- confattr.quickstart module
  - `ConfigManager`
- confattr.state module
  - `has_any_config_file_been_instantiated`
  - `has_config_file_been_instantiated`
- confattr.subprocess_pipe module
  - `run_and_pipe()`
  - `split_list()`
- confattr.types module
  - `AbstractType`
  - `CaseInsensitiveRegex`
  - `OptionalExistingDirectory`
  - `Regex`
  - `SubprocessCommand`
  - `SubprocessCommandWithAlternatives`
  - `TYPE_CONTEXT`
- confattr.utils module
  - `CallAction`
  - `HelpFormatter`
  - `HelpFormatterWrapper`
  - `SortedEnum`
  - `readable_quote()`

## Indices and tables

- Index

- Module Index

- Search Page

## Links

- Source code

- Bug tracker

- Change log

- PyPI