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[module] = [])
Bases:
object
Defines two
ConfigFile
instances with separately configurable notification levels forload()
andparse_line()
. This object also providescreate_argument_parser()
to create anargparse.ArgumentParser
with commonly needed arguments. Note that allConfig
instances must be created before instantiating this class.- Parameters:
appname¶ – The name of the app, used to initialize
ConfigFile
and when printing the version numberversion¶ – 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 anargparse.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 callingcreate_empty_argument_parser()
,add_config_help_argument()
,add_version_argument()
andadd_config_related_arguments()
.
- create_empty_argument_parser() ArgumentParser
Create an
argparse.ArgumentParser
with thedoc
passed to the constructor as description andHelpFormatter
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.
- 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_errors_without_ui() None
Call
set_ui_callback()
withprint()
so that all messages are printed to the terminal.
- 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
- set_ui_callback(callback: Callable[[Message], None]) None
Register a user interface notification callback function to all
ConfigFile
instances created by this object.
- ui_notifier: UiNotifier
Can be used to print messages to the user interface, uses
notification_level_ui