1 configs.base

configs.base

Typed config-as-factory foundation for ARIA-NBV runtime objects.

This module provides BaseConfig, generic TargetConfig, and singleton SingletonConfig. It owns Pydantic validation, nested config serialization, TOML/cache representations, and the standard runtime-construction hook; concrete configs own domain defaults and target classes own runtime behavior.

Configs validate nested experiment state, serialize stable TOML/cache payloads, and construct runtime targets through BaseConfig.setup_target. Runtime objects stay outside the persisted config graph; late-bound dependencies are passed explicitly to setup_target.

1.1 Classes

Name Description
BaseConfig Validate, serialize, inspect, and instantiate one configuration tree.
SingletonConfig Base class for singleton configurations.
TargetConfig Typed config-as-factory base whose setup_target returns TargetT.

1.1.1 BaseConfig

configs.base.BaseConfig()

Validate, serialize, inspect, and instantiate one configuration tree.

Subclasses that construct runtime objects should inherit TargetConfig and expose target_type. Plain subclasses may use setup_target as a no-op and still share TOML, cache, and CLI behavior.

1.1.1.1 Attributes

Name Description
cache_exclude_fields Field names to exclude from cache snapshots.
cache_exclude_extra_key json_schema_extra key for marking fields excluded from cache snapshots.
propagation_exclude_fields Field names that must not propagate into nested config identities.
target_type Callable target used by setup_target.
target Compatibility alias for target_type.
propagated_fields Track which fields were propagated from a parent config.

1.1.1.2 Methods

Name Description
setup_target Instantiate or return the target object for this config, if applicable.
settings_customise_sources Restrict default settings sources to init + optional TOML/CLI.
model_dump_jsonable Return a JSON-serializable dump suitable for logging/checkpoint metadata.
model_dump_cache Return a cache-friendly dump with per-field cache exclusions.
to_jsonable Convert nested configs and common types into JSON-friendly primitives.
to_toml Serialise the config (and nested configs) to TOML.
save_toml Persist the configuration to a TOML file and return the resolved path.
from_toml Load a config from a TOML string or file path.
inspect Render the nested configuration as a Rich tree on the project console.
1.1.1.2.1 setup_target
configs.base.BaseConfig.setup_target(*args, **kwargs)

Instantiate or return the target object for this config, if applicable.

Prioritizes a ‘setup_target’ method on the target itself and falls back to calling the init method.

1.1.1.2.2 settings_customise_sources
configs.base.BaseConfig.settings_customise_sources(
    settings_cls,
    init_settings,
    env_settings,
    dotenv_settings,
    file_secret_settings,
)

Restrict default settings sources to init + optional TOML/CLI.

By default, environment/dotenv/file-secret sources are disabled for safety. Classes can opt into CLI by setting cli_parse_args=True in model_config or override this method for custom behavior.

1.1.1.2.3 model_dump_jsonable
configs.base.BaseConfig.model_dump_jsonable(**kwargs)

Return a JSON-serializable dump suitable for logging/checkpoint metadata.

1.1.1.2.4 model_dump_cache
configs.base.BaseConfig.model_dump_cache(exclude=None, exclude_none=True)

Return a cache-friendly dump with per-field cache exclusions.

1.1.1.2.4.1 Parameters
Name Type Description Default
exclude set[str] | None Additional field names to exclude from the snapshot. None
exclude_none bool Skip fields with value None when True. True
1.1.1.2.5 to_jsonable
configs.base.BaseConfig.to_jsonable(value)

Convert nested configs and common types into JSON-friendly primitives.

1.1.1.2.6 to_toml
configs.base.BaseConfig.to_toml(
    path=None,
    *,
    include_comments=True,
    include_type_hints=True,
)

Serialise the config (and nested configs) to TOML.

1.1.1.2.6.1 Parameters
Name Type Description Default
path Path | None Optional path to write the TOML to. None
include_comments bool Ignored (kept for API compatibility). True
include_type_hints bool Ignored (kept for API compatibility). True
1.1.1.2.6.2 Returns
Name Type Description
str The rendered TOML string.
1.1.1.2.7 save_toml
configs.base.BaseConfig.save_toml(
    path,
    *,
    include_comments=True,
    include_type_hints=True,
)

Persist the configuration to a TOML file and return the resolved path.

1.1.1.2.8 from_toml
configs.base.BaseConfig.from_toml(source)

Load a config from a TOML string or file path.

1.1.1.2.9 inspect
configs.base.BaseConfig.inspect(show_docs=False)

Render the nested configuration as a Rich tree on the project console.

1.1.1.2.9.1 Parameters
Name Type Description Default
show_docs bool Include class and field documentation alongside values. False

1.1.2 SingletonConfig

configs.base.SingletonConfig(**kwargs)

Base class for singleton configurations.

1.1.3 TargetConfig

configs.base.TargetConfig()

Typed config-as-factory base whose setup_target returns TargetT.

TargetT describes the runtime object returned by setup_target; it does not have to be the same type as target_type when the target delegates to a custom factory method.

1.1.3.1 Methods

Name Description
setup_target Instantiate or return the typed target object for this config.
1.1.3.1.1 setup_target
configs.base.TargetConfig.setup_target(*args, **kwargs)

Instantiate or return the typed target object for this config.

Back to top