使用 uv 工具发布 Python 包到 PyPI 指南

本教程将指导你使用 uv 工具创建一个 Python 包并将其发布到 PyPI。uv 是一个快速、现代的 Python 包管理工具，适合替代传统的 pip 和 setuptools。

前提条件

1. 安装 Python（建议 3.8 或以上版本）。
2. 拥有一个 PyPI 账户（在 PyPI.org 注册）。
3. （可选）如果你需要发布到 TestPyPI，可以在 test.pypi.org 注册。

安装 uv：

pip install uv

步骤 1：创建项目结构

• pyproject.toml：项目的元数据和依赖配置文件。
• src/my_python_package/__init__.py：包的初始化文件。
• name：包的名称，需在 PyPI 上唯一。
• version：包的版本号，建议遵循 SemVer。
• description：包的简短描述。
• authors：作者信息。
• readme：指向 README 文件（稍后创建）。
• license：许可证类型（如 MIT、Apache-2.0 等）。

在 src/my_python_package/__init__.py 中添加一些示例代码：

def hello():
    return "Hello from my-python-package!"

创建 README.md 文件，描述你的项目：

echo "# My Python Package\n\nA simple Python package for demonstration purposes." > README.md

检查 pyproject.toml，确保内容正确。以下是一个示例：

[project]
name = "my-python-package"
version = "0.1.0"
description = "A simple Python package"
authors = [{name = "Your Name", email = "[email protected]"}]
dependencies = []
requires-python = ">=3.8"
readme = "README.md"
license = {text = "MIT"}

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

初始化项目：

首先创建一个新目录作为你的项目根目录：

mkdir my-python-package
cd my-python-package

然后运行 uv init：

uv init

uv init 会生成一个基本的项目结构，包含上述文件。

步骤 2：添加依赖（可选）

如果你的包需要依赖其他库，可以通过 uv 添加：

uv add requests

这会更新 pyproject.toml，在 [project.dependencies] 中添加 requests。

步骤 3：测试你的包

运行测试：

uv run pytest

安装测试依赖（如 pytest）：

uv add --dev pytest

创建一个简单的测试文件 tests/test_hello.py：

from my_python_package import hello

def test_hello():
    assert hello() == "Hello from my-python-package!"

步骤 4：构建包

使用 uv 构建你的包，生成分发文件（wheel 和 source distribution）：

uv build

构建完成后，生成的 .whl 和 .tar.gz 文件会出现在 dist/ 目录中。

步骤 5：配置 PyPI 凭据

1. 获取 PyPI API 令牌：
   • 登录 PyPI.org，进入账户设置。
   • 创建一个新的 API 令牌，选择合适的权限（通常是'上传'权限）。
   • 将生成的令牌复制到 ~/.pypirc 的 password 字段。

创建或编辑 ~/.pypirc 文件，添加 PyPI 和 TestPyPI（可选）的配置：

[distutils]
index-servers = pypi testpypi

[pypi]
username = __token__
password = pypi-<your-api-token>

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = pypi-<your-testpypi-api-token>

步骤 6：发布到 TestPyPI（可选）

在正式发布到 PyPI 前，建议先上传到 TestPyPI 测试：

uv publish --index testpypi

• 检查 TestPyPI 上是否成功上传。

安装并测试你的包：

uv pip install --index-url https://test.pypi.org/simple/ my-python-package

步骤 7：发布到 PyPI

如果 TestPyPI 测试通过，发布到正式 PyPI：

uv publish

• 确认包是否成功上传到 PyPI.org。

测试安装：

uv pip install my-python-package

步骤 8：验证安装

创建一个新的虚拟环境并安装你的包：

uv venv
source .venv/bin/activate # Linux/Mac
# .venv\Scripts\activate # Windows
uv pip install my-python-package

运行 Python 解释器并测试：

import my_python_package
print(my_python_package.hello())

注意事项

• 包名冲突：确保你的包名在 PyPI 上是唯一的。如果包名已被占用，修改 pyproject.toml 中的 name 字段。
• 版本号：每次发布新版本时，更新 pyproject.toml 中的 version 字段。
• 文档：完善 README.md，添加使用说明、安装方法和示例代码。
• 许可证：选择合适的许可证（如 MIT），并添加 LICENSE 文件。
• 安全性：不要在公开代码中存储 PyPI 令牌，建议使用环境变量或 CI/CD 工具（如 GitHub Actions）管理。

常见问题

1. 上传失败：检查 ~/.pypirc 中的令牌是否正确，或者网络连接是否正常。
2. 包名已存在：选择一个新包名或联系 PyPI 管理员。
3. 依赖问题：确保 pyproject.toml 中的依赖版本范围合理。