hydra_config ============ .. py:module:: hydra_config .. autoapi-nested-parse:: ``hydra_config`` is a package that provides utilities to simplify the usage of Hydra in your project. Submodules ---------- .. toctree:: :maxdepth: 1 /reference/api/hydra_config/cli/index /reference/api/hydra_config/config/index /reference/api/hydra_config/resolvers/index /reference/api/hydra_config/utils/index Classes ------- .. autoapisummary:: hydra_config.HydraContainerConfig hydra_config.HydraFlagWrapperMeta Functions --------- .. autoapisummary:: hydra_config.register_cli hydra_config.run_cli hydra_config.config_wrapper hydra_config.register_new_resolver hydra_config.builds hydra_config.run_hydra hydra_config.store Package Contents ---------------- .. py:function:: register_cli(func = None, /, **kwargs) Register a CLI command. .. rubric:: Example .. literalinclude:: /../examples/standalone_cli.py :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. .. py:function:: run_cli(func, /, **kwargs) Run a CLI command. :Parameters: **func** (*Callable*) -- The CLI command to run. .. py:class:: HydraContainerConfig Base dataclass which provides additional methods for working with configs. .. py:attribute:: config :type: Optional[omegaconf.DictConfig] 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. .. py:attribute:: custom :type: Optional[Dict[str, Any]] 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. .. py:method:: instantiate(config, *, _convert_ = 'object', **kwargs) :classmethod: Instantiate the config into an object. :Parameters: **config** (*DictConfig | ListConfig*) -- The config to instantiate. :keyword _convert_: The conversion method to use. Defaults to "object", meaning all structured configs will be converted to their dataclass equivalent. :kwtype _convert_: str :keyword \*\*kwargs: Additional keyword arguments to pass to the instantiation method. .. py:method:: compose(config_dir, config_name, *, overrides = [], return_hydra_config = False, **kwargs) :classmethod: 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 overrides: The overrides to use when composing the config. :kwtype overrides: List[str] :keyword return_hydra_config: Whether to return the HydraConfig object. :kwtype return_hydra_config: bool :keyword \*\*kwargs: Additional keyword arguments to pass to the instantiation method. .. py:method:: load(*args, instantiate = True, pattern = None, **instantiate_kwargs) :classmethod: Wrapper around OmegaConf.load to instantiate the config. :keyword instantiate: Whether to instantiate the config into an object. :kwtype instantiate: bool :keyword pattern: The specific pattern to select from the loaded config. :kwtype pattern: Optional[str] :keyword \*\*instantiate_kwargs: Additional keyword arguments to pass to the instantiation method. .. py:method:: create(*args, instantiate = True, instantiate_kwargs = {}, **kwargs) :classmethod: Wrapper around OmegaConf.create to instantiate the config. :keyword instantiate: Whether to instantiate the config into an object. :kwtype instantiate: bool :keyword \*\*instantiate_kwargs: Additional keyword arguments to pass to the instantiation method. .. py: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. .. py:method:: copy() Wrapper around the copy method to return a new instance of this class. .. note:: This method will perform a deepcopy, meaning the :meth:`__getstate__` and :meth:`__setstate__` methods will be called. This is fairly slow since the object is pickled and unpickled. .. py:method:: save(path, *, header = None) Saves the config to a yaml file. :Parameters: **path** (*Path | str*) -- The path to save the config to. :keyword header: The header to add to the top of the yaml file. :kwtype header: str .. py:method:: 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. .. py:method:: __getstate__() This is used to pickle the object. We'll return the config as the state. .. py:method:: __setstate__(state) This is used to unpickle the object. We'll set the config from the state. .. py:method:: __str__() Convert the config to a yaml string. .. py:function:: 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 kw: The kwargs to pass to the dataclass decorator. The following defaults are set: - repr: False - eq: False - slots: True - kw_only: True .. py:function:: 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``. .. py:class:: HydraFlagWrapperMeta Bases: :py:obj:`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`` .. py:method:: __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. .. py:function:: 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. .. py:function:: run_hydra(main_fn = lambda *_, **__: None, /, *, 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: .. code-block:: python 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 parser: The parser to use for the hydra application. If None, a new parser will be created. :kwtype parser: argparse.ArgumentParser :keyword config_path: 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. :kwtype config_path: Path | str :keyword config_name: 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". :kwtype config_name: str :keyword instantiate: Whether to instantiate the config. If False, create will be used. :kwtype instantiate: bool :keyword kwargs: Additional keyword arguments to pass to the instantiate function. .. py: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 :attr:`hydra_store`.