Core API#

The core API is centered on Confease, a configuration container that stores Confitem values with an origin and resolves conflicts through configurable precedence.

Origins#

confease.CLI#

Origin name for values loaded from command-line arguments.

confease.ENV#

Origin name for values loaded from environment variables.

confease.SYS#

Origin name for values loaded from configuration files outside the current user’s home directory.

confease.USR#

Origin name for values loaded from user configuration files or assigned through Confease.set().

confease.DEF#

Origin name for defaults passed to Confease.

confease.ORIGINS#

Ordered list of all supported origin names.

Confease#

class confease.Confease(path=None, reload=False, parser=<class 'confease.parsers.Yaml'>, template=None, preference=['cli', 'env', 'system', 'user', 'default'], **kwargs)#

Configuration container with defaults, persistence, and precedence.

Confease keeps one effective value per key. Values can come from defaults, files, environment variables, or command-line namespaces, and the configured preference decides which origin wins when multiple sources define the same key.

The container supports one nested level. Nested mappings are flattened into dotted Confitem leaves internally, while nested-capable file formats are saved and loaded as ordinary nested mappings.

Parameters:

  • path (str | Path | None)

  • reload (bool)

  • parser (type[Parser] | None)

  • template (str | Path | None)

property preference#

Return source origins ordered from highest to lowest priority.

load(path=None)#

Load configuration values from a file as user-origin entries.

Parameters:

path (str | Path | None) – Optional file path to load instead of the instance path.

Raises:

  • FileNotFoundError – If no path is available or the target file does not exist.

  • ValueError – If the parser rejects the file shape or keys collide.

save(user_only=True)#

Persist configuration to the instance path.

Parameters:

user_only (bool) – When true, write only USR entries. When false, write all effective entries, including defaults and overrides from other origins.

Notes

Runtime-only configurations created without path are a no-op when saved.

reset()#

Reset in-memory entries to defaults or the configured template.

get(key, default=None, cast=None)#

Return a value or one-level section by key.

Parameters:

  • key (str) – Scalar key, dotted nested key, or section name.

  • default – Value returned when neither a leaf nor a section exists.

  • cast – Optional callable used to coerce the returned value. Cast failures are reported and the original value is returned.

Returns:

The stored value, a plain dictionary snapshot for section reads, or default when the key is missing.

get_item(key)#

Return the matching leaf item.

Parameters:

key (str) – Scalar or dotted key to look up.

Return type:

Confitem | None

Returns:

The matching Confitem, or None when no leaf exists. Section names do not return an item; use get() for section snapshots.

set(key, value)#

Store a user-origin value.

Parameters:

  • key (str) – Scalar key, dotted nested key, or section name when value is a one-level mapping.

  • value (Any) – Python value to store. Nested dictionaries are flattened into dotted leaves.

Raises:

ValueError – If nested keys exceed one level or a scalar key collides with a section key.

__getitem__(key)#

Return get(key) so missing keys produce None.

Parameters:

key (str)

__setitem__(key, value)#

Assign through set(key, value).

Parameters:

  • key (str)

  • value (Any)

to_str()#

Reserved for a future detailed printable representation.

edit_file(user_only=True)#

Edit the configured file through a blocking text editor.

The current data is written to a temporary draft, opened in self.editor, parsed with the active parser, and only then moved over the real config file. Invalid edited content leaves the previous file and in-memory values unchanged.

Parameters:

user_only (bool) – When true, edit only user-origin entries. When false, edit the full effective configuration.

Returns:

The current Confease instance.

Raises:

  • FileNotFoundError – If the instance has no configured path.

  • ValueError – If the edited file is invalid for the active parser.

  • Exception – If launching or waiting for the editor fails.

load_sources(cli=None, *files, preference=None)#

Reload file, environment, and CLI sources.

Sources are loaded in file, environment, then CLI order. When the same key appears more than once, the configured origin preference determines the effective value.

Parameters:

  • cli (Namespace | None) – Optional argparse.Namespace whose non-None values are loaded with CLI origin.

  • *files – Additional config files. Files under the current user’s home directory are USR origin; all others are SYS origin.

  • preference (list[str] | None) – Optional source precedence override.

Raises:

  • FileNotFoundError – If any file path does not exist.

  • ValueError – If a file suffix, preference, or key shape is invalid.

reload_files(*paths)#

Load additional config files as system or user origins.

Parameters:

*paths – Config file paths. Parser selection is inferred from each suffix.

Raises:

  • FileNotFoundError – If a path does not exist.

  • ValueError – If a suffix is unsupported or loaded keys collide.

reload_cli(namespace)#

Load non-None argparse namespace values as CLI-origin entries.

Parameters:

namespace (Namespace) – Parsed command-line namespace. Attribute names become config keys, and nested dictionaries are flattened one level.

reload_env()#

Load known environment variables as ENV-origin entries.

Only keys already present in defaults or loaded entries are considered. Values are parsed with yaml.safe_load so common scalar text such as true, 5432, null, or [1, 2] becomes the corresponding Python value.

Confitem#

class confease.Confitem(key, value, origin)#

Single flattened configuration value with its source origin.

Confease stores effective configuration as Confitem leaves. Nested values use dotted keys such as "database.host" while preserving the original Python value type.

Parameters:

  • key (str)

  • value (Any)

  • origin (str)

property key#

Return the flattened config key.

property value#

Return the stored value without coercion.

property origin#

Return the source origin that provided this value.

__eq__(other)#

Compare by key for strings or by all fields for other items.

__repr__()#

Return a developer-friendly representation.

__str__()#

Return the string form of the stored value.