Metadata-Version: 2.4
Name: TATamis-configs
Version: 1.5.0
Summary: 配置文件管理工具 - 支持 INI、JSON、环境变量、命令行参数等多种配置来源
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# TATamis-configs

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

[![PyPI version](https://badge.fury.io/py/TATamis-configs.svg)](https://badge.fury.io/py/TATamis-configs)
[![Python Versions](https://img.shields.io/pypi/pyversions/TATamis-configs.svg)](https://pypi.org/project/TATamis-configs/)
[![Version](https://img.shields.io/badge/version-1.5.0-blue.svg)](CHANGELOG.md)

## 📖 简介

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

**当前版本**: 1.5.0 (2026-08-03)

## ✨ 功能特性

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

## 📦 安装

### 使用 pip

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

# 或指定版本
pip install TATamis-configs==1.5.0
```

### 使用 Pipenv

```bash
pipenv install TATamis-configs
```

### 从源码安装

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

### 可选依赖

为了获得更好的 JSON 支持（包括注释），建议安装 json5：

```bash
pip install json5
```

安装后，配置文件将自动支持 JSON5 格式（包括注释、尾随逗号等扩展语法）。

## 💻 代码使用

### 基本使用

```python
from configs import get_config

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

# 读取配置值
value = config.key
```

### 💡 最佳实践

#### 使用模式

```python
def 示例函数():
    config = get_config()  # 在需要配置的函数开头获取最新配置，不要将其传给其他函数
    value = config.key     # 应当将需要使用的参数立即取出，而不是等待需要的时候再调用
```

> 如果参数不存在，`config.key` 将会抛出异常，库已经在异常里输出了友好提示，用于提示用户填写配置。

#### 动态键名

```python
value = config.get("key" + i)  # 如果参数是动态拼接的，可以直接调用 get
# 实际上 config.key 也是调用的 config.get("key")
```

#### 检查可选配置

```python
if config.has("key"):
    print("激活特殊功能")
```

#### 刷新缓存

```python
config = get_config(no_cache=True)  # 在需要的时候，可以选择重新从硬盘读取配置
```

#### 错误实践

```python
if not config.has("key"):
    value = DEFAULT  # 这是错误实践，你不应当帮用户兜底
```

#### 设置配置值

```python
config.set("key", "value")
```

> 从设计上来说，config 是只读的。如果需要设置，也提供设置方法，但是一般情况下，你应该让用户写到 config 文件里。

### 自定义配置目录

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

### ⚠️ 错误处理

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

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

## 📝 配置文件

### 配置文件示例

#### 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
export database_host=localhost
export database_port=3306
python app.py
```

### 命令行参数

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

### 📋 API 参考

#### get_config 函数

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

#### 继承 BaseConfig（高级用法）

如果需要自定义配置加载顺序或多语言错误提示，可以继承 `BaseConfig` 实现自己的配置类：

```python
from configs import BaseConfig

class MyConfig(BaseConfig):
    def __init__(self):
        super().__init__()
        # 按需调用加载方法，先调用的会被后调用的覆盖
        self._from_env()          # 加载环境变量
        self._from_ini("app.ini") # 加载 INI 文件
        self._from_json("app.json") # 加载 JSON 文件
        self._from_args()         # 加载命令行参数

    def get(self, key):
        # 可重写 get 实现自定义错误提示（如多语言）
        return super().get(key)
```

> 库内部的 `_InteriorConfig` 就是这样实现的，详见 [configs.py](configs/configs.py#L221-L273)。

## 🔨 开发命令

项目使用 Pipenv 管理开发依赖和命令。首先需要安装 Pipenv：

```bash
pip install pipenv
```

然后可以使用以下命令进行开发：

### 代码质量检查

运行 pylint 进行代码静态检查，使用 `.pylintrc` 配置文件：

```bash
pipenv run pylint
```

这会检查 `configs/` 目录下的所有 Python 文件，确保符合项目的编码规范。

### 运行测试套件

运行 pytest 执行所有测试用例：

```bash
pipenv run pytest
```

带覆盖率报告的测试：

```bash
pipenv run pytest --cov=configs tests/
```

### 构建项目

构建 Python 分发包（wheel 和 source distribution）：

```bash
pipenv run build
```

构建产物会输出到 `dist/` 目录。

### 上传到 PyPI

将构建好的包上传到 PyPI 仓库：

```bash
pipenv run upload
```

**注意**: 上传前需要配置好 `.pypirc` 文件或设置相应的环境变量（TWINE_USERNAME、TWINE_PASSWORD）。

## 📄 许可证和版权

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

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

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

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

参与贡献请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。

## 📝 更新日志

详见 [CHANGELOG.md](CHANGELOG.md)

## 👤 作者

**MikuPy2001**

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

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

---

<div align="center">

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

感谢 [DeepSeek](https://www.deepseek.com/) 提供的鼎力支持。

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

</div>
