Python 打包发布

借鉴 pypa/sampleproject (5k⭐) + Python Packaging Guide。

pyproject.toml（现代标准）

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

[project]
name = "my-package"
version = "0.1.0"
description = "简短描述"
readme = "README.md"
requires-python = ">=3.11"
license = {text = "MIT"}
authors = [{name = "郑鑫", email = "xxx@xxx.com"}]
keywords = ["ai", "agent"]
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
]

dependencies = [
    "requests>=2.28",
    "pydantic>=2.0",
]

[project.optional-dependencies]
dev = ["pytest", "ruff", "build"]
all = ["my-package[dev]", "redis", "fastapi"]

[project.urls]
Homepage = "https://github.com/user/my-package"
Repository = "https://github.com/user/my-package.git"

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

[tool.ruff]
line-length = 100
target-version = "py311"

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-v --cov=src"

目录结构

my-package/
├── src/
│   └── my_package/
│       ├── __init__.py
│       ├── core.py
│       └── utils.py
├── tests/
│   ├── __init__.py
│   └── test_core.py
├── pyproject.toml
├── README.md
├── LICENSE
└── .gitignore

构建发布

# 安装构建工具
pip install build twine

# 构建
python -m build
# → dist/my_package-0.1.0.tar.gz
# → dist/my_package-0.1.0-py3-none-any.whl

# 发布到 PyPI
twine upload dist/*

# 发布到 Test PyPI（先测试）
twine upload -r testpypi dist/*

版本管理（Semantic Versioning）

MAJOR.MINOR.PATCH

MAJOR：不兼容的 API 变更（1.0 → 2.0）
MINOR：向后兼容的新功能（1.0 → 1.1）
PATCH：向后兼容的 Bug 修复（1.0.0 → 1.0.1）

0.x.x：开发阶段，API 不稳定
1.0.0：第一个稳定版本

入口点（CLI 命令）

[project.scripts]
mycli = "my_package.cli:main"

# src/my_package/cli.py
def main():
    print("Hello from CLI!")

# pip install 后用户直接敲 mycli 就能运行

依赖锁定

# 开发时：宽松版本
dependencies = ["requests>=2.28"]

# 部署时：锁定具体版本
pip freeze > requirements.txt
# 或
uv pip compile pyproject.toml -o requirements.txt

常见问题

Q: src/ 布局还是平铺？
A: src/ 布局更规范，避免意外导入本地代码

Q: setup.py 还是 pyproject.toml？
A: pyproject.toml（2026年了，用新的）

Q: 要不要上传到 PyPI？
A: 开源项目要，私有项目用 git+https 安装即可