Python开发-poetry的初始化

有了AI,一切皆可从头开始

code
让AI提供一个合适的开发流程
作者

Adopa

日期

2025年03月09日

Modified

2025年03月09日

Keywords

python, poetry

poetry重置

1) 背景

python开发使用cookiecutter建立列项目文件夹，使用poetry inti初始化了项目，使用poetry install进行了安装，但是发现poetry install把虚拟环境安装在了项目文件夹之外。

2) 用户需求

现在请删除poetry inti， poetry install生成的文件和虚拟环境，重新开始potry的的init和install流程，确保虚拟项目在项目文件夹之内。方 便后续维护。

3) 输出要求

1. 输出带注释的shell脚本，方便后期维护更新，2.输出用&&连接的一行命令，方便本次复制粘贴到终端运行。3 . 确保输出的简洁明了，不要啰嗦，不要总结，不要重复说明。

4) 解决方案

配置典型的开发环境

1) 背景

计划通过poetry进行项目的管理，需要了解在poetry init，install中如何把典型的常用开发工具如black，flake8，pytest提前安装好，避免后期单独安装。

2) 用户需求

把python开发中典型的现代开发工具安装设置到poetry init，install流程中。

3) 输出要求

1. 输出带注释的shell脚本，方便后期维护更新，2.输出用&&连接的一行命令，方便本次复制粘贴到终端运行。3 . 确保输出的简洁明了，不要啰嗦，不要总结，不要重复说明。

4) 输出要求

Code 
#!/bin/bash
# 强制配置虚拟环境到项目目录
poetry config virtualenvs.in-project true --local
# 交互式初始化项目（手动确认基本信息）
poetry init
# 安装常用开发工具到dev依赖组
poetry add --group dev black flake8 pytest

poetry初始配置中的选择

1) 背景:

poetry初始配置中提示用户配置相关的main dependencies

Would you like to define your main dependencies interactively? (yes/no) [yes] yes You can specify a package in the following forms: - A single name (requests): this will search for matches on PyPI - A name and a constraint (requests@^2.23.0) - A git url (git+https://github.com/python-poetry/poetry.git) - A git url with a revision (git+https://github.com/python-poetry/poetry.git#develop) - A file path (../my-package/my-package.whl) - A directory (../my-package/) - A url (https://example.com/packages/my-package-0.1.0.tar.gz)

2) 用户需求:

请按main dependencies配置的最佳实践，推荐最低配置和典型配置

3) 输出要求:

输出要求：1.按poetry要求的输出回复。2 . 输出带注释的shell脚本，方便后期cli配置，3. 确保输出的简洁明了，不要啰嗦，不要总结，不要重复说明。

4) 典型解决方案：

Code 
#!/bin/bash
# 最低配置（跳过所有主依赖配置）
poetry init --no-interaction  # 使用默认值并跳过依赖配置

# 典型配置（常用基础依赖）
poetry init --no-interaction \
  --dependency "requests@^2.31.0" \    # HTTP客户端
  --dependency "loguru@^0.7.2" \       # 结构化日志
  --dependency "python-dotenv@^1.0.0"  # 环境变量加载


# 典型配置-oneline cli
poetry init --no-interaction --dependency "requests@^2.31.0" --dependency "loguru@^0.7.2" --dependency "python-dotenv@^1.0.0"

如何正确运行poetry add

1) 背景

运行poetry init后，继续运行poetry add --group dev black flake8 pytest, 终端出现错误提示:

Poetry could not find a pyproject.toml file in /Users/zhuquanming/Documents/pythondev/ai_helper or its parents

2) 用户需求

请确认poetry init ,poetry add ,poetry install 之间正确的关系

3) 输出要求

输出要求：1.按终端错误提示，给出正确的后续步骤。2 . 输出带注释的shell脚本，方便后期cli配置，3. 确保输出的简洁明了，不要啰嗦，不要总结，不要重复说明。

4) 典型解决方案

Code 
# poetry add --group dev black flake8 pytest

# Poetry could not find a pyproject.toml file in /Users/zhuquanming/Documents/pythondev/ai_helper or its parents
# 确保poetry init正常运行后生成
# 或者先完成非初始init在进行题啊见
poetry init --no-interaction && poetry add --group dev black flake8 pytest

readme问题

当使用其它的工具建立项目文件夹结构时可能出现这个问题：

pyproject.toml中配置了readme，指向实际的README, 这就是配置开发的强大之处。

修改pyproject.toml

---
[project]
readme="README.rst"
---

运行成功

典型配置

“poetry config的最佳实践，给出典型的常用的命令”

Code 
#!/bin/bash
# poetry 核心配置最佳实践命令集

# 强制虚拟环境创建在项目目录内（推荐项目级配置）
poetry config virtualenvs.in-project true --local

# 设置全局PyPI镜像源（示例使用清华源）
poetry config repositories.pypi https://pypi.tuna.tsinghua.edu.cn/simple/

# 启用并行安装加速（默认已开启，可显式配置）
poetry config installer.parallel true

# 配置私有仓库认证（替换your-repo-name和token）
poetry config http-basic.your-repo-name username your-token

# 显示当前配置
poetry config --list
Code 
❯ poetry env info --path
~/Documents/pythondev/ai_helper/.venv

开发期间的运维

一键安装package

Code 
# 常用单行命令集合
PACKAGE="package@^1.2.3" && poetry add $PACKAGE && poetry update && poetry show --tree

常用命令

Code 
#!/bin/bash
# Poetry 依赖运维管理最佳实践命令集

# 添加生产依赖（带版本约束）
poetry add "package@^1.2.3"  # ^表示允许次版本和补丁版本更新

# 添加开发依赖到独立分组
poetry add --group dev pytest-coverage  # 新增测试覆盖率工具

# 更新全部依赖到最新兼容版本
poetry update  # 更新所有依赖并刷新lock文件

# 更新指定依赖包
poetry update requests numpy  # 仅更新指定包

# 移除依赖包
poetry remove deprecated-pkg  # 从项目配置中移除

# 列出已安装依赖树
poetry show --tree  # 查看依赖层级关系

# 检查过时依赖
poetry show --outdated  # 列出可升级的依赖

# 安装时排除开发依赖（生产环境）
poetry install --no-dev  # 仅安装运行时依赖

# 导出requirements.txt（兼容其他工具）
poetry self add poetry-plugin-export # 必须首先执行此命令一次，亲测
poetry export -f requirements.txt --output requirements.txt --without-hashes

进阶管理操作：

  1. 依赖版本锁定管理
Code 
# 仅刷新lock文件不安装（适用于CI/CD）
poetry lock --no-update

# 同步依赖到lock文件版本
poetry install --sync
  1. 多环境配置
Code 
# 添加可选依赖组
poetry add --group docs mkdocs  # 文档相关依赖

# 按组安装依赖
poetry install --with docs  # 安装主依赖+文档组依赖
  1. 依赖冲突解决
Code 
# 强制保留当前版本（谨慎使用）
poetry add "conflict-pkg==1.2.3"  # 固定特定版本

# 依赖降级操作
poetry add "problematic-pkg@<=2.0.0"  # 设置版本上限

最佳实践建议：

  1. 使用语义化版本控制符：

    • ^1.2.3 = 1.x.x (x >=2.3)

    • ~1.2.3 = 1.2.x (x >=3)

    • >=1.2.3,<2.0.0 = 明确版本范围

  2. 依赖组分类建议：

    # 典型分组结构
poetry add --group dev pytest   # 开发工具
poetry add --group test selenium  # 测试专用
poetry add --group docs sphinx  # 文档生成

  3. 定期维护操作：

    bash

    Copy

    # 每周执行依赖健康检查
poetry update --dry-run  # 预览更新
poetry show --outdated  # 列出过时依赖
poetry check  # 验证项目配置有效性

分组实践

环境分组添加

Code 
#!/bin/bash
# Poetry 依赖分组最佳实践命令集

# 1. 核心分组配置（必需组）
poetry add --group dev black flake8  # 开发工具（代码格式化/lint）
poetry add --group test pytest coverage  # 测试框架及覆盖率
poetry add --group types mypy types-requests  # 类型检查工具

# 2. 可选功能分组（按需安装）
poetry add --group docs (--optional) mkdocs mkdocs-material  # 文档系统
    # You can only add optional dependencies to the main group
    
poetry add --group notebooks --optional jupyter ipykernel  # Jupyter支持
poetry add --group aws --optional boto3 aws-lambda-powertools  # 云服务扩展

# 使用精确语义化版本控制
poetry add --group security "cryptography@>=3.4.7,<4.0.0"
Code 
# 3. 生产环境安装（仅主依赖）
poetry install --no-dev  # 部署时使用

# 4. 按需安装组合
poetry install --with docs,notebooks  # 开发+文档+notebook环境

# CI/CD 典型安装命令
poetry install --with test --sync  # 仅安装主依赖+测试组，同步lock文件

# 查看特定组的依赖关系
poetry show --tree --only docs

pyproject.toml的典型设置