使用 uv 发布 Python 包到 PyPI 教程
本教程将指导你使用 uv 工具创建一个 Python 包并将其发布到 PyPI。uv 是一个快速、现代的 Python 包管理工具，适合替代传统的 pip 和 setuptools。
前提条件
- 安装 Python（建议 3.8 或以上版本）。
- 拥有一个 PyPI 账户（在 PyPI.org 注册）。
- （可选）如果你需要发布到 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 中添加一些示例代码：
defhello():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" 初始化项目：
uv init uv init 会生成一个基本的项目结构，包含以下文件：
创建一个新目录作为你的项目根目录：
mkdir my-python-package cd my-python-package 步骤 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 deftest_hello():assert hello()=="Hello from my-python-package!"步骤 4：构建包
使用 uv 构建你的包，生成分发文件（wheel 和 source distribution）：
uv build 构建完成后，生成的 .whl 和 .tar.gz 文件会出现在 dist/ 目录中。
步骤 5：配置 PyPI 凭据
- 获取 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）管理。
常见问题
- 上传失败：检查
~/.pypirc中的令牌是否正确，或者网络连接是否正常。 - 包名已存在：选择一个新包名或联系 PyPI 管理员。
- 依赖问题：确保
pyproject.toml中的依赖版本范围合理。
