hydra_zen.BuildsFn#

class hydra_zen.BuildsFn[source]#

A class that can be modified to customize the behavior of builds, just, kwargs_of, and make_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.

Notes

Adding type-checking support for a custom type:

To parameterize BuildsFn with, e.g., support for the custom types MyTypeA and MyTypeB, 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 by hydra_zen:

builds = CustomBuilds.builds
just = CustomBuilds.just
kwargs_of = CustomBuilds.kwargs_of
make_config = CustomBuilds.make_config

E.g.

>>> from hydra_zen import to_yaml
>>> Config = just([Quaternion(1.0), Quaternion(0.0, -12.0)])
>>> print(to_yaml(Config))
- _target_: __main__.Quaternion
  real: 1.0
  i: 0.0
  j: 0.0
  k: 0.0
- _target_: __main__.Quaternion
  real: 0.0
  i: -12.0
  j: 0.0
  k: 0.0

Methods

`builds`(hydra_target, /, *pos_args[, ...])	`builds(target, args, kw)` returns a Hydra-compatible config that, when instantiated, returns `target(args, **kw)`.
`just`(obj, *[, zen_convert, hydra_recursive, ...])	`just(obj)` returns a config that, when instantiated, just returns `obj`.
`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.

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 in Optional.
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

>>> sanitized_type(Dict[str, frozenset])
Dict[str, 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 raises HydraZenUnsupportedPrimitiveError.

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.