hydra_config.config
===================

.. py:module:: hydra_config.config

.. autoapi-nested-parse::

   This module provides a base class for working with Hydra configs.



Classes
-------

.. autoapisummary::

   hydra_config.config.HydraContainerConfig


Functions
---------

.. autoapisummary::

   hydra_config.config.config_wrapper


Module Contents
---------------

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