hydra_config

hydra_config is a package that provides utilities to simplify the usage of Hydra in your project.

Submodules

• hydra_config.cli
• hydra_config.config
• hydra_config.resolvers
• hydra_config.utils

Classes

HydraContainerConfig	Base dataclass which provides additional methods for working with configs.
HydraFlagWrapperMeta	This is a simple metaclass to allow for the use of the | operator to combine

Functions

register_cli([func])	Register a CLI command.
run_cli(func, /, **kwargs)	Run a CLI command.
config_wrapper([cls])	This is a wrapper of the dataclass decorator that adds the class to the hydra
register_new_resolver(name[, replace])	Register a new resolver with OmegaConf.
builds(func_or_cls, /, *[, auto_detect, group])	Build a Hydra Zen configuration for a given function or class.
run_hydra([main_fn, parser, config_path, config_name, ...])	This function is the main entry point for the hydra application.
store(func_or_cls, /, *[, name, group, _max_recursion])	Store a function or class in Hydra Zen's store with a specific group and name.

Package Contents

register_cli(func=None, /, **kwargs)

Register a CLI command.

Example

from typing import Any

from hydra_config.cli import register_cli, run_cli


class Config:
    def __init__(self, param: Any):
        self.param = param


class ConfigInt(Config):
    def __init__(self, param: int):
        super().__init__(param)


class ConfigFloat(Config):
    def __init__(self, param: float):
        super().__init__(param)


class System:
    def __init__(self, config: Config):
        self.config = config


@register_cli
def standalone_cli(system: System, x: int, flag: bool = False):
    print(
        "System Config Param:",
        system.config.param,
        type(system.config),
        type(system.config.param),
    )
    print("X:", x, type(x))
    print("Flag:", flag, type(flag))


if __name__ == "__main__":
    run_cli(standalone_cli)

Parameters:

func (Callable | None) – The CLI function to register. If None, returns a decorator.

Returns:

Callable – The registered CLI function or a decorator if func is None.

run_cli(func, /, **kwargs)

Run a CLI command.

Parameters:

func (Callable) – The CLI command to run.

class HydraContainerConfig

Base dataclass which provides additional methods for working with configs.

config: omegaconf.DictConfig | None

The original, uninstantiated config. This is maintained within each nested instantiated config to allow for proper serialization and deserialization, as well as printing the config as a yaml string.

custom: Dict[str, Any] | None

Custom data to use. This is useful for code-specific logic (i.e. not in yaml files) where you want to store data that is not necessarily defined in the config.

classmethod instantiate(config, *, _convert_='object', **kwargs)

Instantiate the config into an object.

Parameters:

config (DictConfig | ListConfig) – The config to instantiate.

Keyword Arguments:

• _convert_ (str) – The conversion method to use. Defaults to “object”, meaning all structured configs will be converted to their dataclass equivalent.

• **kwargs – Additional keyword arguments to pass to the instantiation method.

classmethod compose(config_dir, config_name, *, overrides=[], return_hydra_config=False, **kwargs)

Compose a config using the Hydra compose API. This will return the config as a HydraContainerConfig instance.

Parameters:

• config_dir (Path | str) – The path to the config directory.

• config_name (str) – The name of the config file.

Keyword Arguments:

• overrides (List[str]) – The overrides to use when composing the config.

• return_hydra_config (bool) – Whether to return the HydraConfig object.

• **kwargs – Additional keyword arguments to pass to the instantiation method.

classmethod load(*args, instantiate=True, pattern=None, **instantiate_kwargs)

Wrapper around OmegaConf.load to instantiate the config.

Keyword Arguments:

• instantiate (bool) – Whether to instantiate the config into an object.

• pattern (Optional[str]) – The specific pattern to select from the loaded config.

• **instantiate_kwargs – Additional keyword arguments to pass to the instantiation method.

classmethod create(*args, instantiate=True, instantiate_kwargs={}, **kwargs)

Wrapper around OmegaConf.create to instantiate the config.

Keyword Arguments:

• instantiate (bool) – Whether to instantiate the config into an object.

• **instantiate_kwargs – Additional keyword arguments to pass to the instantiation method.

merge_with(*others)

Wrapper around OmegaConf.merge to merge the config with another config.

Parameters:

others (DictConfig | ListConfig | Dict | List) – The other config(s) to merge with.

copy()

Wrapper around the copy method to return a new instance of this class.

Note

This method will perform a deepcopy, meaning the __getstate__() and __setstate__() methods will be called. This is fairly slow since the object is pickled and unpickled.

save(path, *, header=None)

Saves the config to a yaml file.

Parameters:

path (Path | str) – The path to save the config to.

Keyword Arguments:

header (str) – The header to add to the top of the yaml file.

to_yaml()

Wrapper around OmegaConf.to_yaml to convert the config to a yaml string. Adds some custom representers.

This uses the stored config attribute to convert to yaml. If the config is None, this will return the default string representation of the object.

__getstate__()

This is used to pickle the object. We’ll return the config as the state.

__setstate__(state)

This is used to unpickle the object. We’ll set the config from the state.

__str__()

Convert the config to a yaml string.

config_wrapper(cls=None, /, **kwargs)

This is a wrapper of the dataclass decorator that adds the class to the hydra store.

The hydra store is used to construct structured configs from the yaml files.

We’ll also do some preprocessing of the dataclass fields such that all type hints are supported by hydra. Hydra only supports a certain subset of types, so we’ll convert the types to supported types using the _sanitized_type method from hydra_zen.

Keyword Arguments:

kw –

The kwargs to pass to the dataclass decorator. The following defaults are set:

• repr: False

• eq: False

• slots: True

• kw_only: True

register_new_resolver(name, replace=True, **kwargs)

Register a new resolver with OmegaConf.

Parameters:

• name (str) – The name of the resolver.

• replace (bool) – Whether to replace the resolver if it already exists.

• **kwargs – Additional keyword arguments to pass to OmegaConf.register_new_resolver.

class HydraFlagWrapperMeta

Bases: enum.EnumMeta

This is a simple metaclass to allow for the use of the | operator to combine flags. This means you can simply put flag1 | flag2 in the yaml file and it will be combined into a single flag.

The following forms are supported and any combination thereof:

• flag1 | flag2 | flag3 | ...

• flag1|flag2|flag3|...

• flag1

__getitem__(item)

This method allows for the use of the | operator to combine flags. This means you can simply put flag1 | flag2 in the yaml file and it will be combined into a single flag.

builds(func_or_cls, /, *, auto_detect=True, group='', **kwargs)

Build a Hydra Zen configuration for a given function or class.

Parameters:

• func_or_cls (Callable[…, Any] | Type[Any]) – The function or class to build a configuration for.

• auto_detect (bool) – Automatically detect and store parameter types. Defaults to True.

• group (str) – The group name for the configuration. Defaults to an empty string.

• **kwargs (Any) – Additional arguments passed to zen.builds.

Returns:

Any – A dataclass representing the Hydra Zen configuration.

run_hydra(main_fn=lambda *_, **__: ..., /, *, parser=argparse.ArgumentParser(), config_path=Path.cwd() / 'configs', config_name='base', instantiate=True, **kwargs)

This function is the main entry point for the hydra application.

The benefits of using this setup rather than the compose API is that we can use the sweeper and launcher APIs, which are not available in the compose API.

An additional --hydra-help flag is added to the parser to print the hydra help message when passed.

Parameters:

main_fn (Callable[[Concatenate[[HydraContainerConfig], …], None]) – The main function to be called after the hydra configuration is parsed. It should take the config as an argument and kwargs which correspond to the argument parser returns. We don’t return the config directly because hydra allows multi-run sweeps and it doesn’t make sense to return multiple configs in this case.

Example:

def main(config: HydraContainerConfig, *, verbose: int):
    pass

parser = argparse.ArgumentParser()
parser.add_argument("--verbose", type=int, default=0)

run_hydra(main_fn=main, parser=parser)

Keyword Arguments:

• parser (argparse.ArgumentParser) – The parser to use for the hydra application. If None, a new parser will be created.

• config_path (Path | str) – The path to the config directory. This should be the absolute path to the directory containing the config files. By default, this is set to the current working directory.

• config_name (str) – The name of the config file to use. This should be the name of the file without the extension. By default, this is set to “base”.

• instantiate (bool) – Whether to instantiate the config. If False, create will be used.

• kwargs – Additional keyword arguments to pass to the instantiate function.

store(func_or_cls, /, *, name='', group='', _max_recursion=10, **kwargs)

Store a function or class in Hydra Zen’s store with a specific group and name.

Parameters:

• func_or_cls (Callable[…, Any] | Type[Any]) – The function or class to store.

• name (str) – The name under which to store the function or class. Defaults to an empty string.

• group (str) – The group name to associate with the store entry. Defaults to an empty string.

• **kwargs (Any) – Additional arguments passed to hydra_store.