heracless
Advanced tools
Type-safe YAML configuration management for Python
Transform your YAML config files into strongly-typed Python dataclasses with full IDE autocomplete support
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
.pyi stub files for full IDE supportpip install heracless
git clone https://github.com/felixscode/heracless.git
cd heracless
pip install -e .
| Python Version | Status |
|---|---|
| 3.10 - 3.13 | Fully Supported |
| 3.9 and below | Not Supported |
Dependencies: PyYAML, black, art
Note: Prebuilt Rust wheels are available for Linux, macOS, and Windows. No Rust installation required!
Create a config.yaml file with your settings:
# config.yaml
database:
host: localhost
port: 5432
name: myapp_db
credentials:
username: admin
password: secret123 # don't use this in production
api:
base_url: https://api.example.com
timeout: 30
retries: 3
features:
enable_caching: true
max_cache_size: 1000
Create a load_config.py file in your project:
# src/myproject/load_config.py
from pathlib import Path
from typing import TypeVar
from heracless import load_config as _load_config
# Point to your config file
CONFIG_YAML_PATH = Path(__file__).parent.parent / "config.yaml"
Config = TypeVar("Config")
def load_config(config_path: Path | str = CONFIG_YAML_PATH,
frozen: bool = True,
stub_dump: bool = True) -> Config:
"""Load configuration and generate type stubs."""
file_path = Path(__file__).resolve() if stub_dump else None
return _load_config(config_path, file_path, frozen=frozen)
# src/myproject/main.py
from myproject.load_config import load_config
# Load config - first run generates load_config.pyi with types!
config = load_config()
# Access config with autocomplete and type checking
print(f"Connecting to {config.database.host}:{config.database.port}")
print(f"Database: {config.database.name}")
print(f"API URL: {config.api.base_url}")
print(f"Caching enabled: {config.features.enable_caching}")
Output:
Connecting to localhost:5432
Database: myapp_db
API URL: https://api.example.com
Caching enabled: True
After the first run, Heracless automatically generates a load_config.pyi file:
# load_config.pyi (auto-generated)
from dataclasses import dataclass
from typing import TypeVar
@dataclass(frozen=True)
class Credentials:
username: str
password: str
@dataclass(frozen=True)
class Database:
host: str
port: int
name: str
credentials: Credentials
@dataclass(frozen=True)
class Api:
base_url: str
timeout: int
retries: int
@dataclass(frozen=True)
class Features:
enable_caching: bool
max_cache_size: int
@dataclass(frozen=True)
class Config:
database: Database
api: Api
features: Features
This stub file enables full IDE autocomplete and type checking
from myproject.load_config import load_config
# Load with defaults (frozen, with stub generation)
config = load_config()
# Access nested values with autocomplete
db_url = f"{config.database.host}:{config.database.port}"
# Load mutable config for testing or dynamic updates
config = load_config(frozen=False)
# Modify values (only works with frozen=False)
config.database.host = "192.168.1.100"
from heracless.utils.helper import as_dict
config = load_config()
config_dict = as_dict(config)
# Now a regular Python dictionary
print(config_dict["database"]["host"]) # localhost
from heracless.utils.helper import from_dict
config_dict = {
"database": {
"host": "localhost",
"port": 5432
},
"api": {
"base_url": "https://api.example.com",
"timeout": 30
}
}
config = from_dict(config_dict, frozen=True)
print(config.database.host) # localhost (with type checking!)
from heracless.utils.helper import mutate_config
config = load_config()
# Create a new config with updated value (immutable pattern)
new_config = mutate_config(config, "database.host", "production-db.example.com")
print(config.database.host) # localhost (original unchanged)
print(new_config.database.host) # production-db.example.com
Heracless includes a CLI tool for generating stub files and validating configs:
# Generate stub file from config
python -m heracless config.yaml --parse types.pyi
# Dry run (validate config without generating files)
python -m heracless config.yaml --dry
# Show help
python -m heracless --help
Here's a recommended project structure:
my_project/
├── src/
│ └── myproject/
│ ├── __init__.py
│ ├── main.py
│ └── config/
│ ├── __init__.py
│ ├── load_config.py # Your config loader
│ └── load_config.pyi # Auto-generated types
├── config/
│ ├── config.yaml # Main config
│ ├── config.dev.yaml # Development overrides
│ └── config.prod.yaml # Production overrides
├── tests/
│ └── test_config.py
├── pyproject.toml
└── README.md
Solutions:
.pyi file exists next to your load_config.pyTypeError: 'Config' object is immutableSolution: This is by design (frozen dataclass). To modify configs:
mutate_config() helper to create updated copiesfrozen=False for mutable configs (not recommended)Solution: Ensure your YAML is valid:
# Validate YAML syntax
python -c "import yaml; yaml.safe_load(open('config.yaml'))"
load_config(config_path, file_path, frozen)Load a YAML configuration file and convert it to a typed dataclass.
Parameters:
config_path (Path | str): Path to the YAML configuration filefile_path (Path | str | None): Path where stub file should be generated (None to skip)frozen (bool): Whether the resulting dataclass should be immutable (default: True)Returns: Config dataclass with attributes matching your YAML structure
Raises:
FileNotFoundError: If config file doesn't existyaml.YAMLError: If YAML file is malformedmutate_config(config, name, value)Create a new config with an updated value (immutable pattern).
from heracless.utils.helper import mutate_config
config = load_config()
new_config = mutate_config(config, "database.port", 3306)
as_dict(config)Convert a Config dataclass to a nested dictionary.
from heracless.utils.helper import as_dict
config = load_config()
config_dict = as_dict(config) # Returns: dict
from_dict(config_dict, frozen)Create a Config dataclass from a dictionary.
from heracless.utils.helper import from_dict
config_dict = {"database": {"host": "localhost"}}
config = from_dict(config_dict, frozen=True)
Contributions are welcome! Here's how you can help:
# Clone the repository
git clone https://github.com/felixscode/heracless.git
cd heracless
# Install with development dependencies
pip install -e .[dev]
# Run tests
pytest
# Run type checking
mypy heracless
# Run code formatting
black heracless tests
# Run all tests
pytest
# Run with coverage
pytest --cov=heracless --cov-report=html
# Run specific test file
pytest tests/test_config.py
Install development dependencies with:
pip install -e .[dev]
This includes:
pytest - Testing frameworkpytest-cov - Coverage reportingmypy - Static type checkingtypes-PyYAML - Type stubs for PyYAMLTo work on the documentation:
# Install documentation dependencies
pip install -e .[doc]
# Serve documentation locally
mkdocs serve
# Build documentation
mkdocs build
Found a bug or have a feature request? Open an issue on GitHub.
Please include:
pip show heracless)${ENV_VAR} syntax in YAMLHeracless is released under the MIT License. See LICENSE file for details.
MIT License
Copyright (c) 2023 Felix Schelling
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
TL;DR: You can freely use, modify, and distribute this software, even for commercial purposes.
Felix Schelling
If Heracless helps your project, consider giving it a star on GitHub!
FAQs
Yaml to Dataclass parser for Config files (Rust-powered for performance)
We found that heracless demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
The planned feature introduces a review step before releases go live, following the Shai-Hulud attacks and a rocky migration off classic tokens that disrupted maintainer workflows.
Security News
GitHub postponed a new billing model for self-hosted Actions after developer pushback, but moved forward with hosted runner price cuts on January 1.
Research
Destructive malware is rising across open source registries, using delays and kill switches to wipe code, break builds, and disrupt CI/CD.