介绍

什么是Poetry

Poetry是Python中用于依赖管理和打包的工具。它允许你声明你的项目所依赖的库，它会为你管理(安装/更新)它们。它的主要功能包括：

1. 依赖管理：Poetry 可以帮助你管理项目的依赖项，包括指定需要的 Python 版本、外部包和库的版本号等。
2. 虚拟环境管理：Poetry 可以在项目中创建和管理虚拟环境，确保项目的依赖项不会与系统中其他项目的依赖项发生冲突。
3. 项目构建和发布：Poetry 支持项目的构建和打包，可以生成 wheel 或 sdist 格式的发布包，方便在其他环境中安装和部署。
4. 版本管理：Poetry 提供了版本控制的功能，可以帮助你管理项目的版本号，并支持在项目中定义版本的约束和依赖。
5. 命令行工具：Poetry 提供了一系列命令行工具，可以方便地进行依赖安装、更新、打包、发布等操作。

Poetry - Python dependency management and packaging made easy

Poetry与conda对比

用途和重点：

• Poetry： Poetry 主要用于依赖管理和项目打包。它旨在提供一种简单和一致的方式来管理Python项目的依赖关系，并且可以帮助打包项目为发布准备。
• conda： Conda 是一个通用的包管理和环境管理系统，不仅限于Python。在Python社区中，它被广泛用于管理包、依赖关系和环境。

项目管理：

• Poetry： Poetry 使用 pyproject.toml 文件来定义项目的依赖关系和元数据，使得管理和共享项目变得更加简单和可靠。
• conda： Conda 使用 environment.yml 或者 requirements.txt 文件来定义环境和依赖关系，它可以创建和管理不同的虚拟环境，使得在不同项目和需求之间切换更为方便。

项目管理：

• Poetry： Poetry 使用 pyproject.toml 文件来定义项目的依赖关系和元数据，使得管理和共享项目变得更加简单和可靠。
• conda： Conda 使用 environment.yml 或者 requirements.txt 文件来定义环境和依赖关系，它可以创建和管理不同的虚拟环境，使得在不同项目和需求之间切换更为方便。

pipx

pipx 将在用于安装 Poetry ，以及 Poetry的管理升级和卸载。
pipx
:::tips
什么是pipx？
pipx是一个用于安装和管理Python命令行工具的工具。它的主要优势在于可以将每个工具安装在一个隔离的虚拟环境中，同时又可以全局调用这些工具，既解决了版本冲突的问题，又保持了系统的整洁。
核心概念

• 虚拟环境：pipx会为每个安装的工具创建一个独立的虚拟环境。
• 全局可用：尽管工具被安装在独立的虚拟环境中，但pipx会创建一个全局可访问的命令链接，使得你可以像平常一样使用这些工具。
  :::

安装

1.安装pipx

pip install --user pipx

Installation - pipx

2.安装Peotry

pipx install poetry
或者
pipx install poetry==1.2.0

2.更新Peotry

pipx upgrade poetry

4.卸载Peotry

pipx uninstall 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 以指定您的包及其位置。

启动项目

Poetry可以用来“初始化”一个已经存在的项目，而不是创建一个新的项目。要在目录 pre-existing-project 中以交互方式创建 pyproject.toml 文件，请执行以下操作：

cd pre-existing-project
poetry init

设置Python版本

在此 pyproject.toml 文件中：

[tool.poetry.dependencies]
python = "^3.7.0"

:::tips
注意：
需要pyhton版本大于3.7.
:::

操作模式

Peotry有两种工作模式。
默认模式是package模式，如果您希望将项目打包到sdist或wheel中，并可能将其发布到包索引中，则该模式是正确的模式。在此模式下，一些打包所需的元数据（如 name 和 version ）是强制性的。此外，项目本身将在运行 poetry install 时以可编辑模式安装。
如果你只想使用Poetry进行依赖管理，而不想打包，你可以使用非打包模式：

[tool.poetry]
package-mode = false

在这种模式下，诸如 name 和 version 的元数据是可选的。因此，不可能生成发行版或将项目发布到包索引。

添加依赖项

如果你想在你的项目中添加依赖项，你可以在 tool.poetry.dependencies 部分中指定它们。
上面指定python版本也是属于添加依赖。

[tool.poetry.dependencies]
python = "^3.7.0"

此外，您可以使用 add 命令，而不是手动修改 pyproject.toml 文件

$ poetry add pendulum

它会自动找到合适的版本约束，并安装包和子依赖项。

使用虚拟环境

默认情况下，Poetry在 {cache-dir}/virtualenvs 中创建虚拟环境。您可以通过编辑Poetry配置来更改 cache-dir 值。此外，您可以使用 virtualenvs.in-project 配置变量在项目目录中创建虚拟环境。

使用 poetry run

要运行脚本，只需使用 poetry run python your_script.py 。同样，如果你有命令行工具，如 pytest 或 black ，你可以使用 poetry run pytest 运行它们。
如果在外部管理自己的虚拟环境，则不需要使用 poetry run 或 poetry shell ，因为您已经激活了该虚拟环境并提供了正确的python实例。

激活虚拟环境| poetry shell

激活虚拟环境的最简单方法是使用 poetry shell 创建一个嵌套 shell。

• 运行 exit 停用虚拟环境并退出这个新的 shell。
• 运行 deactivate 命令来停用虚拟环境，不退出shell。

如果你想阻止 Poetry shell 在激活虚拟环境时修改你的 shell 提示符，可以在运行命令之前设置环境变量 VIRTUAL_ENV_DISABLE_PROMPT=1 。
或者，为了避免创建新 shell，可以通过运行命令手动激活虚拟环境。
手动激活虚拟环境：

• 在 Unix 系统（如 Linux 和 macOS）上，你可以运行 source {path_to_venv}/bin/activate。
• 在 Windows PowerShell 上，你可以运行 {path_to_venv}\Scripts\activate.ps1。

获取虚拟环境的路径：

• 可以运行 poetry env info --path 来获取虚拟环境的路径。

版本约束

在我们的示例中，如果请求带有版本约束 ^2.1 的 pendulum 包。这意味着任何大于或等于2.1.0且小于3.0.0（ >=2.1.0 <3.0.0 ）的版本。
阅读关于依赖规范的更深入信息，了解版本、版本之间的关系，以及你可以指定依赖的不同方式 。
Dependency specification | Documentation | Poetry - Python dependency management and packaging made easy
:::tips
Peotry如何下载正确的文件？
当你在 pyproject.toml 中指定一个依赖项时，Poetry 首先获取你请求的包的名称，并在你使用 repositories 键注册过的任何仓库中搜索这个包。如果你没有注册额外的仓库，或者在你指定的仓库中没有找到这个包的名称，Poetry 将会回退到 PyPI（Python Package Index）进行查找。
:::

安装依赖项

运行 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 文件以来，其中一些依赖项可能已经发布了新版本）。
pyproject.toml文件

poetry.lock 文件

将 poetry.lock 文件提交到版本控制

提交 poetry.lock 文件到版本控制系统的目的是为了确保项目的依赖项版本在不同的开发环境和部署环境中保持一致。这样做有几个好处：

1. 一致性： 确保所有人使用的依赖项版本一致，避免了因为不同版本的依赖项导致的环境差异问题。
2. 可靠性： 减少了因依赖项更新引入的新问题，从而提高了项目的稳定性。
3. 可预测性： 即使过了很长时间再次安装项目，也能确保依赖项版本没有变化，项目能够正常运行。
4. 协作便利： 团队中的所有开发人员都使用相同的依赖项版本，便于协同工作和调试。

仅安装依赖项

通常，当你运行 poetry install 命令时，它不仅会安装你在 pyproject.toml 文件中列出的依赖项，还会安装你的项目包本身，使得你的项目可以在开发环境中以包的形式导入和使用。
如果您只想安装依赖项，请运行带有 --no-root 标志的 install 命令：

poetry install --no-root

更新依赖

poetry.lock 文件阻止您自动获取依赖项的最新版本。要更新到最新版本，请使用 update 命令。这将获取最新的匹配版本（根据 pyproject.toml 文件）并使用新版本更新锁文件。
其实相当于删除 poetry.lock 文件并再次运行 install 。

poetry update

Poetry 常用命令

项目初始化和管理

• 初始化新项目：

poetry new my-project

这会创建一个名为 my-project 的新项目。

• 在现有项目中初始化 Poetry：

poetry init

这会引导你通过交互式的问题来生成一个 pyproject.toml 文件。

依赖管理

• 安装项目依赖：

poetry install

这会根据 pyproject.toml 文件安装所有依赖。

• 添加依赖：

poetry add requests

这会将 requests 包添加到项目依赖中并安装。

• 添加开发依赖：

poetry add --dev pytest

这会将 pytest 包添加到开发依赖中并安装。

• 删除依赖：

poetry remove requests

这会从项目中移除 requests 依赖。

虚拟环境管理

• 进入虚拟环境：

poetry shell

这会创建并激活一个新的虚拟环境。

• 退出虚拟环境：

deactivate

这会退出当前激活的虚拟环境。

• 退出虚poetry shell：

exit

这会退出当前poetry shell。

• 获取虚拟环境信息：

poetry env info

这会显示虚拟环境的详细信息。

发布和打包

• 生成项目的锁文件：

poetry lock

这会根据 pyproject.toml 文件生成或更新 poetry.lock 文件。

• 构建项目：

poetry build

这会构建项目的源码和 wheel 包。

• 发布项目到 PyPI：

poetry publish

这会将构建好的包发布到 PyPI。

其他

• 更新依赖：

poetry update

这会更新项目的所有依赖到最新的兼容版本。

• 运行项目中的命令：

poetry run python my_script.py

这会在 Poetry 的虚拟环境中运行指定的脚本或命令。

• 检查项目依赖：

poetry check

这会检查项目依赖是否正确配置。