Python Package¶

The holoconf Python package provides native bindings to the Rust core library via PyO3, giving you high-performance configuration management with Pythonic ergonomics.

Installation¶

pip install holoconf

Requires Python 3.9 or later. The package includes pre-built wheels for common platforms.

Quick Start¶

from holoconf import Config, Schema

# Load configuration
config = Config.load("config.yaml")

# Access values (resolves interpolations automatically)
host = config.get("database.host")
port = config.get("database.port")

# Or use dict-like access
host = config["database.host"]

# Export resolved configuration
print(config.to_yaml(resolve=True))

# Validate against a schema
schema = Schema.load("schema.json")
config.validate(schema)

Features¶

Native performance - Rust core compiled to native extension
Lazy resolution - Values resolved on access, not at parse time
Type coercion - get_string(), get_int(), get_float(), get_bool()
Dict-like access - config["key"] and config.key syntax
Schema validation - JSON Schema support with detailed errors
Serialization - Export to YAML/JSON with optional redaction

Package Contents¶

Classes¶

Class	Description
Config	Main configuration object for loading and accessing values
Schema	JSON Schema validator for configuration

Exceptions¶

Exception	Description
HoloconfError	Base exception for all holoconf errors
ParseError	YAML/JSON syntax errors
ValidationError	Schema validation failures
ResolverError	Resolution failures (missing env vars, etc.)
PathNotFoundError	Config path doesn't exist
CircularReferenceError	Circular reference detected
TypeCoercionError	Type conversion failures

Examples¶

Environment Variables with Defaults¶

# config.yaml:
# database:
#   host: ${env:DB_HOST,default=localhost}
#   port: ${env:DB_PORT,default=5432}

config = Config.load("config.yaml")

# Uses environment variable if set, otherwise default
host = config.get("database.host")  # "localhost" or $DB_HOST

Merging Configurations¶

# Load base config, then override with environment-specific
config = Config.load_merged([
    "config/base.yaml",
    "config/production.yaml"
])

Validation with Error Collection¶

schema = Schema.load("schema.json")
errors = config.validate_collect(schema)

if errors:
    print("Validation errors:")
    for error in errors:
        print(f"  - {error}")
else:
    print("Configuration is valid")

Safe Export (Redacted)¶

# Redact sensitive values for logging
safe_yaml = config.to_yaml(resolve=True, redact=True)
print(safe_yaml)
# database:
#   host: prod-db.example.com
#   password: "[REDACTED]"

Code Coverage¶

The Python package coverage measures the wrapper layer (__init__.py, cli.py). The core logic is tested via Rust coverage.

Coverage not available

Run make coverage to generate coverage reports.

Generate coverage reports

Run make coverage to generate coverage data.