confattr package¶
Submodules¶
- confattr.config module
Config
Config.LIST_SEP
Config.default_config_id
Config.format_allowed_values()
Config.format_allowed_values_or_type()
Config.format_any_value()
Config.format_type()
Config.format_value()
Config.instances
Config.key
Config.parse_and_set_value()
Config.parse_value()
Config.parse_value_part()
Config.wants_to_be_exported()
ConfigTrackingChanges
DictConfig
InstanceSpecificDictMultiConfig
MultiConfig
MultiDictConfig
- confattr.configfile module
ConfigFile
ConfigFile.COMMENT
ConfigFile.COMMENT_PREFIXES
ConfigFile.ENTER_GROUP_PREFIX
ConfigFile.ENTER_GROUP_SUFFIX
ConfigFile.FILENAME
ConfigFile.INCLUDE
ConfigFile.KEY_VAL_SEP
ConfigFile.SET
ConfigFile.enter_group()
ConfigFile.format_value()
ConfigFile.get_app_dirs()
ConfigFile.include()
ConfigFile.is_comment()
ConfigFile.iter_config_paths()
ConfigFile.iter_user_site_config_paths()
ConfigFile.load()
ConfigFile.load_file()
ConfigFile.load_without_resetting_config_id()
ConfigFile.parse_and_set_value()
ConfigFile.parse_error()
ConfigFile.parse_key_and_set_value()
ConfigFile.parse_line()
ConfigFile.parse_splitted_line()
ConfigFile.primitive_types
ConfigFile.save()
ConfigFile.save_file()
ConfigFile.save_to_open_file()
ConfigFile.set()
ConfigFile.set_multiple()
ConfigFile.set_with_spaces()
ConfigFile.strip_indentation()
ConfigFile.unknown_command()
ConfigFile.write_data_types()
ConfigFile.write_help()
MultipleParseExceptions
NotificationLevel
ParseException
UiNotifier
readable_quote()
- confattr.subprocess_pipe module
- confattr.types module
Module contents¶
Config Attributes
A python library to read and write config files with a syntax inspired by vimrc and ranger config.
- class confattr.Config(key: str, default: T, *, help: Optional[Union[str, dict[T, str]]] = None, unit: Optional[str] = None, parent: Optional[DictConfig[Any, T]] = None, allowed_values: Optional[Sequence[T]] = None)¶
Bases:
Generic
[T
]Each instance of this class represents a setting which can be changed in a config file.
This class implements the descriptor protocol to return
value
if an instance of this class is accessed as an instance attribute. If you want to get this object you need to access it as a class instance.- Parameters:
key – The name of this setting in the config file
default – The default value of this setting
help – A description of this setting
unit – The unit of an int or float value
T
can be one of:a subclass of
enum.Enum
a class where
__str__()
returns a string representation which can be passed to the constructor to create an equal object. If that class has a str attributetype_name
this is used instead of the class name inside of config file. If that class has a str attributehelp
this is used instead of the doc string when explaining the type at the beginning of the config file.
- Raises:
ValueError – if key is not unique
- LIST_SEP = ','¶
- default_config_id = 'general'¶
- instances: dict[str, confattr.config.Config[Any]] = {}¶
- parse_value_part(t: type[T1], value: str) T1 ¶
- Raises:
ValueError – if value is invalid
- class confattr.ConfigFile(ui_callback: Callable[[NotificationLevel, str | BaseException], None], *, appname: str, authorname: Optional[str] = None, config_instances: dict[str, confattr.config.Config[Any]] = {})¶
Bases:
object
Read or write a config file.
- Parameters:
ui_callback – A function to display messages to the user
appname – The name of the application, required for generating the path of the config file if you use
load()
orsave()
authorname – The name of the developer of the application, on MS Windows useful for generating the path of the config file if you use
load()
orsave()
config_instances – The Config instances to load or save
- COMMENT = '#'¶
- COMMENT_PREFIXES = ('"', '#')¶
- ENTER_GROUP_PREFIX = '['¶
- ENTER_GROUP_SUFFIX = ']'¶
- FILENAME = 'config'¶
- INCLUDE = ('include',)¶
- KEY_VAL_SEP = '='¶
- SET = ('set',)¶
- enter_group(ln: str) bool ¶
Check if ln starts a new group and set
config_id
if it does.- Parameters:
ln – The current line
- Returns:
True if ln starts a new group
- get_app_dirs() AppDirs ¶
Create or get a cached AppDirs instance with multipath support enabled.
When creating a new instance, platformdirs, xdgappdirs and appdirs are tried, in that order. The first one installed is used. appdirs, the original of the two forks and the only one of the three with type stubs, is specified in pyproject.toml as a hard dependency so that at least one of the three should always be available. I am not very familiar with the differences but if a user finds that appdirs does not work for them they can choose to use an alternative with
pipx inject appname xdgappdirs|platformdirs
.
- is_comment(ln: str) bool ¶
Check if ln is a comment.
- Parameters:
ln – The current line
- Returns:
True if ln is a comment
- iter_config_paths() Iterator[str] ¶
Iterate over all paths which are checked for config files, user specific first.
Use this method if you want to tell the user where the application is looking for it’s config file. The first existing file yielded by this method is used by
load()
. The paths are based onget_app_dirs()
.
- iter_user_site_config_paths() Iterator[str] ¶
Iterate over all directories which are searched for config files.
- load() None ¶
Load the first existing config file returned by
iter_config_paths()
.If there are several config files a user specific config file is preferred. If a user wants a system wide config file to be loaded, too, they can explicitly include it in their config file.
- load_file(fn: str) None ¶
Load a config file and change the
Config
objects accordingly. Errors are communicated viaui_notifier
.- Parameters:
fn – The file name of the config file (absolute or relative path)
- parse_error(msg: str, ln: str, lnno: int | None) None ¶
Is called if something went wrong while trying to load a config file. This method compiles the given information into an error message and calls
UiNotifier.show_error()
.- Parameters:
msg – The error message
ln – The line where the error occured
lnno – The number of the line
- parse_line(ln: str, lnno: Optional[int] = None, fn: Optional[str] = None) None ¶
- Parameters:
ln – The line to be parsed
lnno – The number of the line, used in error messages
fn – The name of the file from which ln was read (absolute or relative path), used in error messages and for relative imports
lnno and fn are allowed to be None in case ln is not read from a config file but from a command line.
parse_error()
is called if something goes wrong, e.g. invalid key or invalid value.
- parse_splitted_line(ln_splitted: Sequence[str], ln: str, lnno: Optional[int] = None, fn: Optional[str] = None) None ¶
- primitive_types = {<class 'str'>, <class 'bool'>, <class 'int'>, <class 'float'>}¶
- save(config_instances: Optional[Iterable[Union[Config[Any], DictConfig[Any, Any]]]] = None, *, ignore: Optional[Iterable[Union[Config[Any], DictConfig[Any, Any]]]] = None, no_multi: bool = False, comments: bool = True) str ¶
Save the current values of all settings to the first existing and writable file returned by
iter_config_paths()
or to the first path if none of the files are existing and writable.- Parameters:
config_instances – Do not save all settings but only those given. If this is a
list
they are written in the given order. If this is aset
they are sorted by their keys.ignore – Do not write these settings to the file.
no_multi – Do not write several sections. For
MultiConfig
instances write the default values only.comments – Write comments with allowed values and help.
- Returns:
The path to the file which has been written
- save_file(fn: str, config_instances: Optional[Iterable[Union[Config[Any], DictConfig[Any, Any]]]] = None, *, ignore: Optional[Iterable[Union[Config[Any], DictConfig[Any, Any]]]] = None, no_multi: bool = False, comments: bool = True) None ¶
Save the current values of all settings to a specific file.
- Parameters:
fn – The name of the file to write to (absolute or relative path)
For an explanation of the other parameters see
save()
.
- save_to_open_file(f: TextIO, config_instances: Optional[Iterable[Union[Config[Any], DictConfig[Any, Any]]]] = None, *, ignore: Optional[Iterable[Union[Config[Any], DictConfig[Any, Any]]]] = None, no_multi: bool = False, comments: bool = True) None ¶
Save the current values of all settings to file-like object.
- Parameters:
f – The file to write to
For an explanation of the other parameters see
save()
.
- unknown_command(ln_splitted: Sequence[str], ln: str, lnno: int | None, fn: str | None) Optional[NoReturn] ¶
- write_data_types(f: TextIO, config_keys: Iterable[str], ignore: collections.abc.Iterable[confattr.config.Config[Any]] | None) None ¶
- class confattr.ConfigTrackingChanges(key: str, default: T, *, help: Optional[Union[str, dict[T, str]]] = None, unit: Optional[str] = None, parent: Optional[DictConfig[Any, T]] = None, allowed_values: Optional[Sequence[T]] = None)¶
Bases:
Config
[T
]- Parameters:
key – The name of this setting in the config file
default – The default value of this setting
help – A description of this setting
unit – The unit of an int or float value
T
can be one of:a subclass of
enum.Enum
a class where
__str__()
returns a string representation which can be passed to the constructor to create an equal object. If that class has a str attributetype_name
this is used instead of the class name inside of config file. If that class has a str attributehelp
this is used instead of the doc string when explaining the type at the beginning of the config file.
- Raises:
ValueError – if key is not unique
- has_changed() bool ¶
- Returns:
True if
value
has been changed since the last call tosave_value()
- restore_value() None ¶
Restore
value
to the value before the last call ofsave_value()
.
- property value: T¶
- class confattr.DictConfig(key_prefix: str, default_values: dict[T_KEY, T], *, ignore_keys: Container[T_KEY] = {}, unit: Optional[str] = None, help: Optional[str] = None, allowed_values: Optional[Sequence[T]] = None)¶
Bases:
Generic
[T_KEY
,T
]- Parameters:
key_prefix –
default –
ignore_keys –
unit –
help –
- Raises:
ValueError – if a key is not unique
- class confattr.InstanceSpecificDictMultiConfig(dmc: MultiDictConfig[T_KEY, T], config_id: ConfigId)¶
Bases:
Generic
[T_KEY
,T
]
- class confattr.MultiConfig(key: str, default: T, *, unit: Optional[str] = None, help: Optional[Union[str, dict[T, str]]] = None, parent: Optional[MultiDictConfig[Any, T]] = None, allowed_values: Optional[Sequence[T]] = None)¶
Bases:
Config
[T
]- Parameters:
key – The name of this setting in the config file
default – The default value of this setting
help – A description of this setting
unit – The unit of an int or float value
T
can be one of:a subclass of
enum.Enum
a class where
__str__()
returns a string representation which can be passed to the constructor to create an equal object. If that class has a str attributetype_name
this is used instead of the class name inside of config file. If that class has a str attributehelp
this is used instead of the doc string when explaining the type at the beginning of the config file.
- Raises:
ValueError – if key is not unique
- class confattr.MultiDictConfig(key_prefix: str, default_values: dict[T_KEY, T], *, ignore_keys: Container[T_KEY] = {}, unit: Optional[str] = None, help: Optional[str] = None, allowed_values: Optional[Sequence[T]] = None)¶
Bases:
DictConfig
[T_KEY
,T
]- Parameters:
key_prefix –
default –
ignore_keys –
unit –
help –
- Raises:
ValueError – if a key is not unique
- exception confattr.MultipleParseExceptions(exceptions: Sequence[ParseException])¶
Bases:
Exception
This is raised and caught inside of
ConfigFile
to communicate errors while parsing a config file where multiple settings are set in the same line. If you don’t intend to subclassConfigFile
you do not need to worry about this class.
- class confattr.NotificationLevel(value)¶
Bases:
Enum
An enumeration.
- ERROR = 'error'¶
- INFO = 'info'¶
- exception confattr.ParseException¶
Bases:
Exception
This is raised and caught inside of
ConfigFile
to communicate errors while parsing a config file. If you don’t intend to subclassConfigFile
you do not need to worry about this class.
- confattr.readable_quote(value: str) str ¶
This function has the same goal like
shlex.quote()
but tries to generate better readable output.- Parameters:
value – A value which is intended to be used as a command line argument
- Returns:
A POSIX compliant quoted version of
value