playbook/docs/python/configuration.md

Python 配置清单（Configuration）

本文件用于把 Python 工具配置“汇总说明”到一个可读入口。

注意：本 Playbook 将可复制模板放在 templates/python/；在目标项目落地时，这些文件通常需要复制到项目根目录（工具默认查找位置）：

• pyproject.toml
• .flake8
• .pylintrc
• .pre-commit-config.yaml
• .editorconfig
• .vscode/settings.json

1) pyproject.toml

模板文件：templates/python/pyproject.toml

• tool.black
  • line-length = 80
  • target-version = ['py313']（按项目 Python 版本调整）
• tool.isort
  • profile = "google"
  • line_length = 80
  • known_third_party / known_first_party：按项目维护
• tool.mypy
  • python_version = "3.13"（按项目调整）
  • ignore_missing_imports = true（对第三方二进制/无类型库更友好）
• tool.pytest.ini_options
  • 测试发现与参数（若项目引入 tests/ 会自动生效）

2) .flake8

模板文件：templates/python/.flake8

• max-line-length = 80
• docstring-convention = google
• 与 black 冲突的规则已屏蔽（例如 E203、W503）

3) .pylintrc

模板文件：templates/python/.pylintrc

• 命名风格：snake_case / PascalCase 等（对齐 Google Python 风格）
• max-line-length = 80
• init-hook 将项目根目录加入 sys.path（便于本地运行与检查；如项目不需要可移除）

4) .pre-commit-config.yaml

模板文件：templates/python/.pre-commit-config.yaml

• 基础文本检查：尾随空格、文件末尾换行、YAML/TOML 基础校验
• Python：black、isort、flake8

5) .editorconfig

模板文件：templates/python/.editorconfig

• Python：4 空格缩进、行宽 80
• 通用：UTF-8、LF、去尾随空格、文件末尾换行

6) .vscode/settings.json

模板文件：templates/python/.vscode/settings.json

• 保存即格式化、80 列标尺、默认使用 Black formatter、按需组织 import