scaffold.hydra
==============

.. py:module:: scaffold.hydra


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/scaffold/hydra/compose/index
   /autoapi/scaffold/hydra/config_helpers/index
   /autoapi/scaffold/hydra/constants/index
   /autoapi/scaffold/hydra/custom/index
   /autoapi/scaffold/hydra/initialize/index


Functions
---------

.. autoapisummary::

   scaffold.hydra.compose
   scaffold.hydra.initialize


Package Contents
----------------

.. py:function:: compose(config_name_or_class: Union[str, scaffold.hydra.config_helpers.StructuredConfig], config_dir: Optional[str] = None, overrides: Optional[List[str]] = None, return_hydra_config: bool = False, check_missing: Optional[bool] = False, return_leaf: Optional[bool] = True) -> omegaconf.DictConfig

   Alternative for hydra.compose, which differs in the following ways:

   1. No need to call `hydra.initialize` before composing a config, since this will use `scaffold.hydra.initialize`
      internally, which uses an existing instance if available.
   2. Is able to compose a config from a `StructuredConfig` class, which does not require the user to know the path
      in the config store, where the structured config was registered.
   3. Can check for missing values right away, instead of throwing an exception when trying to access them.
   4. Can automatically return the leaf node of the given config. When calling the original
      hydra.compose("/my/grouped/config"), this results in a config with the keys config["my"]["group"][...].
      Setting return_leaf=True, scaffold.hydra.compose will automatically return the result of config["my"]["group"]
      instead of adding all group keys.

   :param config_name_or_class: Path to the config in the config store, or StructuredConfig
                                class. Passing an instance of StructuredConfig has the same effect, but will throw a warning if the instance
                                arguments are not the same as the default ones.
   :type config_name_or_class: Union[str, StructuredConfig]
   :param config_dir: Optional absolute config directory to add to the search path.
   :type config_dir: Optional[str] = None
   :param overrides: Hydra overrides. See https://hydra.cc/docs/advanced/override_grammar/basic/.
   :type overrides: List[str] = None
   :param return_hydra_config: If True, returns the hydra in the root of the config.
   :type return_hydra_config: bool = False
   :param check_missing: If True, will throw an exception if omegaconf.MISSING or '???' values
                         are present.
   :type check_missing: Optional[bool] = False
   :param return_leaf: If True, will return the leaf node of the config path inside the config
                       store, so compose("/my/grouped/config") will return only the values in the "config" node or yaml, without
                       still containing the group keys in the returned config.
   :type return_leaf: Optional[bool] = True

   :returns: Rendered DictConfig.


.. py:function:: initialize(config_dir: Optional[str] = None, job_name: Optional[str] = 'app', exists_ok: Optional[bool] = True) -> Iterator[hydra.core.global_hydra.GlobalHydra]

   Context manager, that either uses an existing hydra instance, or initializes one temporarily.

   .. deprecated::
       This helper is no longer needed in most cases. Use hydra's own ``hydra.initialize`` directly,
       or define configs with ``hydra_zen.builds()`` and ``hydra_zen.ZenStore`` which do not require
       manual initialization. This function will be removed in a future release.

   :param config_dir: Absolute directory that should be added to the search path.
   :type config_dir: Optional[str]
   :param job_name: hydra.job.name which should be set.
   :type job_name: Optional[str]
   :param exists_ok: Do not fail if hydra is already initialized and yield GlobalHydra.instance().
   :type exists_ok: Optional[bool]