hydra-qol

Quality-of-life helpers for Hydra: register dataclass-based configs in one call, prepare composed configs for logging, and check that all YAML config files in a project are valid without running any experiments.

Installation

uv add hydra-qol
# or
pip install hydra-qol

Requires Python 3.11+, hydra-core 1.4+ (a pre-release at the time of writing) and omegaconf 2.4+.

What's in the box

Quick start

# main.py
import hydra
from omegaconf import DictConfig, OmegaConf
from hydra_qol import prepare_for_logging, register_hydra_config

from my_project.config import CONFIG_GROUPS, Config


@hydra.main(config_path="configs", config_name="main_config")
def main(hydra_config: DictConfig) -> None:
    config = OmegaConf.to_object(hydra_config)
    assert isinstance(config, Config)
    config_for_logging = prepare_for_logging(hydra_config)
    ...


if __name__ == "__main__":
    register_hydra_config(Config, CONFIG_GROUPS, schema_name="main_config")
    main()

# check_configs.py
import sys

from hydra_qol import check_configs

from my_project.config import CONFIG_GROUPS, Config

if __name__ == "__main__":
    sys.exit(
        check_configs(
            Config, CONFIG_GROUPS, schema_name="main_config", config_dir="configs"
        )
    )

Config-group options are checked one at a time on top of the schema, so the schema's defaults list has to select an option for every config group. If the defaults list lives in a YAML file instead (i.e. @hydra.main(config_name="default_config") together with register_hydra_config(..., schema_name="base_config")), pass that file as well: check_configs(..., schema_name="base_config", config_with_defaults="default_config", ...).

$ python check_configs.py
OK    dm/celeba_male_smiling.yaml (dm=celeba_male_smiling)
OK    good_run.yaml (--config-name good_run)
FAIL  model/single_linear_layer.yaml (model=single_linear_layer)
Traceback (most recent call last):
  ...
hydra.errors.ConfigCompositionException: Could not override 'model.num_hiden'.

1 config file(s) are invalid:
  - model/single_linear_layer.yaml (model=single_linear_layer)

A complete, annotated example project that uses these functions can be found at wearepal/hydra-example. The full documentation lives in docs/ and is built with Sphinx:

uv sync --group docs
uv run sphinx-build -b html docs docs/_build/html

Development

uv sync                # installs test, lint and docs dependencies
uv run pytest
uv run ruff check && uv run ruff format --check
uv run ty check

Acknowledgements

register_hydra_config and prepare_for_logging originate from ranzen (Apache 2.0).

License

Apache 2.0, see LICENSE.