TyConf

TyConf ≡ Typed Config - a type-safe configuration management library for Python with runtime validation.

What is TyConf?

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.

Quick Start

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-only

Serialization

TyConf 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

Key Features

✅ 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)

Installation

pip install tyconf

Requirements: Python 3.13+

Optional Dependencies:

# For TOML export support (TOML import is built-in via tomllib)
pip install tyconf[toml]

Documentation

• User Guide - Comprehensive guide with all features
• API Reference - Complete API documentation
• Best Practices - Tips for effective usage

Examples

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

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Links

• GitHub: https://github.com/barabasz/tyconf
• Issues: https://github.com/barabasz/tyconf/issues