setting-up-python-libraries

Python 库项目设置

快速开始

使用以下结构创建一个新库：

my-library/
├── src/my_library/
│   ├── __init__.py
│   └── py.typed
├── tests/
├── pyproject.toml
├── Makefile
├── .pre-commit-config.yaml
└── .github/workflows/ci.yml

使用 src/ 布局，防止意外导入开发代码。

核心配置

如需完整模板，请参阅：

• PYPROJECT.md - 包含所有工具配置的完整 pyproject.toml
• CI.md - GitHub Actions 和 pre-commit 设置
• MAKEFILE.md - Makefile 自动化模式

最简 pyproject.toml

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "my-library"
version = "0.1.0"
description = "What it does"
readme = "README.md"
requires-python = ">=3.10"
license = "MIT"  # SPDX expression
dependencies = []

[project.optional-dependencies]
dev = ["pytest>=7.0", "ruff>=0.1", "mypy>=1.0"]

[tool.setuptools.packages.find]
where = ["src"]

必备命令

# Setup
uv sync --extra dev
pre-commit install

# Daily workflow
ruff check src tests        # Lint
ruff format src tests       # Format
pytest                      # Test
mypy src                    # Type check

保持本地检查与 CI 一致

CI 最常见的失败原因不是 Bug，而是某项检查在本地通过、在 CI 中失败（反之亦然），因为两者运行的命令不同。遵循以下两条规则，可以避免一整类“本地绿、CI 红”（以及主分支长期变红）的问题：

1. make lint 必须只读，绝不能使用 --fix。 运行 ruff check --fix 的 lint 目标会修改文件，而且几乎总是以 0 退出，因此已有的问题会悄悄留在分支上，而 CI 中只读的 ruff check 却会报红。仅在 format 和 pre-commit 钩子中使用 --fix。make lint 应运行 CI 执行的完全相同命令。

2. CI（以及 make lint）也必须检查格式。 ruff check 和 ruff format 是不同的工具：通过 Linter 检查并不代表格式正确。两项都要设为必检，否则格式偏差会被合入，或导致分支意外变红：

ruff check src tests          # lint rules
ruff format --check src tests # formatting — REQUIRED, not implied by ruff check

Makefile 和 CI 应检查相同的路径（如果 examples/、docs/ 等目录包含 Python 代码，也要将它们加入检查范围）——本地范围较窄，会导致 CI 检查的目录中问题不断累积。在 [tool.ruff.lint] 下配置 ruff（不要使用已弃用的顶层 select/ignore），并保持 requires-python 与 [tool.ruff] target-version 一致，避免 ruff 对不支持的版本应用升级规则。

对于覆盖率，建议在 CI 日志中使用终端报告（--cov-report=term-missing）运行 pytest --cov，而不是上传到第三方服务——这样检查流程就不依赖外部账户、令牌或网络。

关键决策

选择	建议	原因
布局	src/	尽早发现打包问题
构建后端	setuptools	成熟，兼容性广
Linter	ruff	速度快，可替代 flake8+isort+black
Python 版本范围	>=3.10	不要固定具体版本
依赖	尽量精简	将可选依赖移至 extras

检查清单

Project Setup:
- [ ] src/ layout with py.typed marker
- [ ] pyproject.toml (not setup.py)
- [ ] Makefile with dev/test/lint/format (lint read-only, no --fix)
- [ ] `make lint` runs the exact `ruff check` + `ruff format --check` CI runs
- [ ] Build-gating tools pinned (linter, formatter, toolchain, test runner) so upstream releases don't flip green/red on unrelated PRs
- [ ] .pre-commit-config.yaml
- [ ] .github/workflows/ci.yml
- [ ] README.md, LICENSE, CHANGELOG.md
- [ ] .gitignore

辅助脚本

创建新的项目结构：

python scripts/create_project.py my-library --author "Name" --license MIT

--license 接受 SPDX 标识符（默认值为 MIT）；对于 MIT 和 BSD-3-Clause，会生成 LICENSE 文件。

了解更多

此技能基于 Will McGinnis 撰写的《高质量 Python 库开发指南》。如需深入了解，请参阅以下文章：

• 定义库范围
• 依赖管理
• 为项目选择许可证
• pyproject.toml 详解