tessl/pypi-hydra-core

A framework for elegantly configuring complex applications

—

Pending

Overview

Eval results

Files

Configuration Schema

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

Structured configuration classes that define the schema for Hydra's internal configuration. These dataclasses provide type safety and validation for Hydra's own configuration system, including job settings, runtime information, and framework-specific options.

Capabilities

Main Hydra Configuration

The primary configuration schema that encompasses all Hydra settings and behavior.

@dataclass
class HydraConf:
    """Main Hydra configuration schema."""
    
    defaults: List[Any] = field(default_factory=lambda: [
        {"output": "default"},
        {"launcher": "basic"},
        {"sweeper": "basic"},
        {"help": "default"},
        {"hydra_help": "default"},
        {"hydra_logging": "default"},
        {"job_logging": "default"},
        {"callbacks": None},
        {"env": "default"},
    ])
    
    mode: Optional[RunMode] = None
    searchpath: List[str] = field(default_factory=list)
    run: RunDir = field(default_factory=RunDir)
    sweep: SweepDir = field(default_factory=SweepDir)
    hydra_logging: Dict[str, Any] = MISSING
    job_logging: Dict[str, Any] = MISSING
    sweeper: Any = MISSING
    launcher: Any = MISSING
    callbacks: Dict[str, Any] = field(default_factory=dict)
    help: HelpConf = field(default_factory=HelpConf)
    hydra_help: HydraHelpConf = field(default_factory=HydraHelpConf)
    output_subdir: Optional[str] = ".hydra"
    overrides: OverridesConf = field(default_factory=OverridesConf)
    job: JobConf = field(default_factory=JobConf)
    runtime: RuntimeConf = field(default_factory=RuntimeConf)
    verbose: Any = False

Job Configuration

Configuration schema for individual job settings and metadata.

@dataclass
class JobConf:
    """Job configuration and runtime information."""
    
    name: str = MISSING                    # Job name
    chdir: Optional[bool] = None           # Change to output directory
    override_dirname: str = MISSING        # Override-based directory name
    id: str = MISSING                      # Job ID in scheduling system
    num: int = MISSING                     # Job number in sweep
    config_name: Optional[str] = MISSING   # Config name used
    env_set: Dict[str, str] = field(default_factory=dict)    # Environment variables to set
    env_copy: List[str] = field(default_factory=list)       # Environment variables to copy
    config: JobConfig = field(default_factory=JobConfig)    # Job-specific config
    
    @dataclass
    class JobConfig:
        """Nested job configuration settings."""
        
        @dataclass
        class OverrideDirname:
            """Configuration for override dirname generation."""
            kv_sep: str = "="                    # Key-value separator
            item_sep: str = ","                  # Item separator  
            exclude_keys: List[str] = field(default_factory=list)  # Keys to exclude
        
        override_dirname: OverrideDirname = field(default_factory=OverrideDirname)

Runtime Configuration

Configuration schema for runtime information populated by Hydra during execution.

@dataclass
class RuntimeConf:
    """Runtime information populated during execution."""
    
    version: str = MISSING                          # Hydra version
    version_base: str = MISSING                     # Version base setting
    cwd: str = MISSING                              # Current working directory
    config_sources: List[ConfigSourceInfo] = MISSING # Config source information
    output_dir: str = MISSING                       # Output directory path
    choices: Dict[str, Any] = field(default_factory=dict)  # Composition choices

@dataclass
class ConfigSourceInfo:
    """Information about configuration sources."""
    
    path: str        # Source path
    schema: str      # Source schema/type
    provider: str    # Source provider

Directory Configuration

Configuration schemas for output directory management.

@dataclass
class RunDir:
    """Run output directory configuration."""
    dir: str = MISSING

@dataclass  
class SweepDir:
    """Sweep output directory configuration."""
    dir: str = MISSING      # Base sweep directory
    subdir: str = MISSING   # Job subdirectory pattern

Help and Documentation Configuration

Configuration schemas for help system customization.

@dataclass
class HelpConf:
    """Application help configuration."""
    app_name: str = MISSING    # Application name for help
    header: str = MISSING      # Help header text
    footer: str = MISSING      # Help footer text  
    template: str = MISSING    # Help template path

@dataclass
class HydraHelpConf:
    """Hydra help configuration."""
    hydra_help: str = MISSING  # Hydra help text
    template: str = MISSING    # Hydra help template path

Override Configuration

Configuration schema for command-line and programmatic overrides.

@dataclass
class OverridesConf:
    """Configuration overrides tracking."""
    hydra: List[str] = field(default_factory=list)  # Hydra config overrides
    task: List[str] = field(default_factory=list)   # Task config overrides

Usage Examples

Accessing Hydra Configuration

from hydra import main
from hydra.core.hydra_config import HydraConfig
from omegaconf import DictConfig

@main(version_base=None, config_path="conf", config_name="config")
def my_app(cfg: DictConfig) -> None:
    # Access Hydra's internal configuration
    hydra_cfg = HydraConfig.get()
    
    # Job information
    print(f"Job name: {hydra_cfg.job.name}")
    print(f"Job ID: {hydra_cfg.job.id}")
    print(f"Output directory: {hydra_cfg.runtime.output_dir}")
    
    # Runtime information
    print(f"Hydra version: {hydra_cfg.runtime.version}")
    print(f"Original CWD: {hydra_cfg.runtime.cwd}")
    
    # Configuration choices
    print(f"Config choices: {hydra_cfg.runtime.choices}")

Customizing Job Configuration

# In hydra configuration file (config.yaml):
hydra:
  job:
    name: custom_job_name
    chdir: true  # Change to output directory
    env_set:
      CUDA_VISIBLE_DEVICES: "0,1"
      PYTHONPATH: "/custom/path"
    env_copy:
      - HOME
      - USER

Customizing Output Directories

# In hydra configuration file:
hydra:
  run:
    dir: ./outputs/${now:%Y-%m-%d}/${now:%H-%M-%S}
  
  sweep:
    dir: ./multirun/${now:%Y-%m-%d_%H-%M-%S}
    subdir: ${hydra.job.num}_${hydra.job.id}
  
  job:
    config:
      override_dirname:
        kv_sep: "="
        item_sep: ","
        exclude_keys: ["hydra.verbose"]

Accessing Configuration Metadata

from hydra import main
from hydra.core.hydra_config import HydraConfig
from omegaconf import DictConfig

@main(version_base=None, config_path="conf", config_name="config")  
def analyze_config(cfg: DictConfig) -> None:
    hydra_cfg = HydraConfig.get()
    
    # Analyze configuration sources
    print("Configuration sources:")
    for source in hydra_cfg.runtime.config_sources:
        print(f"  {source.provider}: {source.path} ({source.schema})")
    
    # Show applied overrides
    print("\nApplied overrides:")
    print(f"  Task: {hydra_cfg.overrides.task}")
    print(f"  Hydra: {hydra_cfg.overrides.hydra}")
    
    # Show composition choices
    print("\nComposition choices:")
    for key, value in hydra_cfg.runtime.choices.items():
        print(f"  {key}: {value}")

Custom Help Configuration

# In hydra configuration file:
hydra:
  help:
    app_name: "My Amazing App"
    header: |
      My Amazing App - A demonstration of Hydra configuration
      
      This application showcases advanced configuration management.
    footer: |
      For more information, visit: https://example.com
      
  hydra_help:
    template: |
      Hydra configuration help for My Amazing App
      
      Use --config-help to see available configurations
      Use --hydra-help to see this message

Environment Variable Management

from hydra import main
from hydra.core.hydra_config import HydraConfig
import os

@main(version_base=None, config_path="conf", config_name="config")
def check_environment(cfg: DictConfig) -> None:
    hydra_cfg = HydraConfig.get()
    
    # Check which environment variables were set
    print("Environment variables set by Hydra:")
    for key, value in hydra_cfg.job.env_set.items():
        current_value = os.getenv(key)
        print(f"  {key}: {current_value} (configured: {value})")
    
    # Check which environment variables were copied
    print("\nEnvironment variables copied:")
    for key in hydra_cfg.job.env_copy:
        value = os.getenv(key)
        print(f"  {key}: {value}")

Programmatic Configuration Inspection

from hydra.core.hydra_config import HydraConfig
from hydra.conf import HydraConf, JobConf, RuntimeConf
from omegaconf import OmegaConf

def inspect_hydra_config():
    """Inspect the current Hydra configuration."""
    
    if not HydraConfig.initialized():
        print("Hydra not initialized")
        return
    
    hydra_cfg = HydraConfig.get()
    
    # Convert to structured config for easier inspection
    structured_cfg = OmegaConf.structured(HydraConf)
    current_cfg = OmegaConf.merge(structured_cfg, hydra_cfg)
    
    print("Current Hydra Configuration:")
    print(f"  Mode: {current_cfg.mode}")
    print(f"  Search paths: {current_cfg.searchpath}")
    print(f"  Output subdir: {current_cfg.output_subdir}")
    print(f"  Verbose: {current_cfg.verbose}")
    
    # Job configuration
    print("\nJob Configuration:")
    job_cfg: JobConf = current_cfg.job
    print(f"  Name: {job_cfg.name}")
    print(f"  Change directory: {job_cfg.chdir}")
    print(f"  Override dirname: {job_cfg.override_dirname}")
    
    # Runtime configuration  
    print("\nRuntime Configuration:")
    runtime_cfg: RuntimeConf = current_cfg.runtime
    print(f"  Version: {runtime_cfg.version}")
    print(f"  CWD: {runtime_cfg.cwd}")
    print(f"  Output dir: {runtime_cfg.output_dir}")

Configuration Schema Validation

from hydra.conf import HydraConf, JobConf
from omegaconf import OmegaConf, ValidationError
from dataclasses import dataclass

def validate_custom_hydra_config(config_dict: dict) -> bool:
    """Validate configuration against Hydra schema."""
    
    try:
        # Create structured config from dictionary
        hydra_conf = OmegaConf.structured(HydraConf)
        user_conf = OmegaConf.create(config_dict)
        
        # Merge and validate
        merged = OmegaConf.merge(hydra_conf, user_conf)
        
        # Additional custom validation
        if merged.job.chdir is not None and not isinstance(merged.job.chdir, bool):
            raise ValueError("job.chdir must be boolean")
        
        if merged.output_subdir is not None and not isinstance(merged.output_subdir, str):
            raise ValueError("output_subdir must be string or None")
        
        print("Configuration validation passed")
        return True
        
    except (ValidationError, ValueError) as e:
        print(f"Configuration validation failed: {e}")
        return False

# Usage
test_config = {
    "job": {
        "name": "test_job",
        "chdir": True
    },
    "output_subdir": ".hydra",
    "verbose": True
}

is_valid = validate_custom_hydra_config(test_config)

Install with Tessl CLI