Poetry 安装和使用指南

环境准备和安装

使用 Conda 创建新环境（推荐）：

# 创建新的 Python 环境
conda create -n poetry-env python=3.10
# 激活环境
conda activate poetry-env

安装 Poetry：

pip install poetry

验证安装：

poetry --version

Poetry 常用命令

项目管理

# 创建新项目
poetry new project-name

# 在现有项目初始化
poetry init

# 显示当前项目信息
poetry show

# 检查 pyproject.toml 格式
poetry check

依赖管理

# 安装所有依赖
poetry install

# 添加依赖
poetry add package-name
poetry add package-name==1.2.3  # 指定版本
poetry add package-name@^1.2.3  # 使用版本约束
poetry add --dev pytest  # 添加开发依赖

# 移除依赖
poetry remove package-name

# 更新依赖
poetry update  # 更新所有依赖
poetry update package-name  # 更新特定包

# 显示已安装的包
poetry show  # 列出所有包
poetry show --tree  # 显示依赖树
poetry show --latest  # 显示最新可用版本

环境管理

# 创建/激活虚拟环境
poetry shell

# 运行命令
poetry run python script.py
poetry run pytest

# 查看环境信息
poetry env info

# 列出所有虚拟环境
poetry env list

构建和发布

# 构建包
poetry build

# 发布到 PyPI
poetry publish
poetry publish --build  # 构建并发布

# 配置仓库
poetry config repositories.testpypi https://test.pypi.org/legacy/

版本管理

# 查看当前版本
poetry version

# 更新版本
poetry version patch  # 0.1.0 -> 0.1.1
poetry version minor  # 0.1.1 -> 0.2.0
poetry version major  # 0.2.0 -> 1.0.0

使用 Poetry 发布 Python 包到 PyPI

1. 项目初始化

如果是新项目：

poetry new my-package

如果是现有项目，在项目根目录：

poetry init

2. 配置 pyproject.toml

确保 pyproject.toml 包含必要的元数据：基本上都poetry帮管理，只需要每次修改增加版本号和必须数据指定比如： include = ["xlfill2pdf/fonts/.ttf", "docs/.png"]

[tool.poetry]
name = "my-package"
version = "0.1.0"
description = "Your package description"
authors = ["Your Name <your.email@example.com>"]
readme = "README.md"
packages = [{include = "my_package"}]
repository = "https://github.com/username/my-package"
documentation = "https://my-package.readthedocs.io"
keywords = ["keyword1", "keyword2"]
license = "MIT"

[tool.poetry.dependencies]
python = "^3.7"

[tool.poetry.group.dev.dependencies]
pytest = "^7.0"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

3. 创建 PyPI 账号

前往 PyPI 注册账号
前往 Test PyPI 注册账号（可选，用于测试）
可能需要 Two factor authentication (2FA)认证，需要下载微软 Authenticator 或 Google Authenticator 等应用生成 token，推荐使用微软 Authenticator
获取 API tokens

4. 配置 Poetry 认证

# 配置正式 PyPI
poetry config pypi-token.pypi your-pypi-token

# 配置测试 PyPI（可选）
poetry config repositories.testpypi https://test.pypi.org/legacy/
poetry config pypi-token.testpypi your-testpypi-token

# 发布前建议写测试代码多跑几次
poetry run pytest -s -v

5. 构建包

poetry build

这会在 dist/ 目录下创建两个文件：

.tar.gz 文件（源码分发版本）
.whl 文件（构建分发版本）

6. 发布到 TestPyPI（可选但推荐）

poetry publish -r testpypi

测试安装：

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

7. 发布到 PyPI

例子：在这里插入图片描述

poetry publish

或者构建并发布：

poetry publish --build

安装：(上传正式包后, 安装需要等待几分钟, PyPI 可能需要一些时间来处理新包, 使用国内镜像源<清华的镜像源10分钟就能安装>阿里的可能需要二天才能安装)

pip install my-package

8. 版本更新

更新版本号<也可以直接手动修改>：

poetry version patch  # 增加补丁版本 0.1.0 -> 0.1.1
poetry version minor  # 增加次版本号 0.1.1 -> 0.2.0
poetry version major  # 增加主版本号 0.2.0 -> 1.0.0

构建并发布新版本：

poetry publish --build

注意事项

.gitignore 应包含：

dist/
*.egg-info/
__pycache__/

发布前检查清单：

README.md 是否完整
所有依赖是否正确声明
版本号是否正确
测试是否通过
LICENSE 文件是否存在

安全建议：

使用 API tokens 而不是用户名密码
定期更新 token
不要在代码中保存认证信息

常见问题解决

如果发布时遇到 HTTP 403 错误：

检查包名是否已被占用
验证认证信息是否正确
确认版本号是否已存在（不能重复发布相同版本）

如果安装时找不到包：

等待几分钟，PyPI 可能需要一些时间来处理新包
确认包名称是否正确