25.2 库发布：打包发布到 PyPI、setup.py/pyproject.toml 配置

当你写好一个 Python 库或工具，想让别人通过 pip install your-package 直接安装使用时，就需要把它打包并发布到 PyPI（Python Package Index）上。现代 Python 打包主要依赖两个配置文件：传统的 setup.py 和更推荐的 pyproject.toml。

打包前的准备

  my_project/
  ├── src/
  │   └── mypackage/         # 实际代码包
  │       ├── __init__.py
  │       └── core.py
  ├── tests/                 # 测试代码
  ├── README.md              # 项目说明
  ├── LICENSE                # 开源许可证
  ├── pyproject.toml         # 打包配置（推荐）
  └── (或 setup.py)          # 传统配置方式

关键文件说明
README.md：项目介绍、安装方式、简单用法，会显示在 PyPI 页面上。
LICENSE：明确授权方式，不写就默认保留所有权利，用户不敢用。
pyproject.toml / setup.py：告诉 pip 这个包叫什么、版本多少、依赖有哪些。

使用 pyproject.toml（现代标准，推荐）

Python 官方现在推荐用 pyproject.toml 统一管理包信息、构建系统和依赖。不需要单独写 setup.py 或 setup.cfg。

一个典型的最小配置：

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.backends._legacy:_Backend"

[project]
name = "mypackage"
version = "0.1.0"
description = "一个简单的示例包"
readme = "README.md"
license = {text = "MIT"}
authors = [{name = "你的名字", email = "you@example.com"}]
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]
requires-python = ">=3.8"
dependencies = [
    "requests>=2.25.0",
    "click>=8.0"
]

[project.optional-dependencies]
dev = ["pytest", "black"]

[project.urls]
Homepage = "https://github.com/you/mypackage"
Issues = "https://github.com/you/mypackage/issues"

[tool.setuptools.package-dir]
"" = "src"

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

关键字段解释
[build-system]：指定用什么工具构建，一般就用 setuptools。
[project]：包的基本信息，name 是给 pip 安装的名字，dependencies 是运行时依赖。
[project.optional-dependencies]：可选依赖分组，比如 pip install mypackage[dev] 会多装 pytest 和 black。
[tool.setuptools]：因为用的构建后端是 setuptools，这里告诉它从 src 目录下找包。

传统方式：setup.py（仍广泛使用）

如果你维护的是老项目，或需要兼容更复杂的情况，仍然可以用 setup.py。配置通常写在 setup.cfg 或直接在 setup.py 里调用 setuptools.setup()。

最简 setup.py 示例：

from setuptools import setup, find_packages

setup(
    name="mypackage",
    version="0.1.0",
    packages=find_packages(where="src"),
    package_dir={"": "src"},
    install_requires=[
        "requests>=2.25.0",
        "click>=8.0"
    ],
    python_requires=">=3.8",
)

发布到 PyPI 的操作步骤

安装打包工具：

   pip install --upgrade pip setuptools wheel build twine

构建分发包：

在项目根目录执行：

   python -m build

这会在 dist/ 目录下生成 .tar.gz 源码包和 .whl wheel 包。

上传到 PyPI：

先注册 PyPI 账号（pypi.org ），然后获取 API token。然后上传：

   python -m twine upload dist/*

会提示你输入 token（用户名用 token，密码粘贴 token）。上传成功后，几分钟内别人就可以通过 pip install your-package 安装了。

测试发布：如果怕正式出问题，可以先用 Test PyPI（https://test.pypi.org）试点，确认无误后再推到正式版。

常见注意事项

版本号：遵循语义化版本（主版本.次版本.修订号），每次发布要递增，PyPI 不允许覆盖已发布的文件。
依赖控制：只在 dependencies 里写必不可少的，不要把 black、pytest 这种开发工具放进去。可选依赖分组可以避免用户安装不必要的东西。
README 内容：好的 README 直接决定别人会不会用你的包。至少写清楚“这个包做什么”“怎么安装”“最简单的示例”。
许可证：必须确定，否则你发布的内容别人不敢合法使用。

通过标准化的打包发布流程，你的代码就能从本地的一个脚本，变成一个对全球开发者开放的工具，真正进入 Python 生态的流转。