confattr.quickstart module

Importing this module defines several settings which are useful in many applications and provides the ConfigManager class. This allows for an easy configuration setup in exchange for flexibility. If you want more flexibility you can either subclass ConfigManager and override specific methods or you do not import this module at all and use ConfigFile and Config directly.

class confattr.quickstart.ConfigManager(appname: str, version: str, doc: str | None, *, changelog_url: str | None = None, show_python_version_in_version: bool = False, show_additional_modules_in_version: list[ModuleType] = [])

Bases: object

Defines two ConfigFile instances with separately configurable notification levels for load() and parse_line(). This object also provides create_argument_parser() to create an argparse.ArgumentParser with commonly needed arguments. Note that all Config instances must be created before instantiating this class.

Parameters:

  • appname – The name of the app, used to initialize ConfigFile and when printing the version number

  • version – The version of the app, used when printing the version number

  • doc – The package doc string, used as description when creating an ArgumentParser

  • changelog_url – The URL to the change log, used when printing the version number

  • show_additional_modules_in_version – A sequence of libraries which should be included when printing the version number

  • show_python_version_in_version – If true: include the Python version number when printing the version number

add_config_help_argument(p: ArgumentParser) → ArgumentParser

Add a --help-config argument to an argparse.ArgumentParser.

This is not part of add_config_related_arguments() so that this argument can be insterted between --help and --version.

Returns:

The same object that has been passed in

Add arguments related to the config file to an argparse.ArgumentParser.

Returns:

The same object that has been passed in

add_version_argument(p: ArgumentParser) → ArgumentParser

Add an argument to print the version and exit to an argparse.ArgumentParser.

Returns:

The same object that has been passed in

create_argument_parser() → ArgumentParser

Create an argparse.ArgumentParser with arguments to display the version, edit the config file and choose a config file by calling create_empty_argument_parser(), add_config_help_argument(), add_version_argument() and add_config_related_arguments().

create_empty_argument_parser() → ArgumentParser

Create an argparse.ArgumentParser with the doc passed to the constructor as description and HelpFormatter as formatter_class but without custom arguments.

edit_config(*, context: Callable[[SubprocessCommand], ContextManager[SubprocessCommand]] | None, update: bool = False) → None

Open the config file in a text editor.

If the config file does not exist it is created first. The text editor can be configured with editor.

Parameters:

  • context – Returns a context manager which can be used to stop and start an urwid screen. It takes the command to be executed as argument so that it can log the command and it returns the command to be executed so that it can modify the command, e.g. processing and intercepting some environment variables.

  • update – Load and rewrite the config file if it is already existing.

edit_config_and_exit() → None

edit the config file and exit

editor

A setting allowing the user to specify how to open text files, e.g. the config file

get_save_path() → str
Returns:

The first existing and writable file returned by iter_config_paths() or the first path if none of the files are existing and writable.

load() → bool

Load settings from config file and environment variables.

Returns:

true if no errors have occurred, false if one or more errors have occurred

notification_level_config

A setting allowing the user to specify which messages they want to see when loading a config file with load()

notification_level_ui

A setting allowing the user to specify which messages they want to see when parsing a line with parse_line()

parse_line(ln: str) → bool

Parse a line from the user interface.

Returns:

true if no errors have occurred, false if one or more errors have occurred

print_config_help() → None
print_config_help_and_exit() → None

show the config help and exit

print_errors_without_ui() → None

Call set_ui_callback() with print() so that all messages are printed to the terminal.

print_version() → None
print_version_and_exit() → None

show the version and exit

save(if_not_existing: bool = False) → str

Save the current values of all settings to the file returned by get_save_path(). Directories are created as necessary.

Parameters:

if_not_existing – Do not overwrite the file if it is already existing.

Returns:

The path to the file which has been written

select_config_file(path: str) → None

use this config file instead of the default

set_ui_callback(callback: Callable[[Message], None]) → None

Register a user interface notification callback function to all ConfigFile instances created by this object.

See ConfigFile.set_ui_callback().

ui_notifier: UiNotifier

Can be used to print messages to the user interface, uses notification_level_ui

update_config_and_exit() → None

rewrite the config file, open it for editing and exit