# Python 项目模板

一个标准化的 Python 项目开发模板，集成了配置管理、日志系统和 Pydantic 数据验证。

## 特性

- 🔧 **配置管理**: 基于 YAML 的配置文件，使用 Pydantic 进行数据验证
- 📝 **日志系统**: 集成 Loguru，支持控制台和文件输出，自动轮转和压缩
- 🏗️ **标准结构**: 清晰的项目目录结构，便于维护和扩展
- ✅ **类型安全**: 使用 Pydantic 模型确保配置数据的类型安全
- 🔄 **单例模式**: 日志管理器采用单例模式，确保全局唯一实例

## 项目结构

```
├── config/                 # 配置文件
│   └── config.yaml        # 主配置文件
├── examples/              # 使用示例
│   ├── example_config_loader.py
│   └── example_logger.py
├── src/                   # 源代码
│   ├── core/             # 核心功能模块
│   ├── models/           # 数据模型
│   │   ├── __init__.py
│   │   └── config_models.py  # 配置数据模型
│   ├── modules/          # 业务模块
│   └── utils/            # 工具类
│       ├── config_loader.py  # 配置加载器
│       └── logger.py         # 日志管理器
├── tmp/                   # 临时文件
│   └── log/              # 日志文件
├── main.py               # 程序入口
├── pyproject.toml        # 项目配置
└── README.md
```

## 快速开始

### 环境要求

- Python >= 3.12
- uv (推荐) 或 pip

### 安装依赖

使用 uv (推荐):
```bash
uv sync
pre-commit install # 可选
```

或使用 pip:
```bash
pip install -r requirements.txt
```

### 运行项目

```bash
python main.py
```

## 核心组件

### 1. 配置管理

配置系统使用 Pydantic 进行数据验证，确保配置的正确性。

```python
from src.utils.config_loader import get_config_loader

# 获取配置加载器
loader = get_config_loader()

# 验证并加载配置
config = loader.validate_config()

# 获取日志配置
log_config = loader.get_log_config()
```

### 2. 日志系统

基于 Loguru 的日志系统，支持多种输出格式和自动轮转。

```python
from src.utils.logger import get_logger

# 获取日志记录器
logger = get_logger("MODULE_NAME")

# 记录日志
logger.info("这是一条信息日志")
logger.error("这是一条错误日志")
```
## 开发

### 添加新模块

1. 在 `src/modules/` 下创建新的业务模块
2. 在 `src/core/` 下添加核心功能
3. 在 `src/utils/` 下添加工具函数

### 添加新配置

1. 在 `src/models/config_models.py` 中定义新的配置模型
2. 在 `config/config.yaml` 中添加对应配置
3. 更新配置加载器以支持新配置

### 日志使用规范

- 使用有意义的模块标签: `get_logger("API")`, `get_logger("DATABASE")`
- 合理使用日志级别: DEBUG < INFO < WARNING < ERROR < CRITICAL
- 记录关键操作和错误信息

### 代码风格

遵循 PEP 8 代码风格指南，保持代码整洁和一致性。基于ruff进行代码检查和格式化。


## 作者

wds @ (wdsnpshy@163.com)