pyproject.toml 发布 Python 软件包

1. 典型的项目结构

在开始配置之前，请确保你的文件组织结构清晰。一个标准的包结构如下：

my_package_project/
├── src/
│ └── my_package/ # 你的源代码目录
│ ├── __init__.py
│ └── core.py
├── tests/ # 测试代码
├── pyproject.toml # 核心配置文件
├── README.md # 项目说明
├── LICENSE # 许可证
└── .gitignore # 忽略构建产物

2. 编写 pyproject.toml

这是整个流程的心脏。它主要由三个部分组成：构建系统、项目元数据和工具配置。

A. 构建系统 ([build-system])

这告诉安装程序（如 pip）使用哪个后端来构建你的包。目前最常用的是 setuptools，但你也可以选择 hatchling、flit 或 poetry-core。

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

B. 项目元数据 ([project])

这里定义了包的名称、版本、作者以及它在 PyPI 上的展示信息。

[project]
name = "my_package_fancy_name"
version = "0.1.0"
description = "一个非常酷的示例包"
readme = "README.md"
requires-python = ">=3.8"
license = {text = "MIT"}
authors = [
{name = "你的名字", email = "yourname@example.com"},
]
keywords = ["sample", "package", "guide"]
# 项目依赖
dependencies = [
"requests >= 2.28.0",
"numpy",
]

[project.urls]
"Homepage" = "https://github.com/yourusername/my_package"
"Bug Tracker" = "https://github.com/yourusername/my_package/issues"

3. 构建软件包

在发布之前，你需要将代码“打包”成两种格式：sdist（源码分发版）和 wheel（二进制分发版）。

pip install –upgrade build

python -m build

注意：运行完成后，你会看到一个新的 dist/ 文件夹。里面包含了一个 .tar.gz 文件和一个 .whl 文件。这就是你要上传到 PyPI 的“成品”。

4. 发布到 PyPI

我们将使用 twine 工具将包安全地上传到 Python Package Index (PyPI)。

第一步：注册并获取 Token

第二步：上传

pip install –upgrade twine

python -m twine upload –repository testpypi dist/*

python -m twine upload dist/*