使用 uv 发布 Python 包到 PyPI 教程

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

前提条件

1. 安装 Python（建议 3.8 或以上版本）。
2. 安装 uv：

   pip install uv
   

3. 拥有一个 PyPI 账户（在 PyPI.org 注册）。
4. （可选）如果你需要发布到 TestPyPI，可以在 test.pypi.org 注册。

步骤 1：创建项目结构

1. 创建一个新目录作为你的项目根目录：

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

2. 初始化项目：

   uv init
   

   uv init 会生成一个基本的项目结构，包含以下文件：

   • pyproject.toml：项目的元数据和依赖配置文件。
   • src/my_python_package/__init__.py：包的初始化文件。

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

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

   • name：包的名称，需在 PyPI 上唯一。
   • version：包的版本号，建议遵循 SemVer。
   • description：包的简短描述。
   • authors：作者信息。
   • readme：指向 README 文件（稍后创建）。
   • license：许可证类型（如 MIT、Apache-2.0 等）。

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

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

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

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

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

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

uv add requests

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

步骤 3：测试你的包

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

   from my_python_package import hellodef test_hello():assert hello() == "Hello from my-python-package!"
   

2. 安装测试依赖（如 pytest）：

   uv add --dev pytest
   

3. 运行测试：

   uv run pytest
   

步骤 4：构建包

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

uv build

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

步骤 5：配置 PyPI 凭据

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

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

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

步骤 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 中的依赖版本范围合理。