or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

callbacks.mdcomposition.mdconfig-schema.mdconfig-store.mderrors.mdindex.mdinitialization.mdmain-decorator.mdtypes.mdutilities.md
tile.json

tessl/pypi-hydra-core

A framework for elegantly configuring complex applications

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/hydra-core@1.3.x

To install, run

npx @tessl/cli install tessl/pypi-hydra-core@1.3.0

index.mddocs/

Hydra

A framework for elegantly configuring complex applications. Hydra simplifies the development of complex applications by providing elegant configuration management capabilities, enabling developers to compose and override configurations dynamically from the command line, and supporting hierarchical configuration with automatic merging.

Package Information

  • Package Name: hydra-core
  • Package Type: pypi
  • Language: Python
  • Installation: pip install hydra-core
  • Pytest Integration: Automatic via hydra_pytest entry point

Core Imports

import hydra
from hydra import main, compose, initialize, utils
from hydra.core.config_store import ConfigStore

Main decorator import:

from hydra import main

Configuration composition:

from hydra import compose, initialize

Utility functions:

from hydra.utils import instantiate, get_class, get_method, get_original_cwd, to_absolute_path

Basic Usage

import hydra
from omegaconf import DictConfig

@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)
    print(cfg.db.password)

if __name__ == "__main__":
    my_app()

With structured configs:

from dataclasses import dataclass
from hydra import main, initialize, compose
from hydra.core.config_store import ConfigStore
from omegaconf import DictConfig

@dataclass
class DatabaseConfig:
    driver: str
    user: str
    password: str

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

@main(version_base=None, config_path=None, config_name="config")
def my_app(cfg: DatabaseConfig) -> None:
    print(f"Driver: {cfg.driver}")
    print(f"User: {cfg.user}")
    print(f"Password: {cfg.password}")

if __name__ == "__main__":
    my_app()

Architecture

Hydra's architecture is built around several key components:

  • Configuration Management: Hierarchical configuration composition with YAML files and structured configs
  • Decorator System: The @hydra.main decorator wraps application functions and handles configuration injection
  • ConfigStore: Singleton registry for structured configuration schemas
  • Global State: GlobalHydra manages initialization state and configuration access
  • Plugin System: Extensible launcher, sweeper, and config source plugins
  • Instantiation: Automatic object creation from configuration with dependency injection

This design enables flexible configuration management patterns that scale from simple scripts to large distributed applications while maintaining clean separation between configuration and application logic.

Capabilities

Main Decorator and Application Entry Point

The core decorator that transforms regular Python functions into Hydra-enabled applications with automatic configuration management and command-line interface generation.

def main(
    config_path: Optional[str] = None,
    config_name: Optional[str] = None,
    version_base: Optional[str] = None
) -> Callable[[TaskFunction], Any]: ...

Main Decorator

Configuration Composition

Dynamic configuration composition capabilities allowing runtime assembly of configurations from multiple sources with override support.

def compose(
    config_name: Optional[str] = None,
    overrides: Optional[List[str]] = None,
    return_hydra_config: bool = False,
    strict: Optional[bool] = None
) -> DictConfig: ...

Configuration Composition

Initialization Context Managers

Context managers for programmatic Hydra initialization in different scenarios including file-based configs, module-based configs, and absolute directory paths.

class initialize:
    def __init__(
        self,
        config_path: Optional[str] = None,
        job_name: Optional[str] = None,
        caller_stack_depth: int = 1,
        version_base: Optional[str] = None
    ) -> None: ...

class initialize_config_module:
    def __init__(
        self,
        config_module: str,
        job_name: str = "app",
        version_base: Optional[str] = None
    ) -> None: ...

class initialize_config_dir:
    def __init__(
        self,
        config_dir: str,
        job_name: str = "app", 
        version_base: Optional[str] = None
    ) -> None: ...

Initialization

Object Instantiation and Utilities

Utility functions for dynamic object instantiation from configuration, path resolution, and reflection-based object access.

def instantiate(config: Any, *args: Any, **kwargs: Any) -> Any: ...
def get_class(path: str) -> type: ...
def get_method(path: str) -> Callable[..., Any]: ...
def get_object(path: str) -> Any: ...
def get_original_cwd() -> str: ...
def to_absolute_path(path: str) -> str: ...

Utilities

Configuration Store and Structured Configs

Centralized registry for storing and managing structured configuration schemas with support for hierarchical organization and provider tracking.

class ConfigStore:
    @staticmethod
    def instance() -> "ConfigStore": ...
    
    def store(
        self,
        name: str,
        node: Any,
        group: Optional[str] = None,
        package: Optional[str] = None,
        provider: Optional[str] = None
    ) -> None: ...
    
    def load(self, config_path: str) -> ConfigNode: ...
    def list(self, path: str) -> List[str]: ...

Configuration Store

Type System and Enums

Type definitions, dataclasses, and enums that provide structure for Hydra's configuration system and define behavior for different modes and conversion strategies.

TaskFunction = Callable[[Any], Any]

class RunMode(Enum):
    RUN = 1
    MULTIRUN = 2

class ConvertMode(Enum):
    NONE = "none"
    PARTIAL = "partial"  
    OBJECT = "object"
    ALL = "all"

Types and Enums

Error Handling and Exceptions

Comprehensive exception hierarchy for handling configuration errors, instantiation failures, and other Hydra-specific error conditions.

class HydraException(Exception): ...
class MissingConfigException(IOError, ConfigCompositionException): ...
class InstantiationException(CompactHydraException): ...
class ConfigCompositionException(CompactHydraException): ...

Error Handling

Callback System

Experimental callback API for hooking into Hydra's execution lifecycle with support for run start/end, multirun events, and individual job events.

class Callback:
    def on_run_start(self, config: DictConfig, **kwargs: Any) -> None: ...
    def on_run_end(self, config: DictConfig, **kwargs: Any) -> None: ...
    def on_multirun_start(self, config: DictConfig, **kwargs: Any) -> None: ...
    def on_multirun_end(self, config: DictConfig, **kwargs: Any) -> None: ...
    def on_job_start(self, config: DictConfig, *, task_function: TaskFunction, **kwargs: Any) -> None: ...
    def on_job_end(self, config: DictConfig, job_return: JobReturn, **kwargs: Any) -> None: ...

Callbacks

Configuration Schema Classes

Structured configuration classes that define the schema for Hydra's internal configuration including job settings, runtime information, and hydra-specific options.

@dataclass
class HydraConf:
    defaults: List[Any]
    mode: Optional[RunMode]
    searchpath: List[str]
    run: RunDir
    sweep: SweepDir
    # ... additional fields

@dataclass  
class JobConf:
    name: str
    chdir: Optional[bool]
    override_dirname: str
    # ... additional fields

Configuration Schema

Types

# Version and constants
__version__ = "1.3.2"

# Type aliases
TaskFunction = Callable[[Any], Any]

# Exception classes (key exports)
class MissingConfigException(IOError, ConfigCompositionException):
    """Raised when a required configuration cannot be found."""

# Core dataclasses
@dataclass
class HydraContext:
    config_loader: "ConfigLoader"
    callbacks: "Callbacks"

@dataclass
class ConfigNode:
    name: str
    node: DictConfig
    group: Optional[str]
    package: Optional[str]
    provider: Optional[str]

# Enums
class RunMode(Enum):
    RUN = 1
    MULTIRUN = 2

class ConvertMode(Enum):
    NONE = "none"
    PARTIAL = "partial"
    OBJECT = "object"
    ALL = "all"

class ObjectType(Enum):
    CONFIG = 1
    GROUP = 2
    NOT_FOUND = 3