Poetry包管理 — Poetry依赖管理与发布¶

# 方法1：官方安装脚本（推荐）
curl -sSL https://install.python-poetry.org | python3 -

# 方法2：用 pipx 安装（隔离安装，不污染系统）
pipx install poetry

# 方法3：用 uv 安装
uv tool install poetry

# 验证安装
poetry --version  # 应该显示 Poetry (version 2.4.x)

# 配置 PATH（如果命令找不到）
# Linux/macOS：
export PATH="$HOME/.local/bin:$PATH"
# 加到 ~/.bashrc 或 ~/.zshrc 中永久生效

# 设置虚拟环境创建在项目目录内（推荐，方便 IDE 识别）
poetry config virtualenvs.in-project true

# 查看所有配置
poetry config --list

# 设置 PyPI 镜像（国内加速）
poetry source add tsinghua https://pypi.tuna.tsinghua.edu.cn/simple/ --priority=primary

# 交互式创建新项目
poetry new my-project
# 生成的目录结构：
# my-project/
# ├── src/                 # 源码目录（Poetry 2.1+ 默认 src 布局）
# │   └── my_project/
# │       └── __init__.py
# ├── tests/
# │   └── __init__.py
# ├── pyproject.toml       # 项目配置文件
# └── README.md

# 在已有项目中初始化
cd existing-project
poetry init  # 交互式生成 pyproject.toml

# 添加依赖（自动更新 pyproject.toml 和 poetry.lock）
poetry add requests           # 添加运行时依赖
poetry add pandas numpy       # 一次添加多个

# 添加开发依赖（只在开发时需要，不会打包发布）
poetry add --group dev pytest pytest-cov  # 测试相关
poetry add --group docs mkdocs           # 文档相关

# 指定版本
poetry add "requests>=2.28,<3.0"  # 版本范围
poetry add requests@latest        # 最新版
poetry add requests@^2.31         # 兼容版本

# 移除依赖
poetry remove requests

# 更新依赖
poetry update              # 更新所有依赖
poetry update requests     # 只更新指定包

# 查看依赖树
poetry show --tree  # 树形显示所有依赖关系

# 安装所有依赖（根据 pyproject.toml）
poetry install

# 只安装生产依赖（不装开发依赖）
poetry install --without dev

# 在虚拟环境中运行命令
poetry run python main.py    # 运行 Python 脚本
poetry run pytest            # 运行测试

# 进入虚拟环境的 shell
poetry shell  # 激活虚拟环境

# 查看虚拟环境信息
poetry env info        # 显示环境路径等信息
poetry env list        # 列出所有环境
poetry env remove 3.11 # 删除指定 Python 版本的环境

[tool.poetry]
name = "my-project"           # 项目名（发布到 PyPI 时用的）
version = "0.1.0"             # 版本号
description = "我的项目描述"    # 项目描述
authors = ["张三 <zhangsan@example.com>"]  # 作者
license = "MIT"               # 许可证
readme = "README.md"          # README 文件
packages = [{include = "my_project", from = "src"}]  # 包位置

[tool.poetry.dependencies]
python = ">=3.10,<4.0"       # Python 版本要求
requests = "^2.31"            # ^ 表示兼容更新：>=2.31, <3.0
pandas = "~2.1"               # ~ 表示补丁更新：>=2.1, <2.2
numpy = ">=1.24"              # >= 表示最低版本

[tool.poetry.group.dev.dependencies]
pytest = "^9.0"               # 开发依赖：测试框架
ruff = "^0.15"                # 开发依赖：代码检查
mypy = "^1.10"                # 开发依赖：类型检查

[tool.poetry.group.docs.dependencies]
mkdocs = "^1.6"               # 文档依赖

[tool.poetry.scripts]
my-cli = "my_project.cli:main"  # 定义命令行入口

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

^2.31.0  → >=2.31.0, <3.0.0   # 兼容更新（最常用）
~2.31.0  → >=2.31.0, <2.32.0  # 补丁更新
>=2.31   → >=2.31.0           # 最低版本
==2.31.0 → 精确版本            # 锁定版本
*        → 任意版本            # 不限制（不推荐）

# 构建包（生成 dist/ 目录）
poetry build
# 生成两种格式：
# dist/my_project-0.1.0.tar.gz     # 源码包
# dist/my_project-0.1.0-py3-none-any.whl  # wheel 包

# 发布到 PyPI
poetry publish           # 需要 PyPI 账号
poetry publish --dry-run # 模拟发布（不真的上传）

# 发布到私有仓库
poetry config repositories.private https://my-pypi.example.com/
poetry publish -r private

# 一步完成构建和发布
poetry publish --build

# Poetry 2.0 开始支持 PEP 621 标准格式
# 可以用 [project] 替代 [tool.poetry]

[project]
name = "my-project"
version = "0.1.0"
description = "项目描述"
requires-python = ">=3.10"
dependencies = [
    "requests>=2.31",
    "pandas>=2.1",
]

[project.optional-dependencies]
dev = ["pytest>=9.0", "ruff>=0.15"]

# PEP 735 依赖组（Poetry 2.2+ 支持）
[dependency-groups]
test = ["pytest>=9.0", "pytest-cov>=7.0"]
docs = ["mkdocs>=1.6"]

# 依赖组可以嵌套，一个组包含另一个组的依赖
[tool.poetry.group.test.dependencies]
pytest = "^9.0"

[tool.poetry.group.ci.dependencies]
# CI 组包含 test 组的所有依赖，再加上自己的
# 通过 include 实现

# ===== 项目管理 =====
poetry new project-name     # 创建新项目
poetry init                 # 在已有目录初始化
poetry install              # 安装依赖
poetry update               # 更新依赖
poetry lock                 # 只更新 lock 文件

# ===== 依赖管理 =====
poetry add package          # 添加依赖
poetry add -G dev package   # 添加到 dev 组
poetry remove package       # 移除依赖
poetry show                 # 列出已安装包
poetry show --tree          # 树形显示依赖

# ===== 环境管理 =====
poetry shell                # 进入虚拟环境
poetry run cmd              # 在虚拟环境执行命令
poetry env info             # 环境信息
poetry env list             # 列出所有环境
poetry env remove python    # 删除环境

# ===== 构建发布 =====
poetry build                # 构建包
poetry publish              # 发布到 PyPI
poetry version patch        # 版本号 +0.0.1
poetry version minor        # 版本号 +0.1.0
poetry version major        # 版本号 +1.0.0

# ===== 配置 =====
poetry config --list                    # 查看配置
poetry config virtualenvs.in-project true  # 环境在项目内
poetry source add name url              # 添加包源