Config¶

Configuration object for loading and accessing configuration values.

The Config class is the main entry point for holoconf. It provides methods for loading configuration from files or strings, accessing values with automatic interpolation resolution, and exporting configuration in various formats.

Example

config = Config.load("config.yaml") host = config.get("database.host") port = config.get_int("database.port")

Functions¶

load `staticmethod` ¶

load(
    path: str,
    schema: str | None = None,
    file_roots: list[str] | None = None,
    allow_http: bool = False,
    http_allowlist: list[str] | None = None,
    http_proxy: str | None = None,
    http_proxy_from_env: bool = False,
    http_ca_bundle: str | bytes | None = None,
    http_extra_ca_bundle: str | bytes | None = None,
    http_client_cert: str | bytes | None = None,
    http_client_key: str | bytes | None = None,
    http_client_key_password: str | None = None,
) -> Config

Load configuration from a YAML file (required - errors if missing).

This is the primary way to load configuration. Use Config.optional() for files that may not exist.

PARAMETER	DESCRIPTION
`path`	Path to the YAML file TYPE: `str`
`schema`	Optional path to a JSON Schema file. If provided, schema defaults will be used when accessing missing paths. TYPE: `str \| None` DEFAULT: `None`
`file_roots`	Additional allowed directory paths for file resolver (security). The config file's parent directory is automatically allowed. TYPE: `list[str] \| None` DEFAULT: `None`
`allow_http`	Enable HTTP resolver (disabled by default for security) TYPE: `bool` DEFAULT: `False`
`http_allowlist`	List of URL patterns to allow (glob-style) TYPE: `list[str] \| None` DEFAULT: `None`
`http_proxy`	Proxy URL (e.g., "http://proxy:8080" or "socks5://proxy:1080") TYPE: `str \| None` DEFAULT: `None`
`http_proxy_from_env`	Auto-detect proxy from HTTP_PROXY/HTTPS_PROXY env vars TYPE: `bool` DEFAULT: `False`
`http_ca_bundle`	CA bundle (str path/PEM or bytes P12) - replaces default roots TYPE: `str \| bytes \| None` DEFAULT: `None`
`http_extra_ca_bundle`	Extra CA bundle (str path/PEM or bytes P12) - adds to roots TYPE: `str \| bytes \| None` DEFAULT: `None`
`http_client_cert`	Client cert (str path/PEM or bytes P12) for mTLS TYPE: `str \| bytes \| None` DEFAULT: `None`
`http_client_key`	Client key (str path/PEM or bytes P12, not needed for P12) TYPE: `str \| bytes \| None` DEFAULT: `None`
`http_client_key_password`	Password for encrypted key or P12/PFX file TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`Config`	A new Config object

RAISES	DESCRIPTION
`HoloconfError`	If the file cannot be read or doesn't exist
`ParseError`	If the file cannot be parsed

Example

config = Config.load("config.yaml", schema="schema.yaml") config.pool_size # Returns schema default if not in config

required `staticmethod` ¶

required(
    path: str,
    schema: str | None = None,
    file_roots: list[str] | None = None,
    allow_http: bool = False,
    http_allowlist: list[str] | None = None,
    http_proxy: str | None = None,
    http_proxy_from_env: bool = False,
    http_ca_bundle: str | bytes | None = None,
    http_extra_ca_bundle: str | bytes | None = None,
    http_client_cert: str | bytes | None = None,
    http_client_key: str | bytes | None = None,
    http_client_key_password: str | None = None,
) -> Config

Alias for load() - load a required config file.

Provided for symmetry with Config.optional().

PARAMETER	DESCRIPTION
`path`	Path to the YAML file TYPE: `str`
`schema`	Optional path to a JSON Schema file TYPE: `str \| None` DEFAULT: `None`
`file_roots`	Additional allowed directory paths for file resolver (security). The config file's parent directory is automatically allowed. TYPE: `list[str] \| None` DEFAULT: `None`
`allow_http`	Enable HTTP resolver (disabled by default for security) TYPE: `bool` DEFAULT: `False`
`http_allowlist`	List of URL patterns to allow (glob-style) TYPE: `list[str] \| None` DEFAULT: `None`
`http_proxy`	Proxy URL (e.g., "http://proxy:8080" or "socks5://proxy:1080") TYPE: `str \| None` DEFAULT: `None`
`http_proxy_from_env`	Auto-detect proxy from HTTP_PROXY/HTTPS_PROXY env vars TYPE: `bool` DEFAULT: `False`
`http_ca_bundle`	CA bundle (str path/PEM or bytes P12) - replaces default roots TYPE: `str \| bytes \| None` DEFAULT: `None`
`http_extra_ca_bundle`	Extra CA bundle (str path/PEM or bytes P12) - adds to roots TYPE: `str \| bytes \| None` DEFAULT: `None`
`http_client_cert`	Client cert (str path/PEM or bytes P12) for mTLS TYPE: `str \| bytes \| None` DEFAULT: `None`
`http_client_key`	Client key (str path/PEM or bytes P12, not needed for P12) TYPE: `str \| bytes \| None` DEFAULT: `None`
`http_client_key_password`	Password for encrypted key or P12/PFX file TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`Config`	A new Config object

RAISES	DESCRIPTION
`HoloconfError`	If the file cannot be read or doesn't exist
`ParseError`	If the file cannot be parsed

optional `staticmethod` ¶

optional(path: str) -> Config

Load an optional configuration file.

Returns an empty Config if the file doesn't exist. Use this for configuration files that may or may not be present, such as local overrides.

PARAMETER	DESCRIPTION
`path`	Path to the config file TYPE: `str`

RETURNS	DESCRIPTION
`Config`	A Config object (empty if file doesn't exist)

Example

base = Config.load("base.yaml") local = Config.optional("local.yaml") base.merge(local)

loads `staticmethod` ¶

loads(
    yaml: str,
    base_path: str | None = None,
    file_roots: list[str] | None = None,
    allow_http: bool = False,
    http_allowlist: list[str] | None = None,
    http_proxy: str | None = None,
    http_proxy_from_env: bool = False,
    http_ca_bundle: str | bytes | None = None,
    http_extra_ca_bundle: str | bytes | None = None,
    http_client_cert: str | bytes | None = None,
    http_client_key: str | bytes | None = None,
    http_client_key_password: str | None = None,
) -> Config

Load configuration from a YAML string.

PARAMETER	DESCRIPTION
`yaml`	YAML content as a string TYPE: `str`
`base_path`	Optional base path for resolving relative file references TYPE: `str \| None` DEFAULT: `None`
`file_roots`	Additional allowed directory paths for file resolver (security). If base_path is set, it's automatically allowed. TYPE: `list[str] \| None` DEFAULT: `None`
`allow_http`	Enable HTTP resolver (disabled by default for security) TYPE: `bool` DEFAULT: `False`
`http_allowlist`	List of URL patterns to allow (glob-style) TYPE: `list[str] \| None` DEFAULT: `None`
`http_proxy`	Proxy URL (e.g., "http://proxy:8080" or "socks5://proxy:1080") TYPE: `str \| None` DEFAULT: `None`
`http_proxy_from_env`	Auto-detect proxy from HTTP_PROXY/HTTPS_PROXY env vars TYPE: `bool` DEFAULT: `False`
`http_ca_bundle`	CA bundle (str path/PEM or bytes P12) - replaces default roots TYPE: `str \| bytes \| None` DEFAULT: `None`
`http_extra_ca_bundle`	Extra CA bundle (str path/PEM or bytes P12) - adds to roots TYPE: `str \| bytes \| None` DEFAULT: `None`
`http_client_cert`	Client cert (str path/PEM or bytes P12) for mTLS TYPE: `str \| bytes \| None` DEFAULT: `None`
`http_client_key`	Client key (str path/PEM or bytes P12, not needed for P12) TYPE: `str \| bytes \| None` DEFAULT: `None`
`http_client_key_password`	Password for encrypted key or P12/PFX file TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`Config`	A new Config object

RAISES	DESCRIPTION
`ParseError`	If the YAML is invalid

from_json `staticmethod` ¶

from_json(json: str) -> Config

Load configuration from a JSON string.

PARAMETER	DESCRIPTION
`json`	JSON content as a string TYPE: `str`

RETURNS	DESCRIPTION
`Config`	A new Config object

RAISES	DESCRIPTION
`ParseError`	If the JSON is invalid

get ¶

get(path: str) -> Any

Get a resolved value by path (e.g., "database.host").

Interpolations like ${env:VAR} are resolved before returning.

PARAMETER	DESCRIPTION
`path`	Dot-separated path to the value TYPE: `str`

RETURNS	DESCRIPTION
`Any`	The resolved value (str, int, float, bool, list, dict, or None)

RAISES	DESCRIPTION
`PathNotFoundError`	If the path doesn't exist
`ResolverError`	If resolution fails (e.g., missing env var)

get_raw ¶

get_raw(path: str) -> Any

Get the raw (unresolved) value by path.

Returns the value without resolving interpolations. Useful for debugging or inspecting the raw configuration.

PARAMETER	DESCRIPTION
`path`	Dot-separated path to the value TYPE: `str`

RETURNS	DESCRIPTION
`Any`	The raw value (may contain ${...} interpolation syntax)

RAISES	DESCRIPTION
`PathNotFoundError`	If the path doesn't exist

get_string ¶

get_string(path: str) -> str

Get a string value, with type coercion if needed.

PARAMETER	DESCRIPTION
`path`	Dot-separated path to the value TYPE: `str`

RETURNS	DESCRIPTION
`str`	The value as a string

RAISES	DESCRIPTION
`TypeCoercionError`	If the value cannot be converted to string

get_int ¶

get_int(path: str) -> int

Get an integer value, with type coercion if needed.

String values like "42" will be parsed as integers.

PARAMETER	DESCRIPTION
`path`	Dot-separated path to the value TYPE: `str`

RETURNS	DESCRIPTION
`int`	The value as an integer

RAISES	DESCRIPTION
`TypeCoercionError`	If the value cannot be converted to integer

get_float ¶

get_float(path: str) -> float

Get a float value, with type coercion if needed.

String values like "3.14" will be parsed as floats.

PARAMETER	DESCRIPTION
`path`	Dot-separated path to the value TYPE: `str`

RETURNS	DESCRIPTION
`float`	The value as a float

RAISES	DESCRIPTION
`TypeCoercionError`	If the value cannot be converted to float

get_bool ¶

get_bool(path: str) -> bool

Get a boolean value, with strict coercion.

Only "true" and "false" (case-insensitive) are accepted for string coercion.

PARAMETER	DESCRIPTION
`path`	Dot-separated path to the value TYPE: `str`

RETURNS	DESCRIPTION
`bool`	The value as a boolean

RAISES	DESCRIPTION
`TypeCoercionError`	If the value cannot be converted to boolean

to_dict ¶

to_dict(
    resolve: bool = True, redact: bool = False
) -> dict[str, Any]

Export the configuration as a Python dict.

Binary data (from file resolver with encoding=binary) is returned as Python bytes objects.

PARAMETER	DESCRIPTION
`resolve`	If True (default), resolve all interpolations. If False, return raw values. TYPE: `bool` DEFAULT: `True`
`redact`	If True (default False), redact sensitive values with "[REDACTED]" TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`dict[str, Any]`	The configuration as a Python dictionary. Values may include bytes objects.

to_yaml ¶

to_yaml(resolve: bool = True, redact: bool = False) -> str

Export the configuration as YAML.

Binary data (from file resolver with encoding=binary) is serialized as base64 strings.

PARAMETER	DESCRIPTION
`resolve`	If True (default), resolve all interpolations. If False, return raw values. TYPE: `bool` DEFAULT: `True`
`redact`	If True (default False), redact sensitive values with "[REDACTED]" TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`str`	The configuration as a YAML string

to_json ¶

to_json(resolve: bool = True, redact: bool = False) -> str

Export the configuration as JSON.

Binary data (from file resolver with encoding=binary) is serialized as base64 strings.

PARAMETER	DESCRIPTION
`resolve`	If True (default), resolve all interpolations. If False, return raw values. TYPE: `bool` DEFAULT: `True`
`redact`	If True (default False), redact sensitive values with "[REDACTED]" TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`str`	The configuration as a JSON string

merge ¶

merge(other: Config) -> None

Merge another config into this one.

The other config's values override this config's values.

PARAMETER	DESCRIPTION
`other`	Another Config to merge into this one TYPE: `Config`

resolve_all ¶

resolve_all() -> None

Resolve all values eagerly.

By default, values are resolved lazily when accessed. This method forces resolution of all values upfront, which can be useful for detecting errors early or for performance when all values are needed.

RAISES	DESCRIPTION
`ResolverError`	If any value fails to resolve

clear_cache ¶

clear_cache() -> None

Clear the resolution cache.

Resolved values are cached for performance. Call this method to clear the cache, for example after environment variables have changed.

get_source ¶

get_source(path: str) -> str | None

Get the source file for a config path.

Returns the filename of the config file that provided this value. For merged configs, this returns the file that "won" for this path.

PARAMETER	DESCRIPTION
`path`	The config path (e.g., "database.host") TYPE: `str`

RETURNS	DESCRIPTION
`str \| None`	The filename or None if source tracking is not available

dump_sources ¶

dump_sources() -> dict[str, str]

Get all source mappings.

Returns a dict mapping config paths to their source filenames. Useful for debugging which file each value came from.

RETURNS	DESCRIPTION
`dict[str, str]`	A dict of {path: filename} entries

set_schema ¶

set_schema(schema: Schema) -> None

Attach a schema to this config for default value lookup.

When a schema is attached, accessing a missing path will return the schema's default value (if defined) instead of raising PathNotFoundError.

PARAMETER	DESCRIPTION
`schema`	A Schema object to attach TYPE: `Schema`

Example

config = Config.load("config.yaml") schema = Schema.load("schema.yaml") config.set_schema(schema) config.pool_size # Returns schema default if not in config

get_schema ¶

get_schema() -> Schema | None

Get the attached schema, if any.

RETURNS	DESCRIPTION
`Schema \| None`	The attached Schema object, or None if no schema is attached

validate ¶

validate(schema: Schema | None = None) -> None

Validate the resolved configuration against a schema.

This resolves all values first, then validates the resolved values against the schema, checking types, constraints, and patterns.

PARAMETER	DESCRIPTION
`schema`	Optional Schema object to validate against. If not provided, uses the attached schema (set via `set_schema()` or `load(schema=...)`). TYPE: `Schema \| None` DEFAULT: `None`

RAISES	DESCRIPTION
`ValidationError`	If validation fails
`ResolverError`	If resolution fails
`HoloconfError`	If no schema is provided and none is attached

validate_raw ¶

validate_raw(schema: Schema | None = None) -> None

Validate the raw (unresolved) configuration against a schema.

This performs structural validation before resolution, checking that required keys exist and the configuration structure matches the schema. Interpolation placeholders (${...}) are allowed as valid values.

PARAMETER	DESCRIPTION
`schema`	Optional Schema object to validate against. If not provided, uses the attached schema (set via `set_schema()` or `load(schema=...)`). TYPE: `Schema \| None` DEFAULT: `None`

RAISES	DESCRIPTION
`ValidationError`	If validation fails
`HoloconfError`	If no schema is provided and none is attached

validate_collect ¶

validate_collect(schema: Schema | None = None) -> list[str]

Validate and collect all errors (instead of failing on first).

PARAMETER	DESCRIPTION
`schema`	Optional Schema object to validate against. If not provided, uses the attached schema (set via `set_schema()` or `load(schema=...)`). TYPE: `Schema \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[str]`	A list of error message strings (empty if valid)

RAISES	DESCRIPTION
`HoloconfError`	If no schema is provided and none is attached

getitem ¶

__getitem__(key: str) -> Any

Dict-like access: config["key"].

getattr ¶

__getattr__(name: str) -> Any

Attribute access: config.key.

Config¶

Functions¶

load staticmethod ¶

required staticmethod ¶

optional staticmethod ¶

loads staticmethod ¶

from_json staticmethod ¶

get ¶

get_raw ¶

get_string ¶

get_int ¶

get_float ¶

get_bool ¶

to_dict ¶

to_yaml ¶

to_json ¶

merge ¶

resolve_all ¶

clear_cache ¶

get_source ¶

dump_sources ¶

set_schema ¶

get_schema ¶

validate ¶

validate_raw ¶

validate_collect ¶

__getitem__ ¶

__getattr__ ¶

load `staticmethod` ¶

required `staticmethod` ¶

optional `staticmethod` ¶

loads `staticmethod` ¶

from_json `staticmethod` ¶

getitem ¶

getattr ¶