基本用法
基本用法 #
在基本用法介绍中，我们将安装 pendulum，一个日期时间库。如果您还没有安装 Poetry，请参考 简介 章节。
项目设置 #
首先，让我们创建一个新项目，我们将其命名为 poetry-demo
poetry new poetry-demo
这将在 poetry-demo 目录中创建以下内容
poetry-demo
├── pyproject.toml
├── README.md
├── poetry_demo
│ └── __init__.py
└── tests
└── __init__.py
pyproject.toml 文件在这里是最重要的。它将协调您的项目及其依赖项。现在，它看起来像这样
[tool.poetry]
name = "poetry-demo"
version = "0.1.0"
description = ""
authors = ["Sébastien Eustace <sebastien@eustace.io>"]
readme = "README.md"
packages = [{include = "poetry_demo"}]
[tool.poetry.dependencies]
python = "^3.7"
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"
Poetry 假设您的包包含一个与 tool.poetry.name 相同名称的包，位于项目的根目录中。如果不是这种情况，请填充 tool.poetry.packages 来指定您的包及其位置。
类似地，传统的 MANIFEST.in 文件被 tool.poetry.readme、tool.poetry.include 和 tool.poetry.exclude 部分取代。tool.poetry.exclude 还隐式地由您的 .gitignore 填充。有关项目格式的完整文档，请参阅文档的 pyproject 部分。
设置 Python 版本 #
Poetry 将要求您明确指定要支持的 Python 版本，其通用锁定将保证您的项目可安装（并且所有依赖项都声称支持）所有支持的 Python 版本。同样，重要的是要记住，与其他依赖项不同，设置 Python 版本仅仅是指定您打算支持的 Python 版本。
例如，在这个 pyproject.toml 文件中
[tool.poetry.dependencies]
python = "^3.7.0"
我们允许任何大于 3.7.0 的 Python 3 版本。
当您运行 poetry install 时，您必须在系统上访问满足此约束的某个 Python 解释器版本。Poetry 不会为您安装 Python 解释器。如果您使用 pyenv 等工具，可以使用实验性配置值 virtualenvs.prefer-active-python。
初始化现有项目 #
Poetry 可以用来“初始化”一个预先填充的目录，而不是创建一个新项目。要在目录 pre-existing-project 中交互式地创建一个 pyproject.toml 文件
cd pre-existing-project
poetry init
操作模式 #
Poetry 可以以两种不同的模式运行。默认模式是包模式，如果您想将您的项目打包成 sdist 或 wheel，并可能将其发布到包索引，则这是正确的模式。在此模式下，一些元数据（如 name 和 version）是必需的，这些元数据是打包所必需的。此外，当运行 poetry install 时，项目本身将以可编辑模式安装。
如果您只想使用 Poetry 进行依赖项管理，而不是打包，可以使用非包模式
[tool.poetry]
package-mode = false
在此模式下，name 和 version 等元数据是可选的。因此，无法构建发行版或将项目发布到包索引。此外，当运行 poetry install 时，Poetry 不会尝试安装项目本身，而只安装其依赖项（与 poetry install --no-root 相同）。
指定依赖项 #
如果您想将依赖项添加到您的项目中，可以在 tool.poetry.dependencies 部分中指定它们。
[tool.poetry.dependencies]
pendulum = "^2.1"
如您所见，它接受包名称和版本约束的映射。
Poetry 使用此信息在您在 tool.poetry.source 部分中注册的包“仓库”中或默认情况下在 PyPI 上搜索正确的一组文件。
此外，您可以使用 add 命令，而不是手动修改 pyproject.toml 文件。
$ poetry add pendulum
它将自动找到合适的版本约束，并安装包及其子依赖项。
Poetry 支持丰富的 依赖项规范 语法，包括插入符号、波浪号、通配符、不等式和 多个约束 要求。
使用您的虚拟环境 #
默认情况下，Poetry 在 {cache-dir}/virtualenvs 中创建一个虚拟环境。您可以通过编辑 Poetry 配置来更改 cache-dir 值。此外，您可以使用 virtualenvs.in-project 配置变量在您的项目目录中创建虚拟环境。
有几种方法可以在此虚拟环境中运行命令。
外部虚拟环境管理
Poetry 将检测并尊重已外部激活的现有虚拟环境。这是一种强大的机制，旨在作为 Poetry 内置的简化环境管理的替代方案。
要利用此功能，只需使用您首选的方法或工具激活虚拟环境，然后运行任何需要操作环境的 Poetry 命令。
使用 poetry run #
要运行您的脚本，只需使用 poetry run python your_script.py。同样，如果您有命令行工具，如 pytest 或 black，您可以使用 poetry run pytest 运行它们。
如果您在外部管理自己的虚拟环境，则不需要使用 poetry run 或 poetry shell，因为您可能已经激活了该虚拟环境，并提供了正确的 python 实例。例如，这些命令应该输出相同的 python 路径
conda activate your_env_name
which python
poetry run which python
poetry shell
which python
激活虚拟环境 #
激活虚拟环境最简单的方法是使用 poetry shell 创建一个嵌套的 shell。
要停用虚拟环境并退出此新 shell，请键入 exit。要停用虚拟环境而不退出 shell，请使用 deactivate。
为什么是嵌套的 shell？
子进程从其父进程继承其环境，但不会共享它们。因此，子进程所做的任何修改在子进程退出后都不会保留。Python 应用程序（Poetry）作为子进程，无法修改其被调用的 shell 的环境，因此激活的虚拟环境在 Poetry 命令完成执行后仍然处于活动状态。
因此，Poetry 必须创建一个子 shell，并在其中激活虚拟环境，以便后续命令从虚拟环境中运行。
如果您想阻止 poetry shell 在虚拟环境激活时修改您的 shell 提示符，您应该在运行命令之前将 VIRTUAL_ENV_DISABLE_PROMPT=1 设置为环境变量。
或者，为了避免创建新的 shell，你可以手动激活虚拟环境，运行 source {path_to_venv}/bin/activate （在 PowerShell 中运行 {path_to_venv}\Scripts\activate.ps1）。要获取虚拟环境的路径，运行 poetry env info --path。你也可以将这些命令组合成一行，例如 source $(poetry env info --path)/bin/activate （在 PowerShell 中运行 & ((poetry env info --path) + "\Scripts\activate.ps1")）。
要停用此虚拟环境，只需使用 deactivate。
| POSIX Shell | Windows (PowerShell) | 退出/停用 | |
|---|---|---|---|
| 子 shell | poetry shell |
poetry shell |
exit |
| 手动激活 | source {path_to_venv}/bin/activate |
{path_to_venv}\Scripts\activate.ps1 |
deactivate |
| 单行命令 | source $(poetry env info --path)/bin/activate |
& ((poetry env info --path) + "\Scripts\activate.ps1") |
deactivate |
版本约束 #
在我们的示例中，我们请求 pendulum 包，版本约束为 ^2.1。这意味着任何大于或等于 2.1.0 且小于 3.0.0 的版本（>=2.1.0 <3.0.0）。
请阅读 依赖关系规范，以获取有关版本、版本之间的关系以及指定依赖关系的不同方式的更深入信息。
Poetry 如何下载正确的文件？
当你在 pyproject.toml 中指定依赖关系时，Poetry 首先获取你请求的包的名称，并在你使用 repositories 键注册的任何仓库中搜索它。如果你没有注册任何额外的仓库，或者它在指定的仓库中没有找到具有该名称的包，它将回退到 PyPI。
当 Poetry 找到正确的包时，它将尝试找到与你指定的版本约束最匹配的版本。
安装依赖关系 #
要安装项目中定义的依赖关系，只需运行 install 命令。
poetry install
当你运行此命令时，可能会发生以下两种情况之一
在没有 poetry.lock 的情况下安装 #
如果你以前从未运行过该命令，并且也没有 poetry.lock 文件存在，Poetry 将简单地解析 pyproject.toml 文件中列出的所有依赖关系，并下载其文件的最新版本。
当 Poetry 完成安装后，它会将所有下载的包及其确切版本写入 poetry.lock 文件，将项目锁定到这些特定版本。你应该将 poetry.lock 文件提交到你的项目仓库，以便所有参与项目的人员都锁定到相同的依赖关系版本（更多内容见下文）。
使用 poetry.lock 安装 #
这将我们带到第二种情况。如果在运行 poetry install 时，poetry.lock 文件和 pyproject.toml 文件都存在，这意味着你之前运行过 install 命令，或者项目中的其他人运行过 install 命令并将 poetry.lock 文件提交到项目（这是好事）。
无论哪种方式，在 poetry.lock 文件存在的情况下运行 install 命令都会解析并安装你在 pyproject.toml 文件中列出的所有依赖关系，但 Poetry 使用 poetry.lock 文件中列出的确切版本来确保包版本对所有参与项目的人员保持一致。因此，你将拥有 pyproject.toml 文件中请求的所有依赖关系，但它们可能并非全部都是最新版本（poetry.lock 文件中列出的某些依赖关系可能在文件创建后发布了更新版本）。这是有意为之，它确保你的项目不会因为依赖关系的意外更改而崩溃。
将 poetry.lock 文件提交到版本控制 #
作为应用程序开发人员 #
应用程序开发人员提交 poetry.lock 以获得更可重复的构建。
将此文件提交到 VC 很重要，因为它会让任何设置项目的人员使用与你使用的完全相同的依赖关系版本。你的 CI 服务器、生产机器、团队中的其他开发人员，所有东西和每个人都运行在相同的依赖关系上，这减少了仅影响部署某些部分的错误的可能性。即使你独自开发，在六个月后重新安装项目时，你也可以确信安装的依赖关系仍然有效，即使你的依赖关系自那时起发布了许多新版本。（请参阅下面关于使用 update 命令的说明。）
[build-system] 部分添加到项目的 pyproject.toml 中，那么你可以成功地使用类似 pip install -e . 的命令将项目及其依赖关系安装到虚拟环境中。但是，pip 不会使用锁定文件来确定依赖关系版本，因为 poetry-core 构建系统是为库开发人员设计的（见下一节）。作为库开发人员 #
库开发人员需要考虑更多因素。你的用户是应用程序开发人员，你的库将在你无法控制的 Python 环境中运行。
应用程序会忽略你的库的锁定文件。它可以使用满足 pyproject.toml 中约束的任何依赖关系版本。应用程序可能会使用最新的兼容依赖关系版本。如果你的库的 poetry.lock 落后于某些新的依赖关系版本，而这些版本会给你的用户带来问题，你很可能是最后一个发现问题的人。
避免这种情况的一种简单方法是省略 poetry.lock 文件。但是，这样做会在一定程度上牺牲可重复性和性能。如果没有锁定文件，可能很难找到测试失败的原因，因为除了明显的代码更改之外，未注意到的库更新也可能是罪魁祸首。此外，如果省略了 poetry.lock，Poetry 将不得不先锁定才能安装依赖关系。根据依赖关系的数量，锁定可能需要相当长的时间。
如果你不想放弃可重复性和性能优势，请考虑定期刷新 poetry.lock 以保持最新状态，并降低用户突然出现故障的风险。
仅安装依赖关系 #
默认情况下，当前项目以 可编辑 模式安装。
如果你只想安装依赖关系，请使用 --no-root 标志运行 install 命令
poetry install --no-root
将依赖关系更新到最新版本 #
如上所述，poetry.lock 文件阻止你自动获取依赖关系的最新版本。要更新到最新版本，请使用 update 命令。这将获取最新的匹配版本（根据你的 pyproject.toml 文件）并使用新版本更新锁定文件。（这等同于删除 poetry.lock 文件并再次运行 install 命令。）
poetry.lock 和 pyproject.toml 未同步，Poetry 在执行安装命令时将显示一个警告。