tessl/pypi-hydra-core

A framework for elegantly configuring complex applications

—

Pending

Overview

Eval results

Files

Main Decorator

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

The @hydra.main decorator is the primary entry point for Hydra-enabled applications. It transforms regular Python functions into configuration-aware applications with automatic command-line interface generation and configuration injection.

Capabilities

Main Decorator Function

Decorator that enables Hydra configuration management for application functions. When applied to a function, it automatically handles configuration loading, command-line argument parsing, and dependency injection.

def main(
    config_path: Optional[str] = None,
    config_name: Optional[str] = None,
    version_base: Optional[str] = None
) -> Callable[[TaskFunction], Any]:
    """
    Decorator for Hydra-enabled applications.
    
    Parameters:
    - config_path: Directory where Hydra searches for config files. 
                   Relative paths are interpreted relative to the declaring python file.
                   Can use "pkg://" prefix to specify a python package.
                   If None, no directory is added to the config search path.
    - config_name: Name of the config file (usually without .yaml extension)
    - version_base: Hydra version compatibility base for behavior control
    
    Returns:
    Decorator function that wraps TaskFunction
    """

Usage Examples

Basic usage with file-based configuration:

@hydra.main(version_base=None, config_path="conf", config_name="config")
def my_app(cfg: DictConfig) -> None:
    print(cfg.db.driver)
    print(cfg.db.user)

Usage without configuration files:

@hydra.main(version_base=None, config_path=None)
def my_app(cfg: DictConfig) -> None:
    # cfg will be empty DictConfig
    print("Running with no config")

Usage with package-based config path:

@hydra.main(version_base=None, config_path="pkg://my_package.conf", config_name="config")
def my_app(cfg: DictConfig) -> None:
    print(cfg)

Command-line override examples:

# Override configuration values
python my_app.py db.driver=postgresql db.port=5432

# Run in multirun mode
python my_app.py --multirun db.driver=mysql,postgresql

# Change config file
python my_app.py --config-name=production

Configuration Path Behavior

The config_path parameter supports several patterns:

Relative paths: Interpreted relative to the Python file containing the decorator
Absolute paths: Used as-is (not recommended)
Package paths: Use pkg://package.name to reference Python package resources
None: No config search path is added, useful for structured config-only applications

Version Base Compatibility

The version_base parameter controls backward compatibility behavior:

None: Use current version defaults (recommended for new applications)
"1.1": Use Hydra 1.1 compatible defaults
"1.2": Use Hydra 1.2 compatible defaults

Task Function Requirements

The decorated function must accept a single parameter that is compatible with DictConfig:

# Correct signatures
def my_app(cfg: DictConfig) -> None: ...
def my_app(cfg: Any) -> None: ...
def my_app(cfg) -> None: ...

# Incorrect - multiple parameters not supported
def my_app(cfg: DictConfig, other_param: str) -> None: ...  # Wrong!

Return Values

The decorated function can return any value. In multirun mode, return values from all jobs are collected and can be accessed through job return objects in callbacks or launchers.

Integration with Structured Configs

The main decorator works seamlessly with structured configurations stored in ConfigStore:

from dataclasses import dataclass
from hydra.core.config_store import ConfigStore

@dataclass
class Config:
    name: str
    value: int

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

@hydra.main(version_base=None, config_path=None, config_name="config")
def my_app(cfg: Config) -> None:  # Type hint matches stored config
    print(f"Name: {cfg.name}, Value: {cfg.value}")

Install with Tessl CLI