python-poetry 工程化规范

1. 项目结构设计：结合传统目录结构，但用Poetry的文件代替setup.py和requirements.txt。
2. Poetry核心功能：依赖管理、虚拟环境、打包发布。
3. 模块化与代码规范：模块划分、代码风格工具。
4. 测试策略：单元测试、集成测试、覆盖率。
5. 文档与协作：README、API文档、版本控制。
6. CI/CD集成：自动化测试和部署。
7. 扩展建议：比如配置管理、日志、异常处理等。

以下是基于最新实践的Python项目工程化结构体系指南，结合Poetry工具链的最佳实践方案：

一、项目结构设计

my_project/
├── pyproject.toml         # Poetry项目配置核心文件
├── poetry.lock            # 精确的依赖版本锁定
├── README.md              # 项目总览文档
├── src/                   # 源代码主目录（替代传统my_project/）
│   └── my_package/
│       ├── __init__.py
│       ├── core/          # 核心业务模块
│       ├── utils/         # 工具类模块
│       └── config.py      # 配置管理
├── tests/                 # 测试套件
│   ├── unit/              # 单元测试
│   └── integration/       # 集成测试
├── docs/                  # 文档系统
│   ├── api/               # 自动生成的API文档
│   └── tutorials/         # 使用教程
├── .github/               # CI/CD配置
│   └── workflows/
│       └── main.yml
├── .pre-commit-config.yaml # 代码提交前检查
└── scripts/               # 辅助脚本

二、Poetry核心实践

1. 依赖管理

   # 生产依赖
   poetry add requests numpy pandas
   # 开发依赖
   poetry add black flake8 pytest --group dev
   # 锁定环境
   poetry lock --no-update
   

2. 虚拟环境管理

   poetry env use 3.10   # 指定Python版本
   poetry shell          # 进入虚拟环境
   poetry run pytest     # 直接执行命令
   

3. 多环境配置

   [tool.poetry.group.dev.dependencies]
   pytest = "^7.2"
   coverage = {version = "^7.0", optional = true}
   
   [tool.poetry.extras]
   test = ["coverage"]
   

三、模块化与代码规范

1. 模块设计原则 • 每个子包不超过500行代码 • 采用「领域驱动设计」划分模块边界 • 通过__all__控制模块暴露接口

2. 代码质量保障

   [tool.black]
   line-length = 88
   target-version = ['py310']
   
   [tool.flake8]
   max-line-length = 88
   exclude = ".venv, __pycache__"
   

四、测试策略

# tests/test_core.py
import pytest
from src.my_package.core import Calculator

class TestCalculator:
    @pytest.mark.parametrize("a,b,expected", [(2,3,5), (-1,1,0)])
    def test_add(self, a, b, expected):
        assert Calculator.add(a, b) == expected

测试执行命令：

poetry run pytest --cov=src --cov-report=html

五、文档与协作

1. 自动化文档生成

   poetry add sphinx --group docs
   sphinx-quickstart docs  # 初始化文档框架
   

2. Git工作流实践

   # .pre-commit-config.yaml
   repos:
   - repo: https://github.com/psf/black
     rev: 22.10.0
     hooks: [{id: black}]
   

六、CI/CD集成

# .github/workflows/main.yml
name: CI
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - uses: actions/setup-python@v4
    - run: pip install poetry
    - run: poetry install --no-root
    - run: poetry run pytest

七、进阶实践建议

1. 配置管理 • 使用pydantic.BaseSettings管理环境变量 • 区分development/production配置模板

2. 打包发布

   poetry build            # 生成wheel包
   poetry publish          # 发布到PyPI
   poetry export -f requirements.txt --output requirements.txt
   

3. 日志管理

   # src/my_package/logging.py
   import logging
   from rich.logging import RichHandler
   
   logging.basicConfig(
       level="INFO",
       format="%(message)s",
       handlers=[RichHandler(show_time=False)]
   )
   

建议结合具体项目需求调整结构，对于大型项目可增加docker/目录存放容器化配置，notebooks/存放数据分析脚本。通过poetry-plugin-export插件可生成传统requirements.txt以兼容旧系统。