代码收藏家 Python包高效发布指南：uv、pyproject.toml与twine的无缝集成！
在 Python 开发中，将你的代码打包并发布到 PyPI 是一个重要的里程碑。这不仅可以让更多人使用你的代码，还能帮助你在开源社区中建立声誉。本文将详细介绍如何使用现代工具链——uv、pyproject.toml 和 twine——高效地完成这一过程。通过这些工具，你可以轻松管理项目生命周期，并确保发布过程顺利无误。
一、为什么选择 uv、pyproject.toml 和 twine？
uv 是一个现代的 Python 项目管理工具，它集成了包管理、虚拟环境管理、依赖锁定等功能，能够简化项目的开发和发布流程。pyproject.toml 是 Python 的标准配置文件，用于定义项目的构建和依赖信息，是现代 Python 包的必备文件。twine 是一个专门用于上传 Python 包到 PyPI 的工具，它简单易用且功能强大。结合使用这些工具，可以让你的发布流程更加高效和现代化。
二、准备工作
1. 安装必要的工具
首先，确保你已经安装了 uv 和 twine。如果尚未安装，可以通过以下命令进行安装：
# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# 或者使用 pip 安装 uv
pip install uv
# 安装 twine
pip install twine
2. 创建项目结构
创建一个标准的 Python 包项目结构。假设你的包名为 my_package，项目结构如下：
my_package/
├── pyproject.toml
├── README.md
├── LICENSE
└── src/
└── my_package/
├── __init__.py
└── module.py
pyproject.toml 是项目的配置文件。README.md 是项目的说明文档。LICENSE 是项目的许可证文件。src/my_package/ 是你的包代码目录。3. 配置 pyproject.toml
在 pyproject.toml 文件中，填写项目的元数据和构建配置。以下是一个示例配置：
[project]
name = "my_package"
version = "0.1.0"
description = "A simple example package"
readme = "README.md"
authors = [{ name = "Your Name", email = "your.email@example.com" }]
requires-python = ">=3.11"
dependencies = []
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
name 是你的包名。version 是包的版本号。description 是包的简短描述。readme 指定了包的说明文档文件。authors 是包的作者信息。requires-python 指定了包支持的 Python 版本。dependencies 是包的依赖列表。[build-system] 部分定义了包的构建系统，这里使用了 hatchling。提示：如果你的包有额外的依赖项，可以在 dependencies 中列出它们。例如：
dependencies = [
"requests >= 2.28.1",
"numpy"
]
三、构建包
在项目根目录下运行以下命令来构建包：
uv build
uv 会根据 pyproject.toml 中的配置生成包文件。构建完成后，你可以在 dist/ 文件夹中找到生成的 .whl 和 .tar.gz 文件。
最佳实践：在发布之前，建议运行测试以确保代码质量。你可以在 pyproject.toml 中添加测试依赖，并使用 uv 运行测试：
[tool.uv.dependencies]
test = ["pytest"]
然后运行：
uv test
四、上传包到 PyPI
1. 使用 twine 上传
使用 twine 将包上传到 PyPI：
twine upload dist/*
在上传时，你需要输入 PyPI 的用户名和密码，或者使用 API Token。如果你已经生成了 API Token，可以通过以下方式上传：
twine upload --repository-url https://upload.pypi.org/legacy/ --username __token__ --password YOUR_PYPI_TOKEN dist/*
提示：为了安全起见，建议使用 API Token 而不是用户名和密码。
2. 使用 uv 上传
如果你更倾向于使用 uv 来上传包，可以运行以下命令：
uv publish --token YOUR_PYPI_TOKEN
或者通过环境变量设置 Token：
export UV_PUBLISH_TOKEN=YOUR_PYPI_TOKEN
uv publish
最佳实践：在上传之前，建议先将包上传到 TestPyPI 进行测试。你可以使用以下命令上传到 TestPyPI：
twine upload --repository testpypi dist/*
然后在测试环境中安装并测试你的包：
pip install --index-url https://test.pypi.org/simple/ my_package
五、验证包
在上传包之后，建议进行验证，确保包可以正常安装和使用。
1. 测试安装
在隔离环境中测试包是否可以正常安装和导入：
uv run --with my_package --no-project -- python -c "import my_package"
如果一切正常，你将看到输出，表明包已成功导入。
2. 检查 PyPI 页面
登录到 PyPI 官网，搜索你的包名，查看是否已经成功发布。
六、后续维护
1. 更新版本
如果需要更新包，只需修改 pyproject.toml 中的版本号（例如从 0.1.0 改为 0.1.1），然后重复构建和上传步骤。
最佳实践：遵循语义化版本号（Semantic Versioning），例如 MAJOR.MINOR.PATCH。例如：
1.0.0：主版本号（MAJOR）在不兼容的 API 修改时增加。1.1.0：次版本号（MINOR）在向下兼容的功能性新增时增加。1.1.1：修订号（PATCH）在向下兼容的问题修正时增加。2. 添加分类器
如果你不想将包发布到 PyPI，可以在 pyproject.toml 中添加分类器：
[project]
classifiers = ["Private :: Do Not Upload"]
这将防止包被误上传。
七、总结
通过使用 uv、pyproject.toml 和 twine，你可以高效地将 Python 包发布到 PyPI。uv 提供了强大的项目管理功能，pyproject.toml 确保了项目的标准化配置，而 twine 则专注于包的上传。这种工具链结合了现代 Python 开发的最佳实践，能够帮助你更轻松地管理和发布你的 Python 包。
希望这篇文章能帮助你顺利完成 Python 包的发布。如果你有任何问题或需要进一步的说明，请随时告诉我。
作者：蜗牛沐雨
