TyConf ≡ Typed Config - a type-safe configuration management library for Python with runtime validation.
TyConf is a modern Python 3.13+ library that makes managing application configuration simple, safe, and intuitive. It provides runtime type validation, value validation, read-only properties, and freeze/unfreeze capabilities to help you build robust applications.
from tyconf import TyConf
from tyconf.validators import range
# Create configuration with type-safe properties and validators
config = TyConf(
host=(str, "localhost"), # Mutable string
debug=(bool, True), # Mutable boolean
port=(int, 8080, range(1024, 65535)), # Validated mutable range
users=(list, ["admin", "root"], True) # Immutable list
)
# Access values easily
print(config.host) # 'localhost'
config.port = 3000 # Type-checked and range-validated automatically
config.port = "3000" # Rises TypeError: Property 'port': expected int, got str
config.users = ["guest"] # Rises AttributeError: Property 'users' is read-onlyTyConf supports exporting and importing configurations in multiple formats:
from tyconf import TyConf
config = TyConf(
host=(str, "localhost"),
port=(int, 8080),
debug=(bool, True)
)
# Export to JSON (with full metadata)
config.to_json('config.json')
# Export to JSON (values only)
config.to_json('values.json', values_only=True)
# Export to TOML (requires: pip install tyconf[toml])
config.to_toml('config.toml')
# Import from JSON
config = TyConf.from_json('config.json')
# Import from TOML (built-in via tomllib)
config = TyConf.from_toml('config.toml')
# Load from environment variables
config = TyConf.from_env(prefix='APP_', schema={
'host': str,
'port': int,
'debug': bool
})
# Merge configurations
config.load_json('overrides.json') # Merge JSON into existing config
config.load_env(prefix='APP_') # Merge environment variables✅ Type Safety - Runtime type validation with support for Optional and Union types
✅ Value Validation - Built-in validators (range, length, regex, etc.) and custom validation functions
✅ Read-Only Properties - Protect critical configuration from accidental changes
✅ Freeze/Unfreeze - Lock entire configuration to prevent modifications
✅ Serialization - Export/import configurations to JSON, TOML, and environment variables
✅ Intuitive API - Both attribute (config.host) and dict-style (config['host']) access
✅ Copy & Reset - Easily duplicate or restore default configurations
✅ Zero Dependencies - Pure Python with no external requirements (TOML write requires optional dependency)
pip install tyconfRequirements: Python 3.13+
Optional Dependencies:
# For TOML export support (TOML import is built-in via tomllib)
pip install tyconf[toml]- User Guide - Comprehensive guide with all features
- API Reference - Complete API documentation
- Best Practices - Tips for effective usage
See the examples/ directory for complete examples:
- basic_usage.py - Getting started
- advanced_usage.py - Advanced features
- real_world_app.py - Real-world application configuration
- validation_examples.py - Value validation examples
MIT License - see LICENSE for details.
Contributions are welcome! Please feel free to submit a Pull Request.