configium 0.1.0

A smart configuration manager with auto-save and type validation

Configium 🔧

A smart, type-safe configuration manager for Python with auto-save and auto-reload capabilities.

Features

✨ Auto-save: Changes are automatically persisted to disk
🔄 Auto-reload: Detects external file modifications and reloads
🛡️ Type-safe: Pydantic integration for robust validation
📝 Multiple formats: Support for JSON, YAML, and TOML
🔒 Thread-safe: Safe for concurrent access
⚡ High performance: Efficient file change detection

Installation

pip install configium

Quick Start

from configium import ConfigManager

# Create or load configuration
config = ConfigManager("config.yaml")

# Use it like a dictionary
config["database"] = {
    "host": "localhost",
    "port": 5432
}

# Changes are automatically saved!
print(config["database"]["host"])  # localhost

# Nested access
config["api"]["key"] = "secret"

Advanced Usage

Type Validation with Pydantic

from pydantic import BaseModel
from configium import ConfigManager

class DatabaseConfig(BaseModel):
    host: str
    port: int
    username: str

config = ConfigManager("config.yaml", validation_model=DatabaseConfig)

# This works
config.update({"host": "localhost", "port": 5432, "username": "admin"})

# This raises ValidationError
config["port"] = "invalid"  # ❌ Must be int

Different Formats

# JSON
config = ConfigManager("config.json", format="json")

# TOML
config = ConfigManager("config.toml", format="toml")

# Auto-detect from extension
config = ConfigManager("config.yaml")  # Automatically uses YAML

Manual Control

# Disable auto-save
config = ConfigManager("config.yaml", auto_save=False)
config["key"] = "value"
config.save()  # Manually save

# Disable auto-reload
config = ConfigManager("config.yaml", auto_reload=False)
config.reload()  # Manually reload

Thread-Safe Operations

from threading import Thread

config = ConfigManager("config.yaml")

def update_config(key, value):
    config[key] = value

# Safe concurrent access
threads = [Thread(target=update_config, args=(f"key{i}", i)) for i in range(10)]
for t in threads:
    t.start()
for t in threads:
    t.join()

API Reference

ConfigManager

ConfigManager(
    file_path: str | Path,
    format: str = "yaml",
    auto_save: bool = True,
    auto_reload: bool = True,
    validation_model: Optional[Type[BaseModel]] = None,
    create_if_missing: bool = True,
)

Parameters:

• file_path: Path to configuration file
• format: File format (json, yaml, toml)
• auto_save: Enable automatic saving
• auto_reload: Enable automatic reloading
• validation_model: Pydantic model for validation
• create_if_missing: Create file if it doesn't exist

Methods:

• reload(): Manually reload from file
• save(): Manually save to file
• update(dict): Update multiple values
• to_dict(): Get configuration as dictionary
• clear(): Clear all configuration

Performance

Configium is designed for high performance:

• Smart change detection: Uses mtime + hash for accurate detection
• Atomic writes: Prevents corruption during saves
• Minimal overhead: Dict proxy with negligible performance impact
• Efficient locking: Fine-grained locks for thread safety

Security

• ✅ Uses yaml.safe_load() to prevent code execution
• ✅ Atomic file writes prevent corruption
• ✅ Type validation prevents injection attacks
• ✅ No eval() or exec() usage

Contributing

Contributions welcome! Please check out our GitHub repository.

License

MIT License - see LICENSE file for details.