Skip to content

API reference

Compose Hydra configs and validate them with Pydantic.

Nothing here runs at import time: no resolvers, no global Hydra state, no environment changes.

TargetNotAllowed

Bases: PermissionError

A _target_ is outside the execution allowlist.

BaseConfig

Bases: BaseModel

A Pydantic model whose defaults live in a Hydra config group.

class Tokenizer(BaseConfig): ... config_group = "tokenizer" ... config_name = "simple" ... lowercase: bool = True Tokenizer.compose(overrides=["tokenizer.lowercase=false"]) # doctest: +SKIP

is_allowed(target, allow)

Exact match, or a pkg.* pattern matching everything under pkg.

target_name(target)

The dotted name Hydra would execute for a _target_ string or callable.

iter_targets(config)

Every _target_ (string or callable) in a nested config of dicts, lists, and tuples.

resolve_config_dir(config_dir)

The user config directory: the given one (which must exist), else ./conf if present.

search_path(config_dir=None, config_name=DEFAULT_CONFIG_NAME, plugins=True)

Return the primary config source and the extra search-path entries, highest priority first.

The user directory is primary when it holds <config_name>.yaml; otherwise hyfi._primary (which holds only config.yaml) is, and the user directory comes first among the extras. HyFI's own groups are always last, so group options resolve user > plugins > HyFI in both cases.

compose(overrides=(), *, config_name=DEFAULT_CONFIG_NAME, config_dir=None, plugins=True, dotenv=True)

Compose a config the way the hyfi CLI does, from code or a notebook.

dotenv loads the nearest .env (without overriding variables already set) before composing, so ${oc.env:...} interpolations can see it.

compose_group(group, name, overrides=(), **compose_kwargs)

Compose one option of a config group and return just that node.

to_dict(cfg, resolve=True)

Plain Python containers from a DictConfig, ListConfig, or Pydantic model.

instantiate(config, *args, allow=None, **kwargs)

hydra.utils.instantiate that also accepts Pydantic models and passes plain containers.

A Pydantic model as _target_ is validated by its own constructor. allow is an execution allowlist (exact targets or pkg.*): every nested _target_ must match it, and it is forwarded to Hydra's _execution_whitelist_ on Hydra 1.4+.

Workflows: an ordered list of steps, each a callable built with Hydra instantiate.

.. code-block:: yaml

# conf/workflow/demo.yaml
name: demo
steps:
  - run: mypkg.io.load_csv
    with: {path: data/in.csv}
  - run: mypkg.clean.clean      # gets the previous result as its first argument
  - run: mypkg.io.save
    with: {path: out.csv}
    pipe: true

plan(workflow, allow=None)

Resolve every step target without calling it.

ok is False when a target cannot be imported or, with allow, is outside the allowlist.

execute(workflow, on_record=None, allow=None)

Run the steps in order and return the last result and one record per step.

With pipe (the default) a step receives the previous step's result as its first positional argument when that result is not None. On failure the remaining steps are marked skipped and :class:WorkflowError carries the records. allow is the execution allowlist passed to :func:hyfi.config.instantiate.

Run the workflow node of a composed config and record a manifest.

env_replacements(raw)

Map the current value of every env var named in an oc.env: reference to its interpolation.

redact(obj, replacements)

Replace every occurrence of a secret value in every string (keys included) of obj.

keep_env_interpolations(resolved, raw)

resolved, except leaves whose unresolved form reads ${oc.env:...} stay unresolved.

Values from the environment (often secrets) are re-read on rerun instead of being recorded.

record_config(config)

Return (resolved, recorded, replacements) for a composed or recorded config.

resolved is what runs. recorded is the config view written to manifests and printed: ${oc.env:...} leaves stay unresolved and every env value from replacements is replaced by its interpolation. project.root / project.workspace are made absolute before resolving, in both views, so values that interpolate them are absolute as well. Callers apply :func:redact with replacements to anything else they emit (names, errors).

load_workflow(config)

Validate the project and workflow nodes of a composed (or recorded) config.

run_workflow(config, *, overrides=(), config_name=None, config_dir=None, argv=(), rerun_of=None, allow=None)

Execute the workflow and write <project.root>/.hyfi/runs/<run_id>/manifest.json.

The manifest is written before the first step and again at the end, so a crash leaves a running record. Step failures are recorded, not raised; check manifest.status. allow is the execution allowlist (see :func:hyfi.config.instantiate).

Run manifests: what ran, with which resolved config, on which code, and how it went.

RunManifest

Bases: BaseModel

config_json()

Canonical JSON of the resolved config, for byte-level comparison.

git_info(cwd)

HEAD SHA and dirty flag of the repository containing cwd; None outside a repository.

Project paths, validated from the composed project node.

Project

Bases: BaseModel

runs_dir property

Where run manifests are written.

path(*parts, mkdir=False)

A path under the workspace; mkdir creates it as a directory.

Discover plugin config modules through the hyfi.plugins entry point group.

A plugin declares, in its own pyproject.toml::

[project.entry-points."hyfi.plugins"]
mypkg = "mypkg.conf"

The value is an importable package that holds Hydra config groups.

discover()

Installed plugins, sorted by name so search-path order is stable.

config_modules()

Config modules of plugins that can actually be imported.