tessl/pypi-hydra-core

A framework for elegantly configuring complex applications

—

Pending

Overview

Eval results

Files

Configuration Composition

Name: tessl/pypi-hydra-core
Author: tessl

Dynamic configuration composition capabilities that allow runtime assembly of configurations from multiple sources with override support. This enables programmatic configuration creation outside of the main application decorator.

Capabilities

Compose Function

Composes configuration dynamically from registered sources, applying overrides and returning a fully merged configuration object.

def compose(
    config_name: Optional[str] = None,
    overrides: Optional[List[str]] = None,
    return_hydra_config: bool = False,
    strict: Optional[bool] = None
) -> DictConfig:
    """
    Compose configuration dynamically.
    
    Parameters:
    - config_name: Name of the config to compose (usually without .yaml extension)
    - overrides: List of configuration overrides in the format ["key=value", "nested.key=value"]
    - return_hydra_config: If True, includes hydra configuration node in result
    - strict: DEPRECATED. Previously controlled struct mode behavior
    
    Returns:
    DictConfig: Composed configuration object
    
    Raises:
    AssertionError: If GlobalHydra is not initialized
    """

Initialization Requirement

The compose function requires Hydra to be initialized first using one of the initialization context managers:

from hydra import initialize, compose

# Must initialize before composing
with initialize(version_base=None, config_path="conf"):
    cfg = compose(config_name="config")
    print(cfg)

Usage Examples

Basic composition:

from hydra import initialize, compose

with initialize(version_base=None, config_path="conf"):
    # Compose default config
    cfg = compose(config_name="config")
    
    # Compose with overrides
    cfg_override = compose(
        config_name="config",
        overrides=["db.driver=postgresql", "db.port=5432"]
    )
    
    # Include hydra configuration
    cfg_with_hydra = compose(
        config_name="config",
        return_hydra_config=True
    )

Composition with structured configs:

from dataclasses import dataclass
from hydra import initialize_config_module, compose
from hydra.core.config_store import ConfigStore

@dataclass
class DatabaseConfig:
    driver: str = "mysql"
    port: int = 3306

cs = ConfigStore.instance()
cs.store(name="config", node=DatabaseConfig)

with initialize_config_module(version_base=None, config_module="conf"):
    cfg = compose(config_name="config")
    
    # Override structured config values
    cfg_postgres = compose(
        config_name="config",
        overrides=["driver=postgresql", "port=5432"]
    )

Override Syntax

The overrides parameter supports Hydra's full override syntax:

overrides = [
    "db.driver=postgresql",           # Simple value assignment
    "db.port=5432",                   # Numeric values
    "db.ssl=true",                    # Boolean values  
    "db.hosts=[host1,host2,host3]",   # List values
    "+new_key=value",                 # Add new key
    "~optional_key",                  # Delete key
    "db=postgres",                    # Config group selection
]

cfg = compose(config_name="config", overrides=overrides)

Config Group Selection

Use overrides to select different configurations from config groups:

# With config groups: conf/db/mysql.yaml and conf/db/postgres.yaml
cfg_mysql = compose(
    config_name="config",
    overrides=["db=mysql"]
)

cfg_postgres = compose(
    config_name="config", 
    overrides=["db=postgres"]
)

Return Hydra Config

When return_hydra_config=True, the result includes Hydra's internal configuration:

cfg = compose(config_name="config", return_hydra_config=True)

# Access Hydra configuration
print(cfg.hydra.job.name)
print(cfg.hydra.runtime.cwd)
print(cfg.hydra.runtime.output_dir)

# Access application configuration  
print(cfg.db.driver)  # Application config is at root level

Error Handling

Common errors and their causes:

# AssertionError - GlobalHydra not initialized
try:
    cfg = compose(config_name="config")  # Will fail!
except AssertionError as e:
    print("Must initialize Hydra first")

# MissingConfigException - Config not found
with initialize(version_base=None, config_path="conf"):
    try:
        cfg = compose(config_name="nonexistent")
    except MissingConfigException as e:
        print(f"Config not found: {e}")

Integration with Different Initialization Methods

The compose function works with all initialization context managers:

# File-based initialization
with initialize(version_base=None, config_path="conf"):
    cfg = compose(config_name="config")

# Module-based initialization  
with initialize_config_module(version_base=None, config_module="my_app.conf"):
    cfg = compose(config_name="config")

# Directory-based initialization
with initialize_config_dir(version_base=None, config_dir="/absolute/path/conf"):
    cfg = compose(config_name="config")

Install with Tessl CLI