初次使用 python poetry 包管理模块踩坑

注: 本文不讨论常规的 poetry 使用方法, 只讨论国内开发者在使用 poetry 时可能遇到的一系列问题, 并提供本人踩坑后的解决方法.

poetry new, poetry init 在哪个目录下生成?

结论: poetry new 在未创建项目时使用, poetry init 在已有项目中使用.

poetry new

poetry new 在未创建项目时使用, poetry 将引导你完成项目创建.

假设我们在 D:\workspace\plaground 创建了一个名叫 “poetry-demo” 的项目:

D:\workspace\plaground>poetry new poetry-demo

创建完成后, 你的项目如下:

D:\workspace\playground\poetry-demo
|- poetry_demo  # poetry 会帮你将包名调整为下划线格式.
|               # 请在该目录下编写你的业务逻辑.
    |- __init__.py
|- tests  # 测试模块.
    |- __init__.py
    |- test_poetry_demo.py
|- pyproject.toml  # poetry 用于管理项目的 all-in-one 配置文档.
|- README.rst  # 读我文档.

poetry init

假设我们已有一个项目是:

D:\workspace\myproject
|- documents
|- myproject
    |- __init__.py
    |- calculation.py
    |- main.py
    |- parser.py
    |- validation.py
    |- ...
|- CHANGELOG.txt
|- README.md

则在 “D:\workspace\myproject” 目录下运行 poetry init. poetry 将引导你创建 “pyproject.toml” 文件.

不过, 大家的项目结构可能并非如上图这般. 例如长这样:

D:\workspace\myproject
|- main.py
|- README.md

能简单就简单, 能简略就简略, 有时候只是为了写一个功能单一的小模块, 甚至希望文件夹打包发给对方就能用, 不太在意依赖缺失或版本不匹配引起的报错风险.

这种情况其实不需要重量级的项目管理和依赖管理. poetry 能发挥的作用是有限的.

当然对于需要负责正规的, 复杂的项目的开发人员来说, 一个好的目录组织结构是非常重要的. 对此有以下示范可供参考:

• [https://github.com/psf/requests]
• [https://github.com/feeluown/FeelUOwn]
• …

poetry add <package> 遭遇 “[ConnectionError]”

假设我们在 pyproject.toml 中配置了清华镜像, 还是出现 ConnectionError.

...

# 添加清华镜像
[[tool.poetry.source]]
name = "tsinghua"
url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple/"

...

报错:

原因:

根据这个 issue 得知, [[tool.poetry.source]] 仅对部分环节有效, 在某些步骤 (如 resolve dependencies...) poetry 仍然使用的是 pypi url, 而我们国内访问不了或者连接超时, 就引起了报错.

解决方法:

加一个 default 参数:

[[tool.poetry.source]]
name = "tsinghua"
url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple/"
default = true  # 添加一个 default 参数, 使 poetry 的默认回调行为都调用到这个清华镜像上.

参考:

• https://github.com/python-poetry/poetry/issues/559
• https://python-poetry.org/docs/repositories/#disabling-the-pypi-repository

什么时候使用 ‘poetry.lock’, 什么时候不使用?

先说结论: 多数人以及要发布模块到 pypi 的人不需要 poetry.lock; 通过 Version Control 进行协作的开发团队以及对他机部署环境要求非常严格的人则需要放入 poetry.lock.

poetry.lock 的意义在于, 它会彻底 “锁死” 项目依赖的版本, 比如我们在 pyproject.toml 中要求的依赖版本是 requests = "^2.24.0", 那么哪怕 requests 的作者后面发布了 2.24.1, 使用 poetry.lock 安装时仍会选择安装 2.24.0 版本. 因此, poetry.lock 帮助我们彻底杜绝因依赖的版本的微小变化而产生的任何不确定性.

补充说明:

• 如需使用 poetry.lock, 请将它伴随项目一起打包发布, 在执行 poetry install 时它会优先查找 lock 文件.
• 你可以通过 poetry update 来更新所有依赖到最新版本, 同时 poetry.lock 也会锁定到新的依赖版本.
• 当 pyproject.toml 中所列的依赖与 poetry.lock 不匹配时, poetry install 会中断并提示该错误.

参考:

• https://python-poetry.org/docs/basic-usage/

---

深入阅读

• Poetry 依赖版本号详解: https://python-poetry.org/docs/dependency-specification/
• 版本号迭代规范 ("为什么一般初始项目的版号是 0.1.0"): https://semver.org/lang/zh-CN/