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 forunsafe_hash
isTrue
for hydra-zen’s dataclass-generating functions. See the documentation fordataclasses.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__()
, thenTypeError
is raised.- unsafe_hashbool, optional (default=False)
If
False
(the default), a__hash__()
method is generated according to howeq
andfrozen
are set.If
eq
andfrozen
are both true, by defaultdataclass()
will generate a__hash__()
method for you. Ifeq
is true andfrozen
is false,__hash__() ` will be set to `None
, marking it unhashable. Ifeq
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, thenTypeError
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 specifyweakref_slot=True
without also specifyingslots=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
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
, andjust
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.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 ofdataclasses.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