397 lines
18 KiB
Markdown
397 lines
18 KiB
Markdown
# Python 诗歌:使包和 venv 管理变得容易
|
||
|
||
> 原文:[https://python.land/virtual-environments/python-poetry](https://python.land/virtual-environments/python-poetry)
|
||
|
||
poem 是 Python 的一个包管理器。这是一个有多种用途的工具。它:
|
||
|
||
* 方便地管理您的[虚拟环境](https://python.land/virtual-environments/virtualenv)(无需手动创建)
|
||
* 是安装 Python 包的一个很好的工具(你不再需要 [pip install](https://python.land/virtual-environments/installing-packages-with-pip)
|
||
* 帮助您管理依赖关系
|
||
* 可用于构建可与全世界共享的 Python 包
|
||
|
||
本文仔细研究了 Python 诗歌。我们将首先正确地安装它，然后我将向您展示如何用诗歌创建项目，并管理您的虚拟环境和项目依赖关系。
|
||
|
||
目录
|
||
|
||
|
||
|
||
* [为什么是诗歌？](#Why_Poetry "Why Poetry?")
|
||
* [安装 Python 诗歌](#Installing_Python_Poetry "Installing Python Poetry")
|
||
* [用 Python 诗歌开始一个项目](#Starting_a_project_with_Python_Poetry "Starting a project with Python Poetry")
|
||
* [用 Python 诗安装和移除包](#Install_and_remove_packages_with_Python_Poetry "Install and remove packages with Python Poetry")
|
||
* [使用项目的虚拟环境](#Using_your_projects_virtual_environment "Using your project’s virtual environment")
|
||
* [更新您的依赖关系](#Updating_your_dependencies "Updating your dependencies")
|
||
* [构建和发布包](#Building_and_publishing_packages "Building and publishing packages")
|
||
* [诗是互通的](#Poetry_is_interoperable "Poetry is interoperable")
|
||
* [诗歌命令备忘单](#A_cheat_sheet_of_Poetry_commands "A cheat sheet of Poetry commands")
|
||
* [诗歌 vs Pipenv](#Poetry_vs_Pipenv "Poetry vs Pipenv")
|
||
* [了解更多信息](#Learn_more "Learn more")
|
||
* [结论](#Conclusion "Conclusion")
|
||
|
||
|
||
|
||
## 为什么是诗歌？
|
||
|
||
与使用 pip 或其他包管理器相比，诗歌有几个优点。首先，它是在虚拟环境中安装 Python 包的直观工具。此外，它还可以方便地管理您的虚拟环境。诗歌还管理你的依赖关系:它会试图找到一个很好地协同工作的依赖关系的组合，并将这个组合存储在一个所谓的锁文件中。
|
||
|
||
一旦你想把你的软件作为一个 Python 包来分发，poems 也极大地简化了 Python 包的构建和上传！
|
||
|
||
## **安装 Python 诗歌**
|
||
|
||
诗本身推荐你用他们的安装程序。这个安装程序将通过出售将诗歌与你系统的其他部分隔离开来，这样它就不会与你可能通过`pip`安装的其他依赖项冲突。
|
||
|
||
### 使用安装程序
|
||
|
||
诗歌最近更新了它的安装程序。在本教程中，我将向您展示使用它的最新方法。您会经常找到引用另一个 URL 的其他教程。我建议不要用那个。要使用他们最新最好的安装程序，您可以在 Windows 上使用以下命令:
|
||
|
||
```py
|
||
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -
|
||
```
|
||
|
||
在 Mac 或 Linux 系统上:
|
||
|
||
```py
|
||
curl -sSL https://install.python-poetry.org | python3 -
|
||
```
|
||
|
||
### 使用画中画
|
||
|
||
像大多数 Python 包一样，如果你愿意，你也可以用`pip`安装 Python 诗歌。但是，这不是推荐的方法:
|
||
|
||
```py
|
||
pip install --user poetry
|
||
```
|
||
|
||
如果你使用 pip，我建议你把它安装在你的用户帐号里。如今，这可能已经是 Python 安装的默认行为了。然而，我们可以通过如上所示显式使用`--user`标志来确保这一点。
|
||
|
||
### 测试你的诗歌装置是否有效
|
||
|
||
最后，使用以下命令测试安装是否工作正常:
|
||
|
||
```py
|
||
poetry --version
|
||
```
|
||
|
||
如果您看到类似`Poetry 0.13.0`的内容，这意味着安装成功。
|
||
|
||
### 让 Python 诗歌保持最新
|
||
|
||
如果您使用了诗歌安装程序脚本，您可以使用以下命令更新诗歌:
|
||
|
||
```py
|
||
poetry self update
|
||
```
|
||
|
||
如果您决定使用 pip，您将需要使用 pip 来更新诗歌:
|
||
|
||
```py
|
||
pip install --upgrade poetry
|
||
```
|
||
|
||
## 用 Python 诗歌开始一个项目
|
||
|
||
当你用诗歌开始一个项目时，会发生相当多的事情。让我们首先创建一个新项目:
|
||
|
||
```py
|
||
poetry new demo
|
||
```
|
||
|
||
这个命令在当前目录中创建了一个名为`demo`的新目录。当我们检查目录时，我们会看到几个文件:
|
||
|
||
```py
|
||
demo
|
||
├── demo
|
||
│ └── __init__.py
|
||
├── pyproject.toml
|
||
├── README.rst
|
||
└── tests
|
||
├── __init__.py
|
||
└── test_demo.py
|
||
```
|
||
|
||
`demo`目录是您的项目所在的位置。在其中，创建了另一个名为`demo`的目录。这是您的主包，包含一个`__init__.py`文件，方便您使用。你可以自由地重命名或删除这个包，它只是为了你的方便。
|
||
|
||
该命令还创建了一个`pyproject.toml`文件，包含项目的元数据。我们很快会仔细看看那个文件。然后是一个`README.rst`文件，它应该包含项目的简短描述。它类似于更常见的 [Markdown README.md](https://markdown.land/readme-md) 文件。我个人总是立刻将这个文件重命名为 README.md。
|
||
|
||
最后，我们看到一个`tests`目录，一个包含单元测试的包，如果有的话。
|
||
|
||
您可以随意删除这些文件和目录中的任何一个，除了`pyproject.toml`文件。例如，当您不想使用项目中的包和模块时，您可以删除`demo directory. When you don't want to work with tests, you can remove the tests`目录。基本结构只是作为一个建议，并吸引人们遵循一些最佳实践。
|
||
|
||
### **py project . toml 文件**
|
||
|
||
现在让我们仔细看看`pyproject.toml`文件。它是一个 TOML 文件，包含项目的元数据。TOML 是一种简单的格式，易于读写。如果您曾经使用过，这种格式看起来会很熟悉。ini 文件，但是 TOML 有一个官方的规范，表达能力更强。我们的`pyproject.toml`文件看起来像这样:
|
||
|
||
```py
|
||
[tool.poetry]
|
||
name = "demo"
|
||
version = "0.1.0"
|
||
description = ""
|
||
authors = ["Your name <your@e-mail.address>"]
|
||
|
||
[tool.poetry.dependencies]
|
||
python = "^3.10"
|
||
|
||
[tool.poetry.dev-dependencies]
|
||
pytest = "^5.2"
|
||
|
||
[build-system]
|
||
requires = ["poetry-core>=1.0.0"]
|
||
build-backend = "poetry.core.masonry.api"
|
||
```
|
||
|
||
如您所见，该文件分为几个部分:
|
||
|
||
1. `tool.poetry`部分包含项目的元数据，如名称、版本、描述和作者。
|
||
2. `tool.poetry.dependencies`包含项目的依赖关系。这些依赖项是在此项目中运行软件所必需的。
|
||
3. dependencies 包含从事此项目的开发人员所需的依赖项。最终产品不需要这些依赖项，只需要开发和测试应用程序。
|
||
4. 最后，第四部分是`build-system`部分，包含构建系统的设置。我们暂时忽略这一点。
|
||
|
||
## 用 Python 诗安装和移除包
|
||
|
||
要添加和安装包(您的项目依赖项)，您可以编辑`pyproject.toml`文件，或者使用`poetry add <package>`命令。我强烈建议你使用`poetry add`命令，因为它不仅仅是编辑文件。它立即:
|
||
|
||
* 寻找不与其他依赖项冲突的合适版本
|
||
* 在附带的虚拟环境中安装软件包
|
||
* 创建或更新名为`poetry.lock`的锁文件
|
||
|
||
让我们来看看实际情况。我们将安装最新版本的流行 Python 请求包:
|
||
|
||
```py
|
||
poetry add requests
|
||
```
|
||
|
||
输出应该如下所示:
|
||
|
||
```py
|
||
Creating virtualenv demo-IUjJzrPZ-py3.10 in C:\Users\erik\AppData\Local\pypoetry\Cache\virtualenvs
|
||
Using version ^2.28.0 for requests
|
||
|
||
Updating dependencies
|
||
Resolving dependencies...
|
||
|
||
Writing lock file
|
||
|
||
Package operations: 15 installs, 0 updates, 0 removals
|
||
|
||
• Installing pyparsing (3.0.9)
|
||
• Installing atomicwrites (1.4.0)
|
||
• Installing attrs (21.4.0)
|
||
• Installing certifi (2022.6.15)
|
||
• Installing charset-normalizer (2.0.12)
|
||
• Installing colorama (0.4.5)
|
||
• Installing idna (3.3)
|
||
• Installing packaging (21.3)
|
||
• Installing more-itertools (8.13.0)
|
||
• Installing pluggy (0.13.1)
|
||
• Installing py (1.11.0)
|
||
• Installing urllib3 (1.26.9)
|
||
• Installing wcwidth (0.2.5)
|
||
• Installing pytest (5.4.3)
|
||
• Installing requests (2.28.0)
|
||
```
|
||
|
||
### 发生了什么事？
|
||
|
||
首先:这个命令触发了虚拟环境的创建，因为这是我们第一次实际使用这个项目。虚拟环境不是在项目目录中创建的，而是在用户帐户的目录中创建的。在我的例子中，这个目录是:`C:\Users\erik\AppData\Local\pypoetry\Cache\virtualenvs`。
|
||
|
||
将虚拟环境从项目中分离出来，可以更容易地将虚拟环境从版本控制中排除。如果您希望将虚拟环境放在项目目录中，您可以使用以下命令设置`virtualenvs.in-project=true`选项:
|
||
|
||
```py
|
||
poetry config virtualenvs.in-project true
|
||
```
|
||
|
||
此设置将应用于所有将来的项目。
|
||
|
||
Thank you for reading my tutorials. I write these in my free time, and it requires a lot of time and effort. I use ads to keep writing these *free* articles, I hope you understand! **Support me by disabling your adblocker on my website** or, alternatively, **[buy me some coffee](https://www.buymeacoffee.com/pythonland)**. It's much appreciated and allows me to keep working on this site!
|
||
|
||
接下来，安装一堆包，以及我们请求的包。这些都是`requests`包的依赖项。我们可以检查`pyproject.toml`文件，看看这个包是否也添加到了那里:
|
||
|
||
```py
|
||
[tool.poetry.dependencies]
|
||
python = "^3.10"
|
||
requests = "^2.28.0"
|
||
```
|
||
|
||
它只列出了我们请求的包，而不是它所有的依赖项。毕竟，这些依赖项将在安装时由包管理器整理出来，并根据您指定的所有需求选择最佳版本。但是，依赖项将存储在锁文件中。在输出中，我们可以看到一条消息，*正在写锁文件*。我们来看看这个锁文件是干什么用的。
|
||
|
||
### 锁定包
|
||
|
||
安装完`requests`后，还创建了一个新文件，名为`poetry.lock`。该文件有点太大，无法包含在此页面中，但是如果您亲自查看，您会看到许多类似以下的条目:
|
||
|
||
```py
|
||
[[package]]
|
||
name = "idna"
|
||
version = "3.3"
|
||
description = "Internationalized Domain Names in Applications (IDNA)"
|
||
category = "main"
|
||
optional = false
|
||
python-versions = ">=3.5"
|
||
```
|
||
|
||
这些都是`requests`包的需求包，包括`requests`本身。将这些包的版本锁定在一个`poetry.lock`文件中可以确保在重新创建虚拟环境时这些包的版本总是相同的。
|
||
|
||
这是一个强大的特性，因为它确保了我们的项目构建是*确定的*。这对于 CI/CD 来说很重要，对于开发人员拥有一个易于创建和重新创建的一致环境来说也很有帮助。此外，它还可以用作缓存。当重新安装有锁文件的依赖项时，poem 不需要解析所有的依赖项，因为它们已经存储在锁文件中了。
|
||
|
||
### 添加开发人员依赖项
|
||
|
||
如前所述，还有一个名为`tool.poetry.dev-dependencies`的部分列出了构建和测试项目所需的所有依赖项。使用和运行项目(作为普通用户)不需要这些依赖项；因此，它们也不会自动安装。
|
||
|
||
要添加一个 dev 依赖项，我们可以在 add 命令中添加`--dev`选项，如下所示:
|
||
|
||
```py
|
||
poetry add --dev <package name>
|
||
```
|
||
|
||
### 移除包
|
||
|
||
要从项目中移除包，请使用以下命令:
|
||
|
||
```py
|
||
poetry remove <package name>
|
||
```
|
||
|
||
这将删除该包及其所有依赖项，除非那些依赖项也是您的`pyproject.toml`文件中列出的另一个包所需要的。类似于添加开发依赖项，我们也可以使用额外的`--dev`选项删除它们:
|
||
|
||
```py
|
||
poetry remove --dev <package name>
|
||
```
|
||
|
||
### 安装现有 Python 诗歌项目的依赖项
|
||
|
||
当您有一个基于诗歌的现有项目时，您可以使用以下命令一次安装`pyproject.toml`中列出的所有依赖项:
|
||
|
||
```py
|
||
poetry install
|
||
```
|
||
|
||
如果有一个`poetry.lock`文件存在，这将从那个锁文件安装所有的包。如果没有，poems 将解析依赖项，安装软件包，并生成一个新的锁文件。
|
||
|
||
## 使用项目的虚拟环境
|
||
|
||
诗歌也为我们创造了一个虚拟的环境。我们现在将学习如何使用这个虚拟环境。
|
||
|
||
### 运行您的脚本
|
||
|
||
您可以使用`poetry run`命令在项目的虚拟环境中运行脚本。例如，如果您创建了一个名为`main.py`的文件，您可以使用以下命令运行它:
|
||
|
||
```py
|
||
poetry run python main.py
|
||
```
|
||
|
||
同样，您也可以运行安装在虚拟环境中的命令。例如，要运行作为开发者依赖项安装的`pytest`，可以使用`poetry run pytest`。
|
||
|
||
### 激活虚拟环境
|
||
|
||
如果你想交互地使用虚拟环境，你可以使用`poetry shell`命令。这个命令将在新启动的 shell 中激活虚拟环境。一旦在那里，你不需要使用诗歌运行来运行你的脚本。您可以像使用任何其他虚拟环境一样使用虚拟环境。
|
||
|
||
## 更新您的依赖关系
|
||
|
||
更新软件包有两种情况:
|
||
|
||
1. 根据`pyproject.toml`定义的版本约束更新包
|
||
2. 将软件包更新到其最新(或特定)版本
|
||
|
||
因为包版本被锁定在`poetry.lock`文件中，它们不会自动更新。这是一件好事:它确保您的项目按照预期继续工作，即使您试图在一年后重新构建它。然而，我们都知道让你的软件和依赖项保持最新是多么重要，所以我们确实需要一种方法来更新它们。
|
||
|
||
要更新依赖关系，可以使用`poetry update`命令。该命令更新虚拟环境中的依赖项，然后更新`poetry.lock`文件。尽管如此，它仍将遵守`pyproject.toml`文件的约束。例如，如果您定义了一个希望保持在 3.0.0 以上和 4.0.0 以下版本的依赖项，poems 将尝试将其更新到仍低于`4.0.0`的最新`3.x.x`版本。
|
||
|
||
我们也可以用`poetry update package_name`更新一个特定的包。
|
||
|
||
注意，使用`poetry update`相当于删除`poetry.lock`文件并再次运行`poetry install`。
|
||
|
||
### 将软件包更新到最新版本
|
||
|
||
如果想更严谨，想尝试最新版本，需要使用`poetry add`命令。以下命令演示了如何将`requests`包更新到其最新版本或特定版本:
|
||
|
||
```py
|
||
# Install the latest version
|
||
poetry add requests@latest
|
||
|
||
# Install a specific version
|
||
poetry add requests@2.28.0
|
||
```
|
||
|
||
## 构建和发布包
|
||
|
||
诗歌使构建包变得容易。我只会对此做一个简单的介绍。关于完整的说明，我建议你阅读官方文档。
|
||
|
||
本质上，要构建一个包，可以使用`poetry build`命令。这个命令将在一个新创建的名为`dist`的目录中创建两个文件。第一个文件是一个车轮文件(。whl)，一个编译后的包，第二个是包含包源代码的 tar.gz 文件。
|
||
|
||
准备好这两个文件后，您可以将它们发布到存储库中。默认情况下，这将是公共的 PyPI 存储库。不过，您也可以发布到私有存储库中。无论您在哪里发布，您可能都需要首先为存储库设置凭证，以便 poems 可以访问它。
|
||
|
||
对于 PyPI，建议创建一个访问令牌，而不是更老式的用户名和密码。一旦创建了这样的访问令牌，就可以使用以下内容对其进行配置:
|
||
|
||
```py
|
||
poetry config pypi-token.pypi <token>
|
||
```
|
||
|
||
现在，您已经准备好发布您的包了:
|
||
|
||
```py
|
||
poetry publish
|
||
```
|
||
|
||
## 诗是互通的
|
||
|
||
诗歌有几个特点，使它可以很好地与现有的项目。它还有一个导出功能，可以将您的项目转换回老式的基于 pip 的项目。
|
||
|
||
### 将现有项目转换为诗歌
|
||
|
||
要在预先存在的项目中使用诗歌，您可以使用`poetry init`命令。该命令将在当前目录下创建一个`pyproject.toml`文件:
|
||
|
||
```py
|
||
cd my-project
|
||
poetry init
|
||
```
|
||
|
||
这将启动一个交互式向导，帮助您为现有项目创建一个`pyproject.toml`文件！
|
||
|
||
### 导出到常规 requirements.txt 文件
|
||
|
||
您可以将使用诗歌创建的依赖项列表导出到一个`requirements.txt`文件中。例如，当你需要和不使用诗歌的人一起工作时，这就派上了用场。我更多地使用它是在创建 Docker 图像的时候。作为构建步骤的一部分，我将我的依赖项导出到一个`requirements.txt`文件中，因此我不需要在`Dockerfile`中安装和使用诗歌。
|
||
|
||
要将您的依赖项导出到一个`requirements.txt`文件，使用以下命令:
|
||
|
||
```py
|
||
poetry export -f requirements.txt > requirements.txt
|
||
```
|
||
|
||
## 诗歌命令备忘单
|
||
|
||
下表列出了最常用的诗歌命令，包括它们的简短描述。
|
||
|
||
| `poetry --version` | 显示您的诗歌安装版本 |
|
||
| `poetry new <name>` | 创建新的诗歌项目 |
|
||
| `poetry init` | 启动一个向导，帮助您将现有项目转换为诗歌项目 |
|
||
| `poetry add <package>` | 将包添加到`pyproject.toml`，解决依赖性，并将包安装在 venv 中 |
|
||
| `poetry remove <package>` | 从项目中移除包(包括其依赖项) |
|
||
| `poetry show` | 列出已安装的软件包 |
|
||
| `poetry export -f <filename>` | 导出依赖项列表(目前只导出为 requirements.txt 格式) |
|
||
| `poetry install` | 安装当前诗歌项目的所有依赖项。使用`poetry.lock`(如果有)。 |
|
||
| `poetry run <command>` | 在项目的虚拟环境中运行命令 |
|
||
| `poetry shell` | 启动一个新的 shell，激活项目的虚拟环境 |
|
||
|
||
诗歌命令
|
||
|
||
## 诗歌 vs Pipenv
|
||
|
||
尽管我也写过一个替代方案，叫做 [Pipenv](https://python.land/virtual-environments/pipenv) ，我还是强烈推荐诗歌。即使诗歌和 Pipenv 有很多重合。我觉得大多数人都会同意诗歌是更好的选择。Pipenv 铺平了道路，但在过去几年中，它的发展停滞了一点。与此同时，诗歌获得了大量的牵引力和用户。
|
||
|
||
诗歌相对于 Pipenv 的几个优势是:
|
||
|
||
* 它使用现在标准化的`pyproject.toml`
|
||
* 许多人说它在解决依赖性方面更快
|
||
* 诗歌还可以帮助你构建你的项目，并将其发布在 PyPI 或私有存储库上。
|
||
* 这很主观，但我更喜欢(彩色的)命令行界面
|
||
|
||
## 了解更多信息
|
||
|
||
如果您想进一步了解这款出色的工具，可以尝试以下资源:
|
||
|
||
* 这里的诗歌介绍[有详细的安装说明，包括在命令行上启用自动完成的说明。](https://python-poetry.org/docs/)
|
||
* 如果你想学习如何准确定义版本范围，诗歌网站有一个关于[依赖规范](https://python-poetry.org/docs/dependency-specification/)的扩展部分。
|
||
* 您可以在此页面上[了解更多关于创建和发布您自己的包的信息。](https://python-poetry.org/docs/libraries/)
|
||
|
||
## 结论
|
||
|
||
你学到了诗歌所能提供的。到目前为止，您可能已经看到了像 poem 这样的工具是如何使您的生活比使用 pip install 和手动创建虚拟环境容易得多。我们已经了解了诗歌项目是如何构建的，`pyproject.toml`和`poetry.lock`文件是做什么用的，以及如何安装和更新项目的依赖项。我们还快速浏览了如何创建自己的包，以及如何通过 PyPI 与他人共享。 |