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)