Haven configuration system

Welcome to the docs for haven-conf. This part is still under construction.

API

class haven.Component(config: TConf, func: Callable[[...], TRet])[source]

A simple wrapper that couples a config instance with a function or Class which accepts that config as the first argument.

class haven.ComponentBuilder[source]
exception haven.ParsingError[source]
haven.add_decoder(ty: type[T], func: Callable[[Any], T], include_subclasses: bool = False) → Callable[[Any], T][source]

Add a function for converting pytrees to instances of the given type.

Pytrees are composed of basic python builtin-types that are supported by YAML, JSON, and other similar formats.

Parameters:

  • ty (type[T]) – the type to register

  • func (Callable[[Any], T]) – a function that decodes pytrees into instances of T.

  • include_subclasses (bool, optional) – Whether to also apply this decoder for all subclasses of T. Defaults to False.

haven.add_encoder(ty: type[T], func: Callable[[T], Any]) → Callable[[T], Any][source]

Add function for converting instances of the given type to a pytree.

Pytrees are composed of basic python builtin-types that are supported by YAML, JSON, and other similar formats.

Parameters:

  • ty (type[T]) – the type to register

  • func (Callable[[T], Any]) – a function for encoding instances of the type T into a pytree.

haven.choice(choices: list[str | Callable[[...], Any] | type[_DataclassInstance]] | dict[str, str | Callable[[...], Any] | type[_DataclassInstance]] | ChoiceProvider, key_field: str = 'name', default_factory: Callable[[], T] | str | None = None) → T[source]

A field which dynamically selects the dataclass to decode based on the value of another string field.

Choice fields construct a name, dataclass mapping. During config parsing, the value of another field in the child or parent dataclass is used to lookup which dataclass to decode.

The choices argument can be either a list, dict, or instance of ChoiceProvider; if it is a list, then the name for each choice is determined automatically by inspecting the name of the class or function. The list/dict value can either contain the choices directly or strings of the form my_package.my_module.MyClass.

Note

The default_factory argument works as expected in standard dataclass construction, but when constructed via this library the value of the key field will always override it, since it controls which choice to use.

Parameters:

  • choices (list[ChoiceType] | dict[str, ChoiceType] | ChoiceProvider) – determines the possible choices

  • key_field (str, optional) – the name of the field which determines the choice at runtime. Defaults to “name”.

  • default_factory (Callable[..., T] | str, optional) – If str, import the object specified and use that class as the default factory. Otherwise, a callable that returns a dataclass instance or None for no default.

Raises:

  • ValueError – raised if import strings don’t follow the correct format.

  • TypeError – raised if the passed objects are not dataclasses or if choices is not a dict or list.

haven.dump(obj: _DataclassInstance, format: str = 'yaml') → str[source]

Convert an instance of a dataclass

See load() for a list of supported formats.

Parameters:

  • obj (Dataclass) – the object to encode.

  • format (str, optional) – the format to output. Defaults to “yaml”.

Raises:

ValueError – If an unknown format is specified.

Returns:

a text representation of the dataclass in the specified format.

Return type:

str

haven.dump_pytree(obj: _DataclassInstance) → dict[str, Any][source]

Encode a dataclass instance as a pytree

Parameters:

obj (Any) – the datalass instance to convert.

Returns:

a tree of basic python types matching the given dataclass.

Return type:

Pytree

haven.load(cls: type[TDataclass], stream: str | bytes | SupportsRead[str] | SupportsRead[bytes] | None = None, format: str = 'yaml', overrides: dict[str, Any] | None = None, dotlist_overrides: list[str] | None = None) → TDataclass[source]

Parse a text-based markup format and load it into an instance of the given dataclass

Supported formats:

  • “yaml”

  • “json”

Parameters:

  • cls (type[TDataclass]) – A dataclass to instantiate

  • stream (ReadStream) – A string or file-like object to read

  • format (str, optional) – The format to expect. Defaults to “yaml”.

  • overrides (Pytree, optional) – A pytree of values to override the values from the stream.

  • dotlist_overrides (list[str], optional) – A list of overrides in “dotlist format”, e.g. [“model.num_layers=5”, “optim.lr=1e-3”, “something.sizes=[1,2,3]”]. Useful in combination with argparse.REMAINDER to provide CLI config setting.

Raises:

ValueError – If an unknown format is specified.

Returns:

An instance of the given dataclass with values taken from the text document.

Return type:

TDataclass

haven.load_pytree(cls: type[TDataclass], pytree: dict[str, Any]) → TDataclass[source]

Decode a pytree into an instance of the given dataclass.

Parameters:

  • cls (type[TDataclass]) – Dataclass to decode.

  • pytree (Pytree) – A tree of dicts and basic python objects matching the structure of cls.

Returns:

an instance of cls with values given by pytree.

Return type:

TDataclass

haven.plugin(discover_packages_path: str, attr: str, key_field: str = 'name', default_factory: Callable[[], T] | str | None = None)[source]

Discover choices as all modules in a package namespace automatically.

Similar to the choices() function, but it doesn’t require explicitly specifying all available choices upfront. Instead, all submodules of the given package are discovered at decoding time as available choices.

Parameters:

  • discover_packages_path (str) – the namespace in which to discover packages

  • attr (str) – the attribute expected in each module to use as the choice value

  • key_field (str, optional) – The field use to determine the choice. Defaults to “name”. Same function as in choice()

  • default_factory (Callable[[], T] | str | None, optional) – Defaults to None.

haven.update(dc: TDataclass, overrides: dict[str, Any]) → TDataclass[source]

Update a dataclass given overrides as a Pytree.

Returns a copy and does not modify the original dataclass.

Example

@dataclass
Config:
    val: a = 5
    val2: b = 6

cfg = haven.load_pytree(Config, {"a": 10})
cfg = haven.update(cfg, {"b": 10})

assert cfg.a == 10 and cf.b == 10
Parameters:

  • dc (TDataclass) – Dataclass instance to update

  • overrides (Pytree) – Overrides as a pytree

Returns:

A new dataclass with overrides applied

Return type:

TDataclass

haven.update_from_dotlist(dc: TDataclass, dotlist: list[str]) → TDataclass[source]

Update a dataclass instance with the overrides specified in the dotlist.

Dotlists are lists of key=val strings. The keys can use dot syntax to reference fields deeper in the config tree. The values are parsed as yaml is. Example:

This functionality is useful for providing command-line overrides. This function does not modify the original instance but instead returns a new copy.

Parameters:

  • dc (TDataclass) – Dataclass instance to update.

  • dotlist (list[str]) – List of keyvalue strings.

Returns

TDataclass: the updated dataclass, as a copy.