前言

 Poetry 是 Python 中用于依赖管理和打包的工具。它最强大的功能是打包与分发，第一次通读peotry官方文档后，给我的感觉是peotry与Pipenv他俩差不多呀，我甚至还感觉peotry不如Pipenv，因为它在进行应用项目的依赖管理的时候，无法像Pipenv那样通过Pyenv自动安装python解释器，而是显性的指定Python解释器。经过一些简单的实践与探索我才体会到peotry的强大，并为自己浅薄的见解感到惭愧。在这里我将对Poetry 安装与基本命令、依赖管理、打包与发布这几个阶段进行实践的简单记录，以便日后复盘。

基本概念理解

1. 打包（Build）：把你的 Python 代码、依赖和元数据（比如版本、作者、说明）打包成一个可分发的格式（wheel 或 sdist）。
2. 发布（Publish）：把打包好的文件上传到 PyPI 或私有仓库。
3. 依赖管理：安装、锁定和管理项目所需的第三方库。
4. 在 Python 项目中，如果你想把自己的代码发布到 PyPI（让别人可以 pip install 安装），通常需要做打包与分发这两件事儿。

Poetry 与 Pipenv 的主要区别

总结

• 如果咱的目标主要是应用项目的依赖管理，Pipenv会更方便。
• 如果你想做库的发布、环境可复现、符合现代 Python 标准，Poetry 更强。
• Poetry不能自动安装Pyenv的Python解释器是设计选择，它希望开发者显式管理 Python，而不是Poetry自动决定。

Poetry 安装与基本命令

1. Poetry的安装与配置

zsh
# 安装 Poetry（pipx 或官方推荐方式）
pipx install poetry
# 回退稳定版本（目前2.XX版本存在一些bug让我吃了点苦头😡）
pipx install "poetry==1.8.3" --force

# Zsh 启用 Tab 补全功能
poetry completions zsh > ~/.zfunc/_poetry
# 查看~/.zshrc配置文件中是否存在一下命令，若没有请添加
fpath+=~/.zfunc
autoload -Uz compinit && compinit

# 更新 Poetry
pipx upgrade poetry

# 删除 Poetry
pipx uninstall poetry

# 创建项目
poetry new my_project  
poetry init  # 也可用现有项目

# 查看虚拟环境列表，注意只有在创建项目的目录下方能生效
poetry env list

2. Poetry 项目初始化于目录结构介绍

1. 创建新的初始化项目

zsh
# 创建新的初始化项目，名为“poetry-demo”
poetry new poetry-demo

# 查看目录结构
tree demo-project1 -a
# 项目目录结构如下
demo-project1
├── pyproject.toml
├── README.md
├── src
│   └── demo_project1
│       └── __init__.py
└── tests
    └── __init__.py

4 directories, 4 files

zsh
poetry new demo-project
Command '['/Users/jingwei/.pyenv/shims/python', '-EsSc', 'import sys; print(sys.executable)']' returned non-zero exit status 127.

zsh
export PATH="$HOME/.pyenv/shims:$PATH"

zsh
/Users/jingwei/.pyenv/shims/python

zsh
poetry new demo-project --python=/Library/Frameworks/Python.framework/Versions/3.11/bin/python3.11

创建项目的同时，项目中会自动生成pyproject.toml 是 Poetry 项目的核心配置文件，该文件的用途是依赖管理、构建、打包、发布：

zsh
# 查看pyproject.toml文件内容
nano pyproject.toml

[project]
name = "demo-project1"
version = "0.1.0"
description = ""
authors = [
    {name = "JingWei",email = "qi.zhang010711@gmail.com"}
]
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
]

[tool.poetry]
packages = [{include = "demo_project1", from = "src"}]


[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"

zsh
python = "^3.13"

pyproject.toml 配置说明

2. 初始化现有项目

zsh
# 进入现有项目目录(我的已有项目名称为PeotryDemo)，初始化项目
cd PeotryDemo
poetry init

# 查看目录结构
tree PeotryDemo -a
# 项目目录结构如下
PeotryDemo
├── .idea
│   ├── .gitignore
│   ├── inspectionProfiles
│   │   ├── profiles_settings.xml
│   │   └── Project_Default.xml
│   ├── misc.xml
│   ├── modules.xml
│   ├── PeotryDemo.iml
│   └── workspace.xml
├── main.py
└── pyproject.toml

3 directories, 9 files

在进行初始化的过程中，存在以下交互过程，整理如下：

1. poetry init 提示语详解

2. 依赖配置

3. 开发依赖

4. 结果确认

5. 交互配置完毕后，展示最终配置好后的pyproject.toml文件

zsh
[project]
name = "poetrydemo"                    # 包名（小写，最终写回默认）
version = "0.1.0"                       # 项目版本
description = "验证已有项目初始化"        # 项目描述
authors = [
    {name = "JingWei",email = "qi.zhang010711@gmail.com"}
]
license = {text = "MIT"}                # 许可证
readme = "README.md"                    # README 文件
requires-python = ">=3.11"              # Python 版本约束
dependencies = [                        # 运行依赖
    "requests (>=2.32.5,<3.0.0)"
]

[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]   # 构建依赖
build-backend = "poetry.core.masonry.api"  # 构建后端

Poetry 虚拟环境管理

Pipenv/venv和Poetry在虚拟环境的“进入方式”上有一些差异：

• Pipenv：pipenv shell 会直接进入虚拟环境，并在命令行前显示 (project-name-xxxx) 前缀。
• venv：source venv/bin/activate 同样会修改 PS1，在命令行前显示 (venv)。
  也就是说在上述两种工具激活虚拟环境即进入虚拟环境，但是Poetry 2.0则不同，激活与进入是分开的。

1. Poetry环境激活与创建

1. poetry 1.8.XX版本

zsh
## 进入项目目录，显式的激活虚拟环境(所用的py解释器为系统的最高版本解释器)
poetry shell

## 切换虚拟环境：若想指定py解释器，请修改pyproject.toml中的解释器版本之后，指定解释器激活环境，激活命令如下：
poetry env use /Users/jingwei/.pyenv/versions/3.10.7/bin/python3.10

## 查看虚拟环境信息
poetry env info

## 显示虚拟环境所有列表
poetry env list

## 显示虚拟环境绝对路径
poetry env list --full-path

## 退出虚拟环境
exit

## 查看py版本（未显性激活可查看）
poetry run python -V

## 删除虚拟环境
1.可以直接删除虚拟环境文件夹
2.通过poetry env remove命令删除
poetry env remove python3

2. poetry 2.XX版本

zsh
## 进入项目目录，执行
poetry env activate 
## 复制输出的 source .../bin/activate 命令，手动执行一次
source .../bin/activate
## 退出虚拟环境
deactivate
## 彻底退出并关掉窗口
exit

2. Poetry依赖包管理

zsh
# poetry add 安装依赖包
## 安装最新版本的requests
poetry add requests
poetry add requests@2.30  # 精确锁死 2.30（不会自动更新到 2.31/2.32），poetry update无法升级
poetry add requests@^2.30  # 允许 2.x 的所有更新（直到 <3.0）
poetry add requests@~2.30  # 允许 2.30.x 更新，但不能到 2.31
poetry add requests@>=2.30,<3.0  # 手工指定范围（等价于 ^2.30）
## 指定为开发依赖，会写到pyproject.toml中的[tool.poetry.dependencies]区域
poetry add pytest --dev

# poetry install 安装pyproject.toml文件中的依赖
## 安装pyproject.toml文件中的全部依赖
poetry install
## 仅安装非development环境的依赖，一般部署时使用
poetry install --no-dev

## 更新所有锁定版本的依赖包(慎用)：开发时用 update，线上部署用 install（保证可复现环境）
poetry update
## 更新指定依赖包
poetry update numpy
## 卸载依赖包
poetry remove numpy
## 查看可以更新的依赖
poetry show --outdated
## 查看项目安装的依赖
poetry show
## 以树形结构查看项目安装的依赖关系
poetry show --tree

Poetry 项目构建及发布

 本次上传，选择TestPYPi进行测试项目的构建与发布，在此之前需提前注册好账号并创建 API Token。

zsh
## 项目打包
poetry build
## 在本地配置 Poetry 使用这个API Token，写入当前项目目录下的本地配置文件，不会影响其他项目，也不会写入全局用户配置。
poetry config pypi-token.testpypi <你的token> --local
## 发布项目打包文件
poetry publish -r testpypi

zsh
HTTP Error 403: Forbidden | b"<html>\n <head>\n  <title>403 The user 'LB6666' isn't allowed to upload to project 'poetry-demo'.

zsh
Username/Password authentication is no longer supported. Migrate to API Tokens or Trusted Publishers instead

参考文章

Python依赖管理及打包利器-Poetry
poetry官方文档