Metadata-Version: 2.4
Name: TATamis-configs
Version: 1.4.0
Summary: 配置文件管理工具 - 支持 INI、JSON、环境变量、命令行参数等多种配置来源
Author: MikuPy2001
Author-email: MikuPy2001 <794126318@qq.com>
Maintainer-email: MikuPy2001 <794126318@qq.com>
Project-URL: Homepage, https://github.com/MikuPy2001/TATamis-configs
Project-URL: Repository, https://github.com/MikuPy2001/TATamis-configs
Project-URL: Issues, https://github.com/MikuPy2001/TATamis-configs/issues
Project-URL: Changelog, https://github.com/MikuPy2001/TATamis-configs/blob/main/CHANGELOG.md
Keywords: config,configuration,ini,json,settings,python-config,tatamis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: license-file
Dynamic: requires-python

# configs

配置文件管理工具 - 支持 INI、JSON、环境变量、命令行参数等多种配置来源

[![PyPI version](https://badge.fury.io/py/configs.svg)](https://badge.fury.io/py/configs)
[![Python Versions](https://img.shields.io/pypi/pyversions/configs.svg)](https://pypi.org/project/configs/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Version](https://img.shields.io/badge/version-1.4.0-blue.svg)](CHANGELOG.md)

## 📖 简介

`configs` 是一个轻量级的 Python 配置管理工具，支持多种配置来源和灵活的配置优先级。它可以帮助您轻松管理应用程序的配置，无论是开发环境还是生产环境。

**当前版本**: 1.4.0 (2025-03-03)

## ✨ 功能特性

- ✅ **多格式支持**: INI、JSON 配置文件
- ✅ **灵活来源**: 环境变量、命令行参数
- ✅ **智能缓存**: 自动缓存机制，提高性能
- ✅ **国际化**: 中文/英文错误提示
- ✅ **配置优先级**: 灵活的配置加载顺序
- ✅ **类型安全**: 完整的类型注解
- ✅ **易于使用**: 简洁的 API 设计
- ✅ **魔法方法**: 支持属性和字典方式访问

## 🚀 快速开始

### 安装

```bash
pip install configs
```

### 基本使用

```python
from configs import get_config

# 获取配置实例
config = get_config()

# 读取配置值
value = config.get("key")
# 或使用属性访问
value = config.key

# 检查配置是否存在
if config.has("key"):
    print("配置存在")

# 设置配置值
config.set("key", "value")
```

## 📚 详细文档

### 配置文件示例

#### INI 格式 (config.ini)

```ini
[DEFAULT]
database_host=localhost
database_port=3306
app_name=MyApp
debug=true
```

#### JSON格式 (config.json)

```json
{
    "database_host": "localhost",
    "database_port": 3306,
    "app_name": "MyApp",
    "debug": true
}
```

### 配置优先级

配置的优先级从低到高:

1. 当前目录的 `config/config.ini`
2. 当前目录的 `config/config.json`
3. 当前目录的 `config.ini`
4. 当前目录的 `config.json`
5. 环境变量
6. 命令行参数 (`-key value`)
7. 自定义配置目录 (`config_dir` 参数指定)
8. 自定义配置文件 (`config_file` 参数指定)

### 高级用法

#### 命令行参数

```bash
python app.py -database_host localhost -database_port 3306
```

#### 环境变量

```bash
export database_host=localhost
export database_port=3306
python app.py
```

#### 自定义配置目录

```python
import os
os.environ["config_dir"] = "/path/to/config"
config = get_config()
```

#### 刷新配置缓存

```python
# 清除缓存，重新读取配置
config = get_config(no_cache=True)
```

#### 链式访问

```python
config = get_config()
# 直接作为属性访问
print(config.database_host)
print(config.database_port)
```

## 🔧 安装方法

### 使用 pip

```bash
# 稳定版本
pip install configs

# 或指定版本
pip install configs==1.4.0
```

### 使用 Pipenv

```bash
# 初始化虚拟环境并安装包
pipenv install configs

# 开发模式安装
pipenv install -e .
```

### 从源码安装

```bash
git clone https://github.com/MikuPy2001/configs.git
cd configs
pip install .
```

## 📋 API 参考

### BaseConfig 类

配置基类，提供以下方法:

- `has(key: str) -> bool`: 检查配置项是否存在
- `get(key: str) -> Any`: 获取配置值
- `set(key: str, value: Any, from_: str = "") -> None`: 设置配置值

### get_config 函数

```python
def get_config(no_cache: bool = False) -> BaseConfig:
    """
    获取配置实例
    
    Args:
        no_cache: 是否清除缓存并重新加载
        
    Returns:
        BaseConfig: 配置实例
    """
```

## ⚠️ 错误处理

如果必需的配置项不存在，会抛出 `ValueError` 异常，并提供详细的配置方法提示:

```python
try:
    value = config.get("required_key")
except ValueError as e:
    print(f"配置错误：{e}")
```

## 📄 许可证和版权

**本软件为专有软件，保留所有权利。**

- ❌ 不得用于商业用途
- ❌ 不得修改、分发、再授权
- ❌ 不得创建衍生作品
- ✅ 仅限个人学习和研究使用

详见 [LICENSE](LICENSE) 和 [COPYRIGHT.md](COPYRIGHT.md) 文件。

如需商业使用或其他用途，请联系作者获取书面授权。

## 📝 更新日志

查看 [CHANGELOG.md](CHANGELOG.md) 了解所有版本的详细变更

### 最新版本 (1.4.0 - 2025-03-03)
- 全面忽略 `_` 开头的私有变量访问
- 增强封装性和安全性

[查看所有版本历史](CHANGELOG.md)

## 👤 作者

**MikuPy2001**

GitHub: [@MikuPy2001](https://github.com/MikuPy2001)  
Email: 794126318@qq.com

感谢所有为这个项目做出贡献的人!

---

<div align="center">

**如果觉得有用，请给个 ⭐️ 支持!**

[GitHub](https://github.com/MikuPy2001/configs) | [PyPI](https://pypi.org/project/configs/) | [CHANGELOG](CHANGELOG.md)

</div>
