hydra_zen.make_custom_builds_fn#

hydra_zen.make_custom_builds_fn(*, zen_partial=None, populate_full_signature=False, zen_exclude=frozenset({}), zen_wrappers=(), zen_meta=None, hydra_recursive=None, hydra_convert=None, zen_dataclass=None, frozen=False, zen_convert=None, builds_fn=<class 'hydra_zen.structured_configs._implementations.DefaultBuilds'>)[source]#

Returns the builds function, but with customized default values.

E.g. make_custom_builds_fn(hydra_convert='all') will return a version of the builds function where the default value for hydra_convert is 'all' instead of None.

Parameters:

zen_partialbool, optional (default=False)

Specifies a new the default value for builds(..., zen_partial=<..>)

Specifies a new the default value for builds(..., zen_wrappers=<..>)

zen_metaOptional[Mapping[str, Any]]

Specifies a new the default value for builds(..., zen_meta=<..>)

populate_full_signaturebool, optional (default=False)

Specifies a new the default value for builds(..., populate_full_signature=<..>)

zen_excludeCollection[str] | Callable[[str], bool], optional (default=[])

Specifies parameter names, or a function for checking names, to exclude those parameters from the config-creation process.

Note that inherited fields cannot be excluded.

zen_convertOptional[ZenConvert]

A dictionary that modifies hydra-zen’s value and type conversion behavior. Consists of the following optional key-value pairs (hydra_zen.typing.ZenConvert):

dataclassbool (default=True):
If True any dataclass type/instance without a _target_ field is automatically converted to a targeted config that will instantiate to that type/instance. Otherwise the dataclass type/instance will be passed through as-is.

zen_dataclassOptional[DataclassOptions]

A dictionary can specify any option that is supported by dataclasses.make_dataclass() other than fields. The default value for unsafe_hash is True.

Additionally, the module field can be specified to enable pickle compatibility. See hydra_zen.typing.DataclassOptions for details.

hydra_recursiveOptional[bool], optional (default=True)

Specifies a new the default value for builds(..., hydra_recursive=<..>)

hydra_convertOptional[Literal[“none”, “partial”, “all”, “object”]], optional (default=”none”)

Specifies a new the default value for builds(..., hydra_convert=<..>)

frozenbool, optional (default=False)

Deprecated since version 0.9.0: frozen will be removed in hydra-zen 0.10.0. It is replaced by zen_dataclass={'frozen': <bool>}.

Specifies a new the default value for builds(..., frozen=<..>)

builds_fn: BuildsFn[T]

The builds-function whose defaults are modified.

Returns:

custom_builds[T]: The function builds, but with customized default values.

See also

builds: Create a targeted structured config designed to “build” a particular object.

Examples

>>> from hydra_zen import builds, make_custom_builds_fn, instantiate

Basic usage

The following will create a builds function whose default value for zen_partial has been set to True.

>>> pbuilds = make_custom_builds_fn(zen_partial=True)

I.e. using pbuilds(...) is equivalent to using builds(..., zen_partial=True).

>>> instantiate(pbuilds(int))  # calls `functools.partial(int)`
functools.partial(<class 'int'>)

You can still specify zen_partial on a per-case basis with pbuilds.

>>> instantiate(pbuilds(int, zen_partial=False))  # calls `int()`
0

Adding data validation to configs

Suppose that we want to enable runtime type-checking - using beartype - whenever our configs are being instantiated; then the following settings for builds would be handy.

>>> # Note: beartype must be installed to use this feature
>>> from hydra_zen.third_party.beartype import validates_with_beartype
>>> build_a_bear = make_custom_builds_fn(
...     populate_full_signature=True,
...     hydra_convert="all",
...     zen_wrappers=validates_with_beartype,
... )

Now all configs produced via build_a_bear will include type-checking during instantiation.

>>> from typing_extensions import Literal
>>> def f(x: Literal["a", "b"]): return x

>>> Conf = build_a_bear(f)  # a conf that includes `validates_with_beartype`

>>> instantiate(Conf, x="a")  # satisfies annotation: Literal["a", "b"]
"a"

>>> instantiate(Conf, x="c")  # violates annotation: Literal["a", "b"]
<Validation error: "c" is not "a" or "b">