confee 0.2.0

Configuration Enhanced & Easy ☕️ - A Hydra-like configuration parser helper package

Language: 한국어 | English

Hydra-style Configuration Management + Pydantic Type Safety + Typer-style Auto Help Generation

---

☕️ Overview

confee is a package that makes configuration management in Python applications simple, type-safe, and intuitive. It combines the best of Hydra and Pydantic, allowing you to manage configuration files, environment variables, and CLI arguments seamlessly.

---

✨ Key Features

• 🎯 Type-Safe Configuration — Automatic type validation & IDE autocomplete with Pydantic V2
• 📋 Multi-Format Support — Automatic detection and parsing of YAML and JSON
• 🔄 Flexible Override System — Override values via CLI arguments and environment variables
• 🏗️ Configuration Inheritance — Merge and combine parent-child configurations
• 📁 File Reference — Load file contents with @file: & @config: prefixes
• 🔐 Strict Mode — Reject unknown fields or control validation error handling
• 📦 Zero Configuration — Ready to use with sensible defaults
• ⚙️ Parse Order Control — Freely adjust priority of file/env/cli sources
• 💬 Auto Help Generation — Display all options and defaults with --help flag
• 🪆 Nested Field Access — Override nested fields with dot notation (database.host=localhost)
• 🧾 Verbosity Control — Adjust output verbosity with --quiet/--verbose/--no-color flags

---

📦 Installation

pip install confee

---

🚀 Quick Start

Basic Usage

from confee import ConfigBase

class AppConfig(ConfigBase):
    name: str
    debug: bool = False
    workers: int = 4

# Parse from all sources (file, environment, CLI)
config = AppConfig.load(config_file="config.yaml")

print(config.name)     # Type-safe access
print(config.debug)    # Full IDE support
print(config.workers)  # Auto-completion enabled

YAML Configuration File

name: production-app
debug: false
workers: 8

Command Line Override

python app.py name=my-app debug=true workers=16

Environment Variables

export CONFEE_NAME=my-app
export CONFEE_DEBUG=true
export CONFEE_WORKERS=16

python app.py

Help Display

python app.py --help

Detailed Validation Error Messages

By default, validation errors are displayed concisely, but using the --verbose flag shows detailed error information for each field:

# Concise error message (default)
python app.py name=123

# Output:
# Config error: field 'name' - Input should be a valid string

# Display detailed error messages in verbose mode
python app.py name=123 --verbose

# Output:
# ❌ Configuration Validation Error
#
#   Found 1 validation error(s):
#
#   [1] Field: name
#       Error: Input should be a valid string
#       Type: string_type
#       Got: 123
#
#   💡 How to fix:
#     1. Add the required field to your configuration file
#     2. Or pass the value via CLI: python main.py name=myapp
#     3. Or set an environment variable: export CONFEE_NAME=myapp
#     4. Check field types match your configuration class

Or set via environment variable:

export CONFEE_VERBOSITY=verbose
python app.py name=123

---

🎯 Advanced Features

Nested Configuration

from confee import ConfigBase

class DatabaseConfig(ConfigBase):
    host: str = "localhost"
    port: int = 5432

class AppConfig(ConfigBase):
    name: str
    database: DatabaseConfig

# Override nested fields from CLI
# python app.py database.host=prod.db database.port=3306
config = AppConfig.load()
print(config.database.host)  # "prod.db"

File References

# config.yaml
name: my-app
api_key: "@file:secrets/api_key.txt"
database_config: "@config:configs/database.yaml"

Custom Environment Prefix

# Use custom prefix instead of CONFEE_
# MYAPP_DEBUG=true instead of CONFEE_DEBUG=true
config = AppConfig.load(env_prefix="MYAPP_")

Custom Source Order

# Control which sources override others
config = AppConfig.load(
    config_file="config.yaml",
    source_order=["cli", "env", "file"]  # CLI highest priority
)

Strict/Non-Strict Modes

# Strict mode (default): Forbid unknown fields
class Config(ConfigBase):
    name: str

# Non-strict mode: Ignore unknown fields
config = Config.load(strict=False)

---

📚 Documentation

• Comparison with OmegaConf
• Development Guide
• License

---

🎯 Use Cases

Environment-specific Configuration

# dev.yaml
debug: true
workers: 2

# prod.yaml
debug: false
workers: 32

# Load appropriate config
import os
env = os.getenv("APP_ENV", "dev")
config = AppConfig.load(config_file=f"{env}.yaml")

Kubernetes Environment Variables

# pod.yaml
containers:
  - env:
    - name: CONFEE_DEBUG
      value: "false"
    - name: CONFEE_WORKERS
      value: "16"

Configuration Validation

from pydantic import Field

class AppConfig(ConfigBase):
    workers: int = Field(ge=1, le=128)  # Validate range
    timeout: float = Field(gt=0)         # Must be positive

---

🔄 Integration Examples

With FastAPI

from fastapi import FastAPI
from confee import ConfigBase

class AppConfig(ConfigBase):
    title: str = "My API"
    debug: bool = False

# Load config from file and environment only (no CLI)
config = AppConfig.load(
    config_file="config.yaml",
    source_order=["env", "file"]
)
app = FastAPI(title=config.title, debug=config.debug)

With Click

import click
from confee import ConfigBase

class AppConfig(ConfigBase):
    name: str

# Load config from file and environment only (no CLI)
config = AppConfig.load(
    config_file="config.yaml",
    source_order=["env", "file"]
)

@click.command()
def main():
    click.echo(f"Hello {config.name}")

---

✅ Testing Your Configuration

def test_config_loading():
    config = AppConfig.load(
        config_file="tests/fixtures/config.yaml",
        cli_args=["debug=true"],
        strict=True
    )
    assert config.debug is True

---

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Write tests for your changes
4. Submit a pull request

---

📜 License

MIT License © 2025

See LICENSE for details.

---

💬 Support

For issues and questions:

• GitHub Issues: https://github.com/bestend/confee/issues
• GitHub Discussions: https://github.com/bestend/confee/discussions

---

Enjoy ☕️ configuration management!

---

Language: 한국어 | English