Each of hydra-zen’s config-creation functions has a zen_dataclass parameter, which exposes the full API for affecting the resulting dataclass’ properties, as exposed by dataclasses.make_dataclass().

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

hydra_zen.typing.DataclassOptions#

class hydra_zen.typing.DataclassOptions[source]#

Specifies dataclass-creation options via builds, just et al.

Note that, unlike dataclasses.make_dataclass(), the default value for unsafe_hash is True for hydra-zen’s dataclass-generating functions. See the documentation for dataclasses.make_dataclass() for more details [1].

Options that are not supported by the local Python version will be ignored by hydra-zen’s config-creation functions.

Parameters:

cls_namestr, optional

If specified, determines the name of the returned class object. Otherwise the name is inferred by hydra-zen.

modulestr, default=’typing’

If specified, sets the __module__ attribute of the resulting dataclass.

Specifying the module string-path in which the dataclass was generated, and specifying cls_name as the symbol that references the dataclass, will enable pickle-compatibility for that dataclass. See the Examples section for clarification.

targetstr, optional (unspecified by default)

If specified, overrides the _target_ field set on the resulting dataclass.

initbool, optional (default=True)

If true (the default), a __init__() method will be generated. If the class already defines __init__(), this parameter is ignored.

reprbool, optional (default=True)

If true (the default), a __repr__() method will be generated. The generated repr string will have the class name and the name and repr of each field, in the order they are defined in the class. Fields that are marked as being excluded from the repr are not included. For example: InventoryItem(name='widget', unit_price=3.0, quantity_on_hand=10).

eqbool, optional (default=True)

If true (the default), an __eq__() method will be generated. This method compares the class as if it were a tuple of its fields, in order. Both instances in the comparison must be of the identical type.

orderbool, optional (default=False)

If true (the default is False), __lt__(), __le__(), __gt__(), and __ge__() methods will be generated. These compare the class as if it were a tuple of its fields, in order. Both instances in the comparison must be of the identical type. If order is true and eq is false, a ValueError is raised.

If the class already defines any of __lt__(), __le__(), __gt__(), or __ge__(), then TypeError is raised.

unsafe_hashbool, optional (default=False)

If False (the default), a __hash__() method is generated according to how eq and frozen are set.

If eq and frozen are both true, by default dataclass() will generate a __hash__() method for you. If eq is true and frozen is false, __hash__() ` will be set to `None, marking it unhashable. If eq is false, __hash__() will be left untouched meaning the __hash__() method of the superclass will be used (if the superclass is object, this means it will fall back to id-based hashing).

frozenbool, optional (default=False)

If true (the default is False), assigning to fields will generate an exception. This emulates read-only frozen instances.

match_argsbool, optional (default=True)

(New in version 3.10) If true (the default is True), the __match_args__ tuple will be created from the list of parameters to the generated __init__() method (even if __init__() is not generated, see above). If false, or if __match_args__ is already defined in the class, then __match_args__ will not be generated.

kw_onlybool, optional (default=False)

(New in version 3.10) If true (the default value is False), then all fields will be marked as keyword-only.

slotsbool, optional (default=False)

(New in version 3.10) If true (the default is False), __slots__ attribute will be generated and new class will be returned instead of the original one. If __slots__ is already defined in the class, then TypeError is raised.

weakref_slotbool, optional (default=False)

(New in version 3.11) If true (the default is False), add a slot named “__weakref__”, which is required to make an instance weakref-able. It is an error to specify weakref_slot=True without also specifying slots=True.

modulestr | None

If module is defined, the __module__ attribute of the dataclass is set to that value. By default, it is set to the module name of the caller.

Notes

This is a typed dictionary, which provides static type information (e.g. type checking and auto completion options) to tooling. Note, however, that it provides no runtime checking of its keys and values.

References

[1]

https://docs.python.org/3/library/dataclasses.html

[2]

https://docs.python.org/3/library/dataclasses.html#mutable-default-values

Examples

>>> from hydra_zen.typing import DataclassOptions as Opts
>>> from hydra_zen import builds, make_config, make_custom_builds_fn

Creating a frozen config.

>>> conf = make_config(x=1, zen_dataclass=Opts(frozen=True))()
>>> conf.x = 2
FrozenInstanceError: cannot assign to field 'x'

Creating a pickle-compatible config:

The dynamically-generated classes created by builds, make_config, and just can be made pickle-compatible by specifying the name of the symbol that it is assigned to and the module in which it was defined.

# contents of mylib/foo.py
from pickle import dumps, loads
from hydra_zen import builds

DictConf = builds(dict,
                  zen_dataclass={'module': 'mylib.foo',
                                 'cls_name': 'DictConf'})

assert DictConf is loads(dumps(DictConf))

Using namespace to add a method to a config instance.

>>> conf = make_config(
...     x=100,
...     zen_dataclass=Opts(
...         namespace=dict(add_x=lambda self, y: self.x + y),
...     ),
... )()
>>> conf.add_x(2)
102

Dataclasse objects created by hydra-zen’s config-creation functions will be created with unsafe_hash=True by default. This is in contrast with the default behavior of dataclasses.dataclass(). This is to help ensure smooth compatibility through Python 3.11, which changed the mutability checking rules for dataclasses [2].

>>> from dataclasses import make_dataclass
>>> DataClass = make_dataclass(fields=[], cls_name="A")
>>> DataClass.__hash__
None

>>> Conf = make_config(x=2)
>>> Conf.__hash__
<function types.__create_fn__.<locals>.__hash__(self)>

>>> UnHashConf = make_config(x=2, zen_dataclass=Opts(unsafe_hash=False))
>>> UnHashConf.__hash__
None