Charonfig

A Python configuration management library for handling application settings and configuration files with ease.

Overview

Charonfig is a lightweight, Pythonic configuration management tool designed to simplify how you handle application configuration. It provides a clean interface for loading, validating, and managing configuration settings from various sources.

Features

• Easy Configuration Loading: Simple API for loading configuration from files and environment variables
• Type Validation: Built-in validation using Pydantic for type safety
• Multiple Formats: Support for multiple configuration file formats
• Environment Integration: Seamless environment variable override support
• Type Hints: Full Python type hints support for IDE autocomplete
• Minimal Dependencies: Lightweight with minimal external dependencies

Technology Stack

• Language: Python 100%
• Build System: Modern Python packaging with pyproject.toml
• Configuration: Setuptools with pyproject.toml

Project Structure

charonfig/
├── src/                    # Source code package
│   └── charonfig/         # Main package directory
├── pyproject.toml         # Project configuration and dependencies
├── MANIFEST.in            # Package manifest
└── README.md              # Documentation

Installation

From PyPI

pip install charonfig

From Source

git clone https://github.com/AAEO04/charonfig.git
cd charonfig
pip install -e .

Quick Start

Basic Usage

from charonfig import Config

# Load configuration
config = Config.from_file('config.yml')

# Access settings
database_url = config.get('database.url')
debug_mode = config.get('debug', default=False)

With Environment Variables

from charonfig import Config

# Configuration with environment variable overrides
config = Config.from_file('config.yml', override_from_env=True)

# Environment variables override file settings
# e.g., export APP_DEBUG=true

Type-Safe Configuration

from charonfig import BaseConfig
from pydantic import Field

class AppConfig(BaseConfig):
    """Application configuration with type validation."""
    debug: bool = Field(default=False, description="Enable debug mode")
    database_url: str = Field(description="Database connection URL")
    port: int = Field(default=8000, description="Application port")
    log_level: str = Field(default="INFO", description="Logging level")

# Load and validate
config = AppConfig.from_file('config.yml')

Configuration File Formats

Charonfig supports multiple configuration file formats:

YAML Format

database:
  url: postgresql://localhost/myapp
  pool_size: 10
debug: false
port: 8000

JSON Format

{
  "database": {
    "url": "postgresql://localhost/myapp",
    "pool_size": 10
  },
  "debug":  false,
  "port": 8000
}

TOML Format

debug = false
port = 8000

[database]
url = "postgresql://localhost/myapp"
pool_size = 10

API Reference

Config Class

Config.from_file(path, **kwargs)

Load configuration from a file.

Parameters:

• path (str): Path to configuration file
• override_from_env (bool): Override settings with environment variables

Returns: Config instance

config.get(key, default=None)

Get a configuration value.

Parameters:

• key (str): Dot-notation key path (e.g., "database.url")
• default (Any): Default value if key not found

Returns: Configuration value or default

config.set(key, value)

Set a configuration value.

Parameters:

• key (str): Dot-notation key path
• value (Any): Value to set

config.to_dict()

Export configuration as dictionary.

Returns: Dict representation of config

BaseConfig Class

Base class for type-safe configuration using Pydantic:

from charonfig import BaseConfig
from typing import Optional

class DatabaseConfig(BaseConfig):
    url: str
    pool_size: int = 10
    timeout: Optional[int] = None

class AppConfig(BaseConfig):
    debug: bool = False
    database: DatabaseConfig
    port: int = 8000

Environment Variables

Charonfig automatically handles environment variable mapping:

# Application configuration
export CHARONFIG_DEBUG=true
export CHARONFIG_PORT=3000
export CHARONFIG_DATABASE_URL=postgresql://localhost/myapp

Use Cases

Flask/Django Applications

from charonfig import Config

class Config:
    config = Config.from_file('config.yml', override_from_env=True)
    DEBUG = config.get('debug')
    DATABASE_URL = config.get('database.url')
    SECRET_KEY = config.get('secret_key')

Microservices

from charonfig import BaseConfig

class ServiceConfig(BaseConfig):
    service_name: str
    api_key: str
    log_level: str = "INFO"

config = ServiceConfig.from_file(f'config.{os.getenv("ENV")}.yml')

Configuration Validation

from charonfig import BaseConfig
from pydantic import validator

class AppConfig(BaseConfig):
    port: int
    
    @validator('port')
    def validate_port(cls, v):
        if not (1 <= v <= 65535):
            raise ValueError('Port must be between 1 and 65535')
        return v

Development

Setup Development Environment

git clone https://github.com/AAEO04/charonfig.git
cd charonfig
pip install -e ".[dev]"

Running Tests

pytest

Building Package

python -m build

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Repository Information

• Created: October 3, 2025
• Last Updated: October 3, 2025
• Language Composition: Python 100%
• Repository Size: 9 KB
• Visibility: Public

License

This project is open source and available publicly on GitHub.

Support

For issues, questions, or feature requests, please visit the repository issues page.

Roadmap

• YAML/JSON/TOML format support
• CLI tool for configuration management
• Configuration schema validation
• Hot reload support
• Encrypted configuration values
• Configuration documentation generator