Metadata-Version: 2.1
Name: conftier
Version: 0.1.0
Summary: Multi-level configuration framework
Home-page: https://github.com/Undertone0809/conftier
License: MIT
Author: conftier
Author-email: zeeland4work@gmail.com
Requires-Python: >=3.9,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: rich (>=10.14.0,<11.0.0)
Requires-Dist: typer[all] (>=0.4.0,<0.5.0)
Requires-Dist: zeeland (>=0.3.0,<0.4.0)
Project-URL: Repository, https://github.com/Undertone0809/conftier
Description-Content-Type: text/markdown

<p align="center">
   <img src="./docs/public/banner.png" alt="conftier Banner" style="border-radius: 15px;">
</p>

<div align="center">

[![Build status](https://github.com/Undertone0809/conftier/workflows/build/badge.svg?branch=main&event=push)](https://github.com/Undertone0809/conftier/actions?query=workflow%3Abuild)
[![Python Version](https://img.shields.io/pypi/pyversions/conftier.svg)](https://pypi.org/project/conftier/)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![License](https://img.shields.io/github/license/Undertone0809/conftier)](https://github.com/Undertone0809/conftier/blob/main/LICENSE)
![Coverage Report](assets/images/coverage.svg)

</div>

# Conftier

A powerful multi-tier configuration management framework that simplifies the definition, access, and synchronization of layered configurations in Python applications.

Think of VSCode's configuration system: you have user settings that apply globally and workspace settings that override them for specific projects. Conftier brings this same intuitive model to your Python frameworks and applications.

## Overview

Conftier helps you manage configurations across multiple levels:

- **User-level settings**: Global preferences that apply across all projects (~/.zeeland/{config_name}/config.yaml)
- **Project-level settings**: Local configurations specific to a project (./.{config_name}/config.yaml)
- **Default values**: Fallback values defined in your configuration schema

Conftier automatically merges these configurations based on priority (project > user > default).

## Key Features

- **Multi-level Configuration Management**: Like VSCode's user/workspace settings pattern
- **Flexible Schema Definition**: Use Pydantic models or dataclasses to define and validate configurations
- **Type Safety**: No more string/int confusion or missing required fields
- **Smart Merging**: Only override what's specified, preserving other values
- **CLI Integration**: Built-in command-line tools for configuration management
- **IDE Autocompletion**: Full type hints for a great developer experience

## Why Conftier?

| Without Conftier | With Conftier |
|------------------|---------------|
| Manual parsing of multiple config files | Automatic loading and merging |
| Type errors discovered at runtime | Validation at load time |
| Custom code for merging configs | Smart merging built-in |
| Documentation struggles | Schema serves as documentation |
| Repetitive boilerplate | Consistent, reusable pattern |

## Installation

```bash
# Basic installation
pip install conftier

# With Pydantic support (recommended)
pip install conftier[pydantic]
```

## Quick Example

```python
from pydantic import BaseModel, Field
from conftier import ConfigManager

class AppConfig(BaseModel):
    app_name: str = "MyApp"
    debug: bool = False

config_manager = ConfigManager(
    config_name="myapp",
    config_schema=AppConfig,
    auto_create=True
)

# Load the merged configuration
config: AppConfig = config_manager.load()
```

## When to Use Conftier

Conftier shines when:

1. **You're building a framework or library**: Give your users a consistent way to configure your tool
2. **Your app has both user and project settings**: Like VSCode's personal vs. project-specific settings
3. **You need schema validation**: Ensure configuration values have the correct types and valid ranges
4. **You want to reduce boilerplate**: Stop writing the same configuration loading code in every project

## Documentation

For comprehensive guides, examples, and API reference, visit our documentation:

- [Introduction](https://conftier.zeeland.top/)
- [Quick Start Guide](https://conftier.zeeland.top/guide/quick-start.html)

## Development

```bash
# Create and activate conda environment
conda create -n conftier python==3.10
conda activate conftier

# Install poetry and dependencies
pip install poetry
poetry install
```



