Heracless Screenshot

Introduction

Configuration files are essential in modern Python projects—from machine learning experiments and web apps to data pipelines and simulations.

Yet many tools (like Hydra) introduce complexity that can be overwhelming for small- to mid-sized projects. Heracless offers a minimalist alternative that brings structure, type safety, and IDE autocompletion to your configuration workflow—without the learning curve.

What is Heracless?

Heracless is a lightweight Python library that:

  • Parses config files (YAML) into type-safe Python dataclasses
  • Generates .pyi stub files for IDE autocompletion and type hinting
  • Makes your config usage as easy as config.model.learning_rate

No metaclasses, no complex CLI overrides, no global state—just clean Python and familiar patterns.

Why “Heracless”?

The name is a playful jab at complexity.

In Greek mythology, Heracles fought the many-headed Hydra—cut one head off, two grow back.

Hydra is Meta’s popular config manager. While powerful, it’s heavy for many use cases.
Heracless is:

  • Less Hydra
  • Less complexity
  • Less magic

Example: From YAML to Python

config.yaml

model:
  name: "resnet"
  learning_rate: 0.001
  layers: 34

training:
  batch_size: 64
  epochs: 10

main.py

from your_module import load_config

config = load_config()

print(config.model.name)           # "resnet"
print(config.training.batch_size) # 64

Autocompletion + Type Hints

Heracless generates a .heracless/config.pyi stub file:

# .heracless/config.pyi (auto-generated)
class Model:
    name: str
    learning_rate: float
    layers: int

class Training:
    batch_size: int
    epochs: int

class Config:
    model: Model
    training: Training

So your IDE can suggest config.model.learning_rate with type info—just like native code.

Features

  • YAML → Python dataclass parser
  • Auto-generated .pyi files for autocompletion
  • CLI tool to regenerate stubs on file change
  • Supports nested config blocks
  • Typed access to every field
  • designed for dev speed and simplicity

Use Cases

  • Machine Learning: Manage experiment configs in YAML, enjoy type-safe access in your training script.
  • Streamlit apps: Centralize user settings or environment parameters without hardcoding.
  • Dev tools: Easily switch between config presets with confidence—knowing typos will be caught.

Installation

pip install heracless

Resources

Final Thoughts

Heracless is built for developers who want just enough structure—without adopting a whole framework.

If you’ve ever written "config['model']['layers']" and felt uneasy—Heracless is for you.

Try it out, star the repo, or submit an issue.

— Felix