Skip to content

Welcome to Heracless

Type-safe YAML configuration management for Python

Transform your YAML config files into strongly-typed Python dataclasses with full IDE autocomplete support.

PyPI version Python Version Rust License: MIT Tests codecov mypy

Why Heracless?

Stop wrestling with dictionaries and string keys. Heracless automatically converts your YAML configuration files into Python dataclasses with full type safety and IDE autocomplete support. Plus it's written in Rust for blazing-fast performance.

# WITHOUT Heracless - prone to typos, no autocomplete
config = yaml.load(open("config.yaml"))
db_host = config["database"]["host"]  # Runtime errors waiting to happen
db_port = config["databse"]["port"]   # Typo goes unnoticed!

# WITH Heracless - type-safe, autocomplete, catch errors at write-time
config = load_config()
db_host = config.database.host  # Autocomplete works!
db_port = config.database.port  # Typos caught by IDE/mypy

Features

  • Automatic Type Generation - Generates .pyi stub files for full IDE support
  • Type Safety - Catch configuration errors at development time, not runtime
  • Zero Boilerplate - No manual dataclass definitions needed
  • IDE Autocomplete - Full IntelliSense/autocomplete for all config values
  • Immutable by Default - Frozen dataclasses prevent accidental modifications
  • Rust-Powered Performance - Native Rust backend for blazing-fast YAML parsing and stub generation

Quick Example

Create a config.yaml file:

database:
  host: localhost
  port: 5432
  name: myapp_db

Load it with full type safety:

from myproject.load_config import load_config

config = load_config()
print(f"Connecting to {config.database.host}:{config.database.port}")

Heracless automatically generates type stubs, giving you:

  • Full autocomplete in your IDE
  • Type checking with mypy
  • Runtime validation
  • Zero boilerplate

Background

Working with config files in Python can be a pain. There's Meta's Hydra, which is a powerful tool for managing complex configurations. For simple projects, Hydra can be overkill.

So I created Heracless, to fight Hydra.

License

Heracless is released under the MIT License. See LICENSE for details.

Author

Felix Schelling