用poetry管理Python项目

最新推荐文章于 2025-10-11 10:50:03 发布

原创最新推荐文章于 2025-10-11 10:50:03 发布 · 1.3k 阅读

23 ·

CC 4.0 BY-SA版权

文章标签：

#python #poetry

python 专栏收录该内容

259 篇文章

订阅专栏

部署运行你感兴趣的模型镜像

poetry 简介

Poetry 是 Python 的一个依赖管理和打包工具，它可以帮助开发者更方便地管理项目的依赖关系、构建和发布软件包。

在这里插入图片描述

依赖管理方面

精确版本控制：与传统的pip工具相比，Poetry 能够更加精确地管理依赖版本。它使用pyproject.toml文件（这是一个遵循 PEP 518 规范的文件）来记录项目的所有依赖信息。例如，你可以指定一个库的具体版本，如requests==2.31.0，也可以指定一个版本范围，像numpy>=1.20.0,<1.24.0。这有助于确保项目在不同环境下的稳定性，避免因依赖版本的不兼容而出现问题。

依赖隔离：Poetry 为每个项目创建一个独立的虚拟环境，这意味着不同项目可以使用不同版本的相同库，而不会相互干扰。例如，项目 A 可能需要Django 3.0，项目 B 需要Django 4.0，Poetry 可以为这两个项目分别管理它们的依赖，使得它们能够在各自合适的环境中运行。
打包发布方面

构建软件包简单化：当你想要发布你的 Python 项目作为一个可安装的软件包（例如，发布到 PyPI 上供其他人使用）时，Poetry 会让这个过程变得更加容易。它会自动处理项目的元数据（如项目名称、作者、版本等），并根据pyproject.toml文件中的信息构建出符合标准的软件包。

支持多种格式：Poetry 支持构建.whl（wheel）格式和.tar.gz（source distribution）格式的软件包。wheel格式是一种预编译的二进制分发格式，安装速度通常比源码分发格式更快，这使得用户在安装你的项目时能够更加高效。
项目配置方面

集中式配置：所有关于项目的配置，包括依赖、脚本、开发依赖等，都在pyproject.toml文件中进行管理。例如，除了依赖库的信息，你还可以在这个文件中指定测试框架（如pytest）及其相关的配置，以及项目的入口脚本等。这样一来，项目的整个配置一目了然，便于开发者维护和分享项目配置信息。

动态生成setup.py文件（如果需要）：在传统的 Python 项目中，setup.py文件用于项目的安装和分发。Poetry 可以根据pyproject.toml文件中的内容动态生成setup.py文件，这使得在一些需要兼容旧的打包系统的场景下也能够顺利进行项目打包和发布。

使用 Poetry 的基本步骤

安装 Poetry

不同的操作系统有不同的安装方式。在 Linux 和 macOS 上，可以使用官方提供的安装脚本：
```
`curl -sSL https://install.python - poetry.org | python3 -`
# （这个命令会通过网络下载安装脚本并使用 Python 3 来执行安装）。
```
在 Windows 上，可以通过(Invoke - WebRequest - Uri https://install.python - poetry.org - UseBasicParsing).Content | python -（这个命令是在 PowerShell 中执行的安装方式）。
初始化项目

进入你的项目目录后，使用poetry init命令。这个命令会引导你逐步配置项目，如输入项目名称、版本、作者、许可证类型等信息。它还会让你添加项目的初始依赖，你可以手动输入依赖库的名称和版本要求。例如，如果你要创建一个简单的 Web 应用项目，你可能会添加flask作为依赖，并且指定一个合适的版本范围。
添加依赖

要添加新的依赖，可以使用poetry add命令。例如，poetry add requests会将requests库添加到你的项目依赖中，并且 Poetry 会自动解析其依赖关系，下载并安装所有相关的库到项目的虚拟环境中。如果需要添加开发依赖（例如，用于测试或代码格式化的工具），可以使用poetry add --dev pytest（这里以添加pytest作为测试工具为例）。
运行脚本和命令

Poetry 允许你在项目的虚拟环境中方便地运行脚本。例如，如果你有一个main.py脚本，你可以使用poetry run python main.py来运行它。这样可以确保脚本是在项目的虚拟环境中运行，使用正确的依赖版本。
构建和发布项目

当你准备好发布项目时，首先要构建软件包。使用poetry build命令，Poetry 会根据pyproject.toml文件中的信息构建.whl和.tar.gz格式的软件包。之后，如果你有账号并且有权限，可以使用poetry publish命令将项目发布到 PyPI（Python Package Index）上，供其他用户安装和使用。

迁移python项目

首先，祝贺你选择了用于Python项目管理的Poetry。这是一个奇妙的选择，我希望诗歌成为事实上的标准。

现在是告别旧的、简陋的requirements.txt文件的时候了，将您的依赖项转移到Poetry，让它处理所有事情——包括对依赖项进行适当的版本跟踪。

我将假设您已经初始化了您的Poetry项目并拥有pyproject。项目根目录下的Yml文件。如果没有，运行以下命令初始化一个Python项目：

poetry init

现在，从requirements.txt迁移到Poetry就像在Python项目的根目录下运行以下命令一样简单：

poetry add $(cat requirements.txt)

如果你想添加本地开发依赖，在requirements.dev.txt中定义你的依赖，那么你需要运行以下命令：

poetry add --group dev $(cat requirements.dev.txt)

接下来，打开pyproject。你应该看到你的核心依赖项列在[tool. poem .dependencies]下，开发依赖项列在[tool. poem .group.dev.dependencies]下。

[tool.poetry.dependencies]
python = "^3.11"
django = ">=4.2,<4.3"
wagtail = ">=5.1,<5.2"

[tool.poetry.group.dev.dependencies]
pytest = ">=7.4,<7.5"

至此，您已经准备好告别requirements.txt文件，并完全拥抱poetry的力量：

rm requirements.txt
rm requirements.dev.txt

啊，那感觉不是很好吗？

Poetry 的优势和适用场景

优势

环境一致性：通过为每个项目创建独立的虚拟环境并严格管理依赖，Poetry 确保了项目在不同开发环境和生产环境之间的一致性。这减少了因环境差异导致的 “在我机器上可以运行” 的问题。

易于协作：pyproject.toml文件可以被轻松地纳入版本控制系统（如 Git）。当团队成员获取项目代码时，他们可以使用 Poetry 快速地重新创建与原项目相同的开发环境，包括安装正确的依赖版本。

现代化的打包方式：符合 PEP 518 等现代 Python 打包标准，使得项目的打包和发布过程更加规范和高效，与 Python 社区的最佳实践保持一致。
适用场景

开发 Python 库和框架：对于开发供他人使用的 Python 库，Poetry 能够很好地管理库的依赖，方便发布到 PyPI 上。例如，开发一个数据处理库，使用 Poetry 可以确保用户在安装该库时能够正确地获取所有必要的依赖。

Web 应用开发：无论是小型的 Flask 应用还是大型的 Django 项目，Poetry 都可以帮助开发者管理项目的各种依赖，包括数据库驱动、模板引擎等，并且在部署时能够轻松地构建和发布项目。

数据科学项目：在数据科学项目中，往往需要使用多种数据分析和机器学习库。Poetry 可以有效管理这些库的依赖关系，并且在团队协作或共享项目代码时，能够快速搭建一致的开发环境。