使用 Poetry 将 Python 包发布到 PyPI | 指南

# 将 Python 包发布到 PyPI：使用 Poetry 自动化流程

将自己的 Python 包发布到 PyPI 仓库是希望复用代码的开发者必不可少的一步。Poetry 工具通过管理依赖项和构建工件大大简化了这一过程。本指南详细介绍了项目准备、环境设置以及包发布，包括使用 API 令牌和可选依赖项。

账户设置和 API 令牌生成

第一步是在官方 PyPI 网站上创建账户。注册后，为发布时的身份验证生成 API 令牌。在账户仪表板中，转到 API 令牌部分，点击 Generate API token。为令牌指定名称并选择其范围。对于新项目，账户级令牌（Entire account）很合适，因为你还没有注册任何包。重要提示： 创建后立即复制生成的令牌——它不会再次显示。

生成过程包括：

• 登录 PyPI 账户
• 转到 API 令牌管理部分
• 指定令牌名称和范围
• 确认创建并保存令牌值

Poetry 将使用此令牌进行安全发布，而无需你的登录名和密码。请像对待密码一样安全存储它。

使用 Poetry 初始化项目

创建项目根目录并设置虚拟环境：

python3 -m venv .venv
source .venv/bin/activate

通过 pip 安装 Poetry 并运行初始化：

pip install poetry
poetry init

在交互模式下，提供基本参数：包名称、版本、描述、作者以及支持的 Python 版本。生成的 pyproject.toml 文件中的主要字段：

• name — PyPI 中的唯一包名称（必须与代码目录的 snake_case 名称匹配）
• version — 包的语义化版本
• python — 支持的解释器版本范围
• readme — 描述文件路径
• packages — 源代码目录指针

初始化后，创建代码目录（将 name 中的连字符替换为下划线），并添加基本文件结构。

项目结构和配置

典型项目结构如下所示：

my-package/
├── LICENSE
├── poetry.lock
├── pyproject.toml
├── README.md
└── my_package/
    ├── __init__.py
    └── core.py

至关重要的是，pyproject.toml 中的包名称必须与代码目录名称匹配。例如，对于 name = "my-package"，目录必须命名为 my_package。在 __init__.py 文件中，推荐导入主要函数以便使用。

core.py 中的示例实现：

PREPEND_STR = 'prepend_'

def modify_str(string: str) -> str:
    return f'{PREPEND_STR}{string}'

务必添加许可证文件（推荐 MIT）和带有功能描述的 README.md。在发布前使用 poetry lock 锁定依赖项。

构建和发布包

在上传到仓库前，构建工件：

poetry build

此命令会在 dist/ 目录中生成源代码分发包（.tar.gz）和 wheel 文件（.whl）。接下来，配置 Poetry 使用 API 令牌：

poetry config pypi-token.pypi pypi-XXXXXXXX

将 pypi-XXXXXXXX 替换为你的令牌。现在发布：

poetry publish

如果成功，你将看到上传到 PyPI 的确认。你可以通过在 PyPI 网站搜索或本地安装包来验证发布：

pip install my-package

处理可选依赖项

要实现可选组件（通过 pip install package[extra] 安装），按如下方式配置 pyproject.toml：

[tool.poetry.dependencies]
python = "^3.10"
pydantic = {version=">=1.9", optional = true}

[tool.poetry.extras]
pydantic = ["pydantic"]

这里，pydantic 依赖项被标记为可选（optional = true），extras 部分创建了一个名为 pydantic 的组，包括此库。用户可以使用 pip install my-package[pydantic] 安装额外组件。

关键要点

• 严格匹配 pyproject.toml 中的包名称与代码目录名称（连字符 → 下划线）
• 始终包含许可证和详细的 README.md 以建立用户信任
• 使用 API 令牌而非登录名/密码进行安全发布
• 对于可选依赖项，正确配置 dependencies 和 extras 部分
• 在发布前，使用 poetry build 验证构建

— Editorial Team