Each of hydra-zen’s config-creation functions has a zen_config parameter, which can be passed a dictionary to modify the function’s value and type conversion behaviors. hydra_zen.typing.ZenConfig is a typing.TypedDict that can be used as a convenience function to view and override these options.

The following documentation details the available zen-convert options and shows example use cases.

hydra_zen.typing.ZenConvert

class hydra_zen.typing.ZenConvert

A TypedDict that provides a type-checked interface for specifying zen-convert options that configure the hydra-zen config-creation functions (e.g., builds, just, and make_config).

Note that, at runtime, ZenConvert is simply a dictionary with type-annotations. There is no enforced runtime validation of its keys and values.

Parameters:

flat_target: bool

If True (default), builds(builds(f)) is equivalent to builds(f). I.e. the second builds call will use the _target_ field of its input, if it exists.

dataclassbool

If True (default) any dataclass type/instance without a _target_ field is automatically converted to a targeted config that will instantiate to that type/ instance. Otherwise the dataclass type/instance will be passed through as-is.

Note that this only works with statically-defined dataclass types, whereas make_config() and dataclasses.make_dataclass() dynamically generate dataclass types. Additionally, this feature is not compatible with a dataclass instance whose type possesses an InitVar field.

Examples

>>> from hydra_zen.typing import ZenConvert as zc
>>> zc()
{}
>>> zc(dataclass=True)
{"dataclass": True}
>>> # static type-checker will raise, but runtime will not
>>> zc(apple=1)  # type: ignore
{"apple": 1}

Configuring dataclass auto-config behaviors

>>> from hydra_zen import instantiate as I
>>> from hydra_zen import builds, just
>>> from dataclasses import dataclass
>>> @dataclass
... class B:
...     x: int
>>> b = B(x=1)

>>> I(just(b))
B(x=1)
>>> I(just(b, zen_convert=zc(dataclass=False)))  # returns omegaconf.DictConfig
{"x": 1}

>>> I(builds(dict, y=b))
{'y': B(x=1)}
>>> I(builds(dict, y=b, zen_convert=zc(dataclass=False)))  # returns omegaconf.DictConfig
{'y': {'x': 1}}

>>> I(make_config(y=b))  # returns omegaconf.DictConfig
{'y': {'x': 1}}
>>> I(make_config(y=b, zen_convert=zc(dataclass=True), hydra_convert="all"))
{'y': B(x=1)}

Auto-config support does not work with dynamically-generated dataclass types

>>> just(make_config(z=1))
HydraZenUnsupportedPrimitiveError: ...
>>> I(just(make_config(z=1), zen_convert=zc(dataclass=False)))
{'z': 1}

A dataclass with a _target_ field will not be converted:

>>> @dataclass
... class BuildsStr:
...     _target_: str = 'builtins.str'
...
>>> BuildsStr is just(BuildsStr)
True
>>> (builds_str := BuildsStr()) is just(builds_str)
True