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.

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.

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