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 (推荐):

uv sync
pre-commit install # 可选

或使用 pip:

pip install -r requirements.txt

运行项目

python main.py

核心组件

1. 配置管理

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

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 的日志系统，支持多种输出格式和自动轮转。

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)