Terminology
This page describes some common concepts in Hydra, most of which are covered in greater details throughout the documentation. Examples of many of the following concepts are in the Examples section.
Input Configsβ
Input configs are building blocks used to construct the Output Config consumed by the application. They can be grouped by placing them in Config Groups.
Config filesβ
Config files are form of input configs in YAML format. They can exist in the file system or in a Python module.
user:
name: James Bond
age: 7
Structured Configβ
This term has two common meanings:
- A class decorated with @dataclass or @attr.s, or an instance of such a class which is intended to be used as config.
- A Config object initialized from a class or object as defined in 1. Structured Configs provide additional type information that enables static and runtime type checking.
The two primary patterns for using Structured Configs are:
- As an Input Config.
- As a schema validating Config Files and command line arguments.
@dataclass
class User:
name: str
age: int
Other configsβ
Primary Config: The input config named in @hydra.main() or in the Compose API.
Output Config: A config composed from the Input Configs and Overrides by @hydra.main(), or the Compose API.
Overridesβ
Overrides are strings that can be used to manipulate the config composition process. This includes updating, adding and deleting config values and Defaults List options.
Overrides can be used in the command line and in the Compose API.
In the examples below, key=value
is an override:
$ python my_app.py key=value
cfg = compose(config_name,
overrides=["key=value"])
Defaults Listβ
A list in an Input Config that instructs Hydra how compose the config.
defaults:
- db: mysql # An overridable defaults list entry
- schema/school # A non-overridable defaults list entry
Config Groupβ
A Config Group is directory in the Config Search Path that contains Input Configs. Config Groups can be nested, and in that case the path elements are separated by a forward slash ('/') regardless of the operating system.
Config Group Optionβ
An Input Config in a Config Group. When used in a Defaults List, a Config Group Option can be a single Input Config, or a list of Input Configs from the same Config Group.
Packageβ
A Package is the path to node in a config. By default, the Package of a Config Group Option is derived from the Config Group. e.g: Configs in mi6/agent will have the package mi6.agent by default.
The Package Directive specifies the root Package of a Config File. It can appear at the top of YAML config file.
Example of Core Conceptsβ
defaults:
- mi6/agent: james_bond
# @package bond.james
codename: '007'
bond:
james:
codename: '007'
- Input Configs: config.yaml, mi6/agent/james_bond.yaml
- Config Group: mi6/agent
- Config Group Option: james_bond
- Packages: <empty>, mi6, mi6.agent, mi6.agent.codename
- Package directive: # @package bond.james, overriding the default Package for the containing Input Config
Config Search Pathβ
The Config Search Path is a list of paths that are searched in order to find configs. It is similar to the Python PYTHONPATH.
Pluginsβ
Plugins extend Hydra's capabilities. Hydra has several plugin types, for examples Launcher and Sweeper.