Python 项目文件组织与工程化实践
Python 项目文件组织与工程化实践
项目结构设计
采用模块化结构是 Python 项目工程化的核心。典型结构如下：
project_name/ ├── src/ # 主代码目录 │ ├── module1/ # 功能模块 │ ├── module2/ │ └── __init__.py # 包初始化文件 ├── tests/ # 单元测试 ├── docs/ # 文档 ├── scripts/ # 辅助脚本 ├── requirements.txt # 依赖列表 └── setup.py # 打包配置src 目录存放核心代码，tests 目录与 src 保持平行结构。每个功能模块应有自己的子目录和init.py 文件。
依赖管理
使用虚拟环境隔离项目依赖：
python -m venv venv source venv/bin/activate # Linux/Mac venv\Scripts\activate # Windows通过 requirements.txt 记录依赖：
flask==2.0.1 pytest>=6.0.0对于复杂项目，建议使用 poetry 或 pipenv 管理依赖：
poetry add pandas # 自动更新pyproject.toml测试框架集成
pytest 是当前主流测试框架。测试文件应以 test_ 开头：
# tests/test_module1.py def test_function(): assert 1 + 1 == 2配置 pytest.ini 文件规范测试行为：
[pytest] python_files = test_*.py norecursedirs = .* venv文档生成
使用 Sphinx 生成专业文档。通过 docstring 编写模块级文档：
"""模块说明 详细描述模块功能和实现细节 """ def func(param): """函数说明 :param param: 参数说明 :return: 返回值说明 """运行 sphinx-quickstart 初始化文档项目，生成 HTML 格式文档。
持续集成
配置 GitHub Actions 实现自动化测试：
# .github/workflows/test.yml name: Tests on: [push] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - run: pip install -r requirements.txt - run: pytest打包发布
使用 setuptools 配置 setup.py：
from setuptools import setup, find_packages setup( name="project", version="0.1", packages=find_packages(where="src"), package_dir={"": "src"}, )构建分发包：
python setup.py sdist bdist_wheel twine upload dist/*代码质量控制
配置 pre-commit 钩子自动检查代码：
# .pre-commit-config.yaml repos: - repo: https://github.com/psf/black rev: 22.3.0 hooks: - id: black集成 flake8 进行风格检查：
# .flake8 [flake8] max-line-length = 88 exclude = .venv日志管理
采用结构化日志配置：
import logging logging.basicConfig( level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s" ) logger = logging.getLogger(__name__)对于生产环境，建议使用 JSON 格式日志：
from pythonjsonlogger import jsonlogger handler = logging.StreamHandler() handler.setFormatter(jsonlogger.JsonFormatter()) logger.addHandler(handler)