upsies.utils.config.base

Base classes for configuration models

Classes

class upsies.utils.config.base.ConfigBase

Bases: ConfigDictBase

Root-level configuration model

Instances map section names to SectionBase subclass instances.

From a user perspective, a section is a file name without the file extension, e.g. “clients” for “~/.config/upsies/clients.ini”.

section_names: ClassVar = ()

Sequence of valid section names

validate_config()

Pass this ConfigBase instance to SectionBase.validate_config() on all sections

Returns:

the ConfigBase instance (i.e. the first argument self)

dump()

Return all values as a human-readable tree structure string

dump_defaults()

Return default values as a human-readable tree structure string

property files

Mapping of section names to file paths

Section names should be file stems, i.e. file names without extensions.

read(section_name, filepath, *, ignore_missing=False)

Read filepath and make its contents available as section

Raises:

ConfigError – if reading, parsing or validating filepath fails

write(*sections, include_defaults=False)

Save current configuration to files

List values use "\n " (newline followed by two spaces) as separators between items.

Parameters:

• sections – Sections to write (see files) Write all sections if no sections are provided.

• include_defaults (bool) – Whether to include commented defaults

Raises:

ConfigError – if writing fails

defaults = ConfigBaseDefaults()

Class property that holds an instance of this class with default values

See _CreateDefaults.

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class upsies.utils.config.base.ConfigDictBase

Bases: MutableMapping, BaseModel

pydantic.BaseModel that provides dictionary field access

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

defaults: ClassVar = ConfigDictBaseDefaults()

Class property that holds an instance of this class with default values

See _CreateDefaults.

class upsies.utils.config.base.SectionBase

Bases: ConfigDictBase

Configuration model of one section

Instances map subsection names to SubsectionBase instances.

From a user perspective, a subsection a section in an INI file, e.g. “[qbittorrent]” in ~/.config/upsies/clients.ini.

validate_config(config)

Called by ConfigBase.validate_config() with its own instance after validation

This method does nothing by default. Subclasses can override it if access to sibling sections is required for validation.

get_comment()

Optional comment that explains the section to the user

as_ini(*, include_defaults=False)

Return section in INI file format

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class upsies.utils.config.base.SubsectionBase

Bases: ConfigDictBase

Configuration model of one subsection

Instances map option names to values.

From a user perspective, an option is a single key-value pair in a section in an INI file, e.g. “foo = bar”.

get_description(option)

Return the description for option or empty string

as_ini(*, include_defaults=False, comment_defaults=True)

Return option-value pairs in INI file format

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'validate_assignment': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].