hydra_zen.make_config#
- hydra_zen.make_config(*fields_as_args, hydra_recursive=None, hydra_convert=None, hydra_defaults=None, zen_dataclass=None, bases=(), zen_convert=None, **fields_as_kwargs)[source]#
Returns a config with user-defined field names and, optionally, associated default values and/or type annotations.
Unlike
builds
,make_config
is not used to configure a particular target object; rather, it can be used to create more general configs [1].- Parameters:
- *fields_as_argsstr | ZenField
The names of the fields to be be included in the config. Or,
ZenField
instances, each of which details the name and their default value and/or the type annotation of a given field.- **fields_as_kwargsSupportedPrimitive | ZenField
Like
fields_as_args
, but field-name/default-value pairs are specified as keyword arguments.ZenField
can also be used here to express a field’s type-annotation and/or its default value.Named parameters of the forms
hydra_xx
,zen_xx
, and_zen_xx
are reserved to ensure future-compatibility, and cannot be specified by the user.- zen_convertOptional[ZenConvert]
A dictionary that modifies hydra-zen’s value and type conversion behavior. Consists of the following optional key-value pairs (hydra_zen.typing.ZenConvert):
- basesTuple[Type[DataClass], …], optional (default=())
Base classes that the resulting config class will inherit from.
- hydra_recursiveOptional[bool], optional (default=True)
If
True
, then Hydra will recursively instantiate all other hydra-config objects nested within this dataclass [2].If
None
, the_recursive_
attribute is not set on the resulting config.- hydra_convertOptional[Literal[“none”, “partial”, “all”, “object”]], optional (default=”none”)
Determines how Hydra handles the non-primitive objects passed to configuration [3].
"none"
: Passed objects are DictConfig and ListConfig, default"partial"
: Passed objects are converted to dict and list, with the exception of Structured Configs (and their fields)."all"
: Passed objects are dicts, lists and primitives without a trace of OmegaConf containers"object"
: Passed objects are converted to dict and list. Structured Configs are converted to instances of the backing dataclass / attr class.
If
None
, the_convert_
attribute is not set on the resulting config.- hydra_defaultsNone | list[str | dict[str, str | list[str] | None ]], optional (default = None)
A list in an input config that instructs Hydra how to build the output config [7] [8]. Each input config can have a Defaults List as a top level element. The Defaults List itself is not a part of output config.
- zen_dataclassOptional[DataclassOptions]
A dictionary can specify any option that is supported by
dataclasses.make_dataclass()
other thanfields
.Additionally, a
'module': <str>
entry can be specified to enable pickle compatibility. Seehydra_zen.typing.DataclassOptions
for details.- frozenbool, optional (default=False)
Deprecated since version 0.9.0:
frozen
will be removed in hydra-zen 0.10.0. It is replaced byzen_dataclass={'frozen': <bool>}
.If
True
, the resulting config class will produce ‘frozen’ (i.e. immutable) instances. I.e. setting/deleting an attribute of an instance of the config will raisedataclasses.FrozenInstanceError
at runtime.- config_namestr, optional (default=”Config”)
Deprecated since version 0.9.0:
config_name
will be removed in hydra-zen 0.10.0. It is replaced byzen_dataclass={'cls_name': <str>}
.The class name of the resulting config class.
- Returns:
- ConfigType[DataClass]
The resulting config class; a dataclass that possess the user-specified fields.
- Raises:
- hydra_zen.errors.HydraZenUnsupportedPrimitiveError
The provided configured value cannot be serialized by Hydra, nor does hydra-zen provide specialized support for it. See Configuration-Value Types Supported by Hydra and hydra-zen for more details.
See also
Notes
The resulting “config” is a dataclass-object [4] with Hydra-specific attributes attached to it, along with the attributes specified via
fields_as_args
andfields_as_kwargs
. Unlike std-lib dataclasses, the default value for unsafe_hash is True.Any field specified without a type-annotation is automatically annotated with
typing.Any
. Hydra only supports a narrow subset of types [5];make_config
will automatically ‘broaden’ any user-specified annotations so that they are compatible with Hydra.make_config
will automatically manipulate certain types of default values to ensure that they can be utilized in the resulting config and by Hydra:Mutable default values will automatically be packaged in a default factory function [6]
A default value that is a class-object or function-object will automatically be wrapped by
just
, to ensure that the resulting config is serializable by Hydra.
For finer-grain control over how type annotations and default values are managed, consider using
dataclasses.make_dataclass()
.For details of the annotation
SupportedPrimitive
, see Configuration-Value Types Supported by Hydra and hydra-zen.References
Examples
>>> from hydra_zen import make_config, to_yaml >>> def pp(x): ... return print(to_yaml(x)) # pretty-print config as yaml
Basic Usage
Let’s create a bare-bones config with two fields, named ‘a’ and ‘b’.
>>> Conf1 = make_config("a", "b") # sig: `Conf(a: Any, b: Any)` >>> pp(Conf1) a: ??? b: ???
Now we’ll configure these fields with particular values:
>>> conf1 = Conf1(1, "hi") >>> pp(conf1) a: 1 b: hi >>> conf1.a 1 >>> conf1.b 'hi'
We can also specify fields via keyword args; this is especially convenient for providing associated default values.
>>> Conf2 = make_config("unit", data=[-10, -20]) >>> pp(Conf2) unit: ??? data: - -10 - -20
Configurations can be nested
>>> Conf3 = make_config(c1=Conf1(a=1, b=2), c2=Conf2) >>> pp(Conf3) c1: a: 1 b: 2 c2: unit: ??? data: - -10 - -20 >>> Conf3().c1.a 1
Configurations can be composed via inheritance
>>> ConfInherit = make_config(c=2, bases=(Conf2, Conf1)) >>> pp(ConfInherit) a: ??? b: ??? unit: ??? data: - -10 - -20 c: 2
>>> issubclass(ConfInherit, Conf1) and issubclass(ConfInherit, Conf2) # type: ignore True
Support for Additional Types
Types like
complex
andpathlib.Path
are automatically supported by hydra-zen.>>> ConfWithComplex = make_config(a=1+2j) >>> pp(ConfWithComplex) a: real: 1.0 imag: 2.0 _target_: builtins.complex
See Auto-Config Support for Additional Types via hydra-zen for a complete list of supported types.
Using ZenField to Provide Type Information
The
ZenField
class can be used to include a type-annotation in association with a field.Providing type annotations is optional, but doing so enables Hydra to perform checks at runtime to ensure that a configured value matches its associated type [4].
>>> pp(ProfileConf(username="piro", age=False)) # age should be an integer <ValidationError: Value 'False' could not be converted to Integer>
These default values can be provided alongside type annotations
>>> C = make_config(age=zf(int, 0)) # signature: C(age: int = 0)
ZenField
can also be used to specifyfields_as_args
; here, field names must be specified as well.See Runtime Data Validation for more general data validation capabilities via hydra-zen.