python 开发规范

• 介绍
• 代码风格
• 项目结构
• 依赖管理
  • ruff 和 pre-commit
  • Makefile
• 测试
• 文档
• 版本控制

介绍

本文档总结了 Python 项目的开发规范和最佳实践，涵盖代码风格、项目结构、依赖管理、测试等方面，旨在帮助开发者编写高质量的 Python 代码。

代码风格

• 遵循 PEP 8 规范，使用 black 格式化代码。
• 使用 flake8 检查代码质量，确保无语法错误和风格问题。
• 函数和变量命名应具有描述性，遵循蛇形命名法（snake_case）。

项目结构

• 使用标准的 Python 包结构，包含 setup.py 或 pyproject.toml 文件。
• 将源代码放在 src/ 目录下，测试代码放在 tests/ 目录下。
• 使用虚拟环境隔离项目依赖。

依赖管理

ruff 和 pre-commit

ruff 是一个用 Rust 写的 超快 Python 代码工具，集 Linter（静态检查）+ 导入排序 + 语法升级 + 格式化 于一体。

pre-commit 是一个管理 Git 钩子（hooks）的工具。让你在 git commit / git push 之前自动跑一堆检查/修复，不合格就拦截提交。

ruff 常常和 pre-commit 一起使用，在 git commit 前进行静态检查和格式化。常用在开发模式下进行代码检查。

配置 ruff 和 pre-commit：

[tool.ruff.lint]
select = ["E4", "E7", "E9", "F", "TID"]

[tool.ruff.lint.flake8-tidy-imports]
ban-relative-imports = "parents"

[dependency-groups]
dev = [
    "pre-commit>=4.3.0",
    "ruff>=0.12.12",
]

在根目录创建pre-commit配置文件 .pre-commit-config.yaml： 使用pre-commit必须激活 uv run pre-commit install安装 git 钩子。见 Makefile 中的make i命令。

fail_fast: false

exclude: |
  (?x)^(
    .vscode/.*|
    helm/.*|
    uv.lock
  )$
repos:
  - repo: https://github.com/abravalheri/validate-pyproject
    rev: v0.24.1
    hooks:
      - id: validate-pyproject
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v6.0.0
    hooks:
      - id: check-added-large-files
      - id: check-builtin-literals
      - id: check-case-conflict
      - id: check-docstring-first
      - id: check-executables-have-shebangs
      - id: check-json
      - id: check-merge-conflict
      - id: check-toml
      - id: check-yaml
      - id: detect-private-key
      - id: end-of-file-fixer
      - id: mixed-line-ending
        args: [--fix=lf]
      - id: trailing-whitespace
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.12.12
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

Makefile

Makefile 用来简化常用命令的执行，例如安装依赖、运行测试等。例如：make i（make 默认执行第一个）安装依赖，make dev启动开发服务器。

.PHONY: i dev prod update build clean publish test hooks-run hooks-remove hooks-update check

i:
 uv sync --all-extras --all-packages && uv run pre-commit install

dev:
 uv run python -c "__import__('knowledge_base.app.__main__').app.__main__.dev()" $(filter-out dev,$(MAKECMDGOALS)) || echo shutdown

prod:
 uv run --no-sync knowledge-base-app prod $(filter-out prod,$(MAKECMDGOALS))

update:
 uv sync --all-extras --all-packages -U $(filter-out update,$(MAKECMDGOALS))

build:
 uv build --all $(filter-out build,$(MAKECMDGOALS))

clean:
 rm -rf .venv && rm -rf dist/ && rm -rf build/ && rm -rf .ruff_cache/

publish:
 uv publish ./dist/* --index gitea $(filter-out publish,$(MAKECMDGOALS))

test:
 uv run pytest

hooks-run:
 uv run pre-commit run --all-files

hooks-remove:
 uv run pre-commit uninstall $(filter-out hooks-remove,$(MAKECMDGOALS))

hooks-update:
 uv run pre-commit autoupdate $(filter-out hooks-update,$(MAKECMDGOALS))

check: test hooks-run

%:
 @:

测试

• 编写单元测试和集成测试，确保代码功能正确。
• 使用 pytest 作为测试框架。
• 集成持续集成（CI）工具，在每次提交时自动运行测试。

文档

• 使用 Sphinx 或 MkDocs 编写项目文档。
• 在代码中添加适当的注释和文档字符串（docstrings）。
• 提供使用示例和 API 文档，方便用户理解和使用项目。

版本控制

• 使用 Git 进行版本控制，遵循 Git Flow 工作流程。
• 编写清晰的提交信息，描述所做的更改。
• 定期合并分支，保持代码库的整洁和一致性。