hydra_zen.just#
- hydra_zen.just(obj, *, zen_convert=None, hydra_recursive=None, hydra_convert=None, zen_dataclass=None)[source]#
just(obj)
returns a config that, when instantiated, just returnsobj
.I.e.,
instantiate(just(obj)) == obj
just
is designed to be idempotent. I.e.,just(obj) == just(just(obj))
- Parameters:
- objCallable[…, Any] | HydraSupportedPrimitive | ZenSupportedPrimitive
A type (e.g. a class-object), function-object, or a value that is either supported by Hydra or has auto-config support via hydra-zen.
- 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):
- hydra_recursiveOptional[bool], optional (default=True)
If
True
, then Hydra will recursively instantiate all other hydra-config objects nested within this config [2].If
None
, the_recursive_
attribute is not set on the resulting config.- hydra_convertOptional[Literal[“none”, “partial”, “all”, “object”]], optional (default=”none”)
Determines how Hydra treats the non-primitive, omegaconf-specific objects during instantiateion [3].
"none"
: No conversion occurs; omegaconf containers are passed through (Default)"partial"
:DictConfig
andListConfig
objects converted todict
andlist
, respectively. Structured configs and their fields are passed without conversion."all"
: All passed objects are converted to dicts, lists, and primitives, without a trace of OmegaConf containers."object"
: Passed objects are converted to dict and list. Structured Configs are converted to instances of the backing dataclass / attr class.
If
None
, the_convert_
attribute is not set on the resulting config.- zen_dataclassOptional[DataclassOptions]
A dictionary that can specify any option that is supported by
dataclasses.make_dataclass()
other thanfields
. The default value forunsafe_hash
isTrue
.These options are only relevant when the input to
just
is a dataclass instance. Otherwise,just
does not utilize these options when auto-generating configs.Additionally, the
module
field can be specified to enable pickle compatibility. Seehydra_zen.typing.DataclassOptions
for details.
- Returns:
- outHydraSupportedPrimitive | Builds[Type[obj]]
out
isobj
unchanged ifobj
is supported natively by Hydra, otherwiseout
is a dynamically-generated dataclass type or instance.
- Raises:
- hydra_zen.errors.HydraZenUnsupportedPrimitiveError
See also
builds
Create a targeted structured config designed to “build” a particular object.
make_config
Creates a general config with customized field names, default values, and annotations.
Notes
Here, a “config” is a dynamically-generated dataclass type that is designed to be compatible with Hydra [1].
The configs produced by
just(<type_or_func>)
introduce an explicit dependency on hydra-zen. I.e. hydra-zen must be installed in order to instantiate any config that usedjust
.References
Examples
Basic usage
>>> from hydra_zen import just, instantiate, to_yaml
just
, called on a value of a type that is natively supported by Hydra, will return that value unchanged:>>> just(1) 1 >>> just({"a": False}) {"a": False}
just
can be used to create a config that will simply import a class-object or function when the config is instantiated by Hydra.>>> class A: pass >>> def my_func(x: int): pass
>>> instantiate(just(A)) is A True >>> instantiate(just(my_func)) is my_func True
just
dynamically generates dataclass types, a.k.a structured configs, to describeobj
>>> just(A) Just_A(_target_='hydra_zen.funcs.get_obj', path='__main__.A') >>> just(my_func) Just_my_func(_target_='hydra_zen.funcs.get_obj', path='__main__.my_func')
Auto-config support
Calling
just
on a value of a type that has special support from hydra-zen will return a structured config instance that, when instantiated by Hydra, returns that value.>>> just(1+2j) ConfigComplex(real=1.0, imag=2.0, _target_='builtins.complex') >>> instantiate(just(1+2j)) (1+2j)
>>> just({1, 2, 3}) Builds_set(_target_='builtins.set', _args_=((1, 2, 3),)) >>> instantiate(just({1, 2, 3})) {1, 2, 3}
By default,
just
will convert a dataclass instance to a corresponding targeted config. This behavior can be modified via zen-convert settings.>>> from dataclasses import dataclass >>> @dataclass ... class B: ... x: complex >>> >>> instantiate(just(B)) is B True >>> instantiate(just(B(2+3j))) == B(2+3j) True
just
operates recursively within sequences, mappings, and dataclass fields.Auto-Application of just
Both
builds
andmake_config
will automatically (and recursively) applyjust
to all configured values. E.g. in the following examplejust
will be applied to both the complex-valued the list and tosum
.>>> from hydra_zen import make_config >>> Conf2 = make_config(data=[1+2j, 2+3j], reduction_fn=sum)
>>> print(to_yaml(Conf2)) data: - real: 1.0 imag: 2.0 _target_: builtins.complex - real: 2.0 imag: 3.0 _target_: builtins.complex reduction_fn: _target_: hydra_zen.funcs.get_obj path: builtins.sum
>>> conf = instantiate(Conf2) >>> conf.reduction_fn(conf.data) (3+5j)