hydra_zen.BuildsFn#
- class hydra_zen.BuildsFn[source]#
A class that can be modified to customize the behavior of
builds
,just
,kwargs_of
, andmake_config
.These functions are exposed as class methods of
BuildsFn
.To customize type-refinement support, override
_sanitized_type
.To customize auto-config support, override
_make_hydra_compatible
.To customize the ability to resolve import paths, override
_get_obj_path
.
Methods
builds
(hydra_target, /, *pos_args[, ...])builds(target, *args, **kw)
returns a Hydra-compatible config that, when instantiated, returnstarget(*args, **kw)
.just
(obj, *[, zen_convert, hydra_recursive, ...])just(obj)
returns a config that, when instantiated, just returnsobj
.kwargs_of
(_BuildsFn__hydra_target, *[, ...])Returns a config whose signature matches that of the provided target.
make_config
(*fields_as_args[, ...])Returns a config with user-defined field names and, optionally, associated default values and/or type annotations.
Notes
Adding type-checking support for a custom type:
To parameterize
BuildsFn
with, e.g., support for the custom typesMyTypeA
andMyTypeB
, use:from typing import Union from hydra_zen.typing import CustomConfigType class MyTypeA: ... class MyTypeB: ... class MyBuilds(BuildsFn[CustomConfigType[Union[MyTypeA, MyTypeB]]]): ...
Examples
Suppose you wrote the following type:
class Quaternion: def __init__( self, real: float = 0.0, i: float = 0.0, j: float = 0.0, k: float = 0.0, ): self._data = (real, i, j, k) def __repr__(self): return "Q" + repr(self._data)
and you want hydra-zen’s config-creation functions to be able to automatically know how to make configs from instances of this type. You do so by creating your own subclass of
BuildsFn
:from typing import Any from hydra_zen import BuildsFn from hydra_zen.typing import CustomConfigType, HydraSupportedType class CustomBuilds(BuildsFn[CustomConfigType[Quaternion]]): @classmethod def _make_hydra_compatible(cls, value: Any, **k) -> HydraSupportedType: if isinstance(value, Quaternion): real, i, j, k = value._data return cls.builds(Quaternion, real=real, i=i, j=j, k=k) return super()._make_hydra_compatible(value, **k)
Now you use the config-creation functions that are provided by
CustomBuilds
instead of those provided byhydra_zen
:builds = CustomBuilds.builds just = CustomBuilds.just kwargs_of = CustomBuilds.kwargs_of make_config = CustomBuilds.make_config
E.g.
- classmethod _sanitized_type(type_, *, primitive_only=False, wrap_optional=False, nested=False)[source]#
Broadens a type annotation until it is compatible with Hydra.
Override this to change how
builds
refines the type annotations of the configs that it produces.- Parameters:
- type_Any
The type being sanitized.
- primitive_only: bool, optional (default=False)
If true, only
bool
|None
|int
|float
| str` is permitted.- wrap_optional: bool, optional (default=False)
True
indicates that the resulting type should be wrapped inOptional
.- nested: bool, optional (default=False)
True
indicates that this function is processing a type within a container type.
Examples
>>> sanitized_type(int) <class 'int'>
>>> sanitized_type(frozenset) # not supported by hydra typing.Any
>>> sanitized_type(int, wrap_optional=True) typing.Union[int, NoneType]
>>> sanitized_type(List[int]) List[int]
>>> sanitized_type(List[int], primitive_only=True) Any
- classmethod _make_hydra_compatible(value, *, allow_zen_conversion=True, error_prefix='', field_name='', structured_conf_permitted=True, convert_dataclass, hydra_recursive=None, hydra_convert=None, zen_dataclass=None)[source]#
Converts
value
to Hydra-supported type or to a config whose fields are recursively supported by_make_hydra_compatible
. Otherwise raisesHydraZenUnsupportedPrimitiveError
.Override this method to add support for adding auto-config support to custom types.
Notes
- Hydra supports the following types:
bool
,None
,int
,float
,str
,ByteString
,pathlib.Path
,dataclasses.MISSING
. As well as lists, tuples, dicts, and omegaconf containers containing the above.
- classmethod _get_obj_path(target)[source]#
Used to get the
_target_
value for the resulting config.Override this to control how
builds
determines the _target_ field in the configs that it produces.
Methods
_sanitized_type
(type_, *[, primitive_only, ...])Broadens a type annotation until it is compatible with Hydra.
_make_hydra_compatible
(value, *[, ...])Converts
value
to Hydra-supported type or to a config whose fields are recursively supported by_make_hydra_compatible
._get_obj_path
(target)Used to get the
_target_
value for the resulting config.