The compose API can compose a config similarly to
@hydra.main() anywhere in the code.
Prior to calling compose(), you have to initialize Hydra: This can be done by using the standard
or by calling one of the initialization methods listed below.
The Compose API is useful when
@hydra.main() is not applicable.
- Inside a Jupyter notebook (Example)
- Inside a unit test (Example)
- In parts of your application that does not have access to the command line (Example)
- If you want to compose multiple configuration objects (Example with Ray)
There are 3 initialization methods:
initialize(): Initialize with a config path relative to the caller
initialize_config_module(): Initialize with config_module (absolute)
initialize_config_dir(): Initialize with a config_dir on the file system (absolute)
All 3 can be used as methods or contexts. When used as methods, they are are initializing Hydra globally and should only be called once. When used as contexts, they are initializing Hydra within the context can be used multiple times.
from hydra.experimental import compose, initializefrom omegaconf import OmegaConf if __name__ == "__main__": # context initialization with initialize(config_path="conf", job_name="test_app"): cfg = compose(config_name="config", overrides=["db=mysql", "db.user=me"]) print(OmegaConf.to_yaml(cfg)) # global initialization initialize(config_path="conf", job_name="test_app") cfg = compose(config_name="config", overrides=["db=mysql", "db.user=me"]) print(OmegaConf.to_yaml(cfg))
def compose( config_name: Optional[str] = None, overrides: List[str] = , strict: Optional[bool] = None, return_hydra_config: bool = False,) -> DictConfig: """ :param config_name: the name of the config (usually the file name without the .yaml extension) :param overrides: list of overrides for config file :param strict: optionally override the default strict mode :param return_hydra_config: True to return the hydra config node in the result :return: the composed config """
def initialize( config_path: Optional[str] = None, job_name: Optional[str] = "app", strict: Optional[bool] = None, caller_stack_depth: int = 1,) -> None: """ Initializes Hydra and add the config_path to the config search path. config_path is relative to the parent of the caller. Hydra detects the caller type automatically at runtime. Supported callers: - Python scripts - Python modules - Unit tests - Jupyter notebooks. :param config_path: path relative to the parent of the caller :param job_name: the value for hydra.job.name (By default it is automatically detected based on the caller) :param strict: (Deprecated), will be removed in the next major version :param caller_stack_depth: stack depth of the caller, defaults to 1 (direct caller). """
def initialize_config_module(config_module: str, job_name: str = "app") -> None: """ Initializes Hydra and add the config_module to the config search path. The config module must be importable (an __init__.py must exist at its top level) :param config_module: absolute module name, for example "foo.bar.conf". :param job_name: the value for hydra.job.name (default is 'app') """
def initialize_config_dir(config_dir: str, job_name: str = "app") -> None: """ Initializes Hydra and add an absolute config dir to the to the config search path. The config_dir is always a path on the file system and is must be an absolute path. Relative paths will result in an error. :param config_dir: absolute file system path :param job_name: the value for hydra.job.name (default is 'app') """