2025-01-20    2025-01-22    2135 字  5 分钟
OLs

Poetry 是一个现代的 Python 包管理工具,它不仅能够管理依赖,还可以构建和发布 Python 包。Poetry 的目标是简化 Python 项目的管理,替代传统的 requirements.txtsetup.pypip 等工具。下面是 Poetry 的简要教程说明,包括安装、常用命令和基本使用。

1. 安装 Poetry

Poetry 可以通过 Python 包管理工具 pip 或官方安装脚本安装。

# 使用 `pip` 安装
pip install poetry

# 使用官方安装脚本安装(推荐 🌟)
curl -sSL https://install.python-poetry.org | python3 -

安装完成后,你可以通过以下命令确认 Poetry 是否安装成功:

poetry --version

# 查看当前配置
poetry config --list

2. 初始化 Poetry 项目

❶ 初始化新的项目

Poetry 可以用来快速初始化一个新的 Python 项目。通过 poetry new 命令创建一个项目。

1
poetry new my_project

这将创建一个新的 my_project 目录,包含一个基本的 Python 包结构:

/my_project
    /my_project
        __init__.py
    pyproject.toml
    README.rst
    tests
        __init__.py
        test_my_project.py

pyproject.toml 文件是 Poetry 的核心配置文件,用于描述项目的元数据、依赖关系、构建工具等。

❷ 初始化已有项目

还可以通过 poetry init:初始化当前目录为一个 Poetry 项目(创建 pyproject.toml)。

3. 管理项目依赖

Poetry 提供了非常简洁的命令来管理项目的依赖,包括安装、添加、删除等操作。

❶ 添加依赖:

使用 poetry add 来添加依赖,支持通过指定版本号来精确安装依赖。

1
2
poetry add requests          # 添加最新版本的 requests 库
poetry add requests@2.25.1    # 添加指定版本的 requests 库

你也可以添加开发依赖(如测试框架):

1
poetry add --dev pytest

❷ 查看当前依赖:

查看项目的所有依赖,可以使用:

1
poetry show

❸ 删除依赖:

如果需要删除某个依赖,可以使用:

1
poetry remove requests

4. 虚拟环境管理

Poetry 会自动为每个项目创建一个独立的虚拟环境来隔离项目依赖。你可以通过以下命令查看虚拟环境的路径:

1
poetry env info

💡 这里有一点需要注意

Poetry 的虚拟环境默认放在默认的全局缓存位置

  • Windows: %LOCALAPPDATA%\pypoetry\Cache\virtualenvs\
  • macOS/Linux: ~/.cache/pypoetry/virtualenvs/

如果我们想要把它放在当前项目中,应该怎么做呢?

运行以下命令:

1
2
3
4
poetry config virtualenvs.in-project true

# 再次安装依赖(有时,可能需要删除全局缓存)
poetry install

虚拟环境会存放在项目根目录的 .venv 文件夹中。

❶ 激活虚拟环境:

你可以通过以下命令激活虚拟环境,进入虚拟环境后执行 Python 或其他命令:

1
poetry shell

⚠️ 这个命令在 Windows 下不可用❗️

不能用该怎么办呢?手动激活喽~ 通过脚本〔 推荐 〕,或者像下面这样手动创建虚拟环境。

如果 poetry shell 无法正常工作,可以尝试手动创建虚拟环境并指定 Python 版本。可以使用 poetry env use 来指定 Python 版本:

poetry env use python3.8

如果虚拟环境已经存在,但无法进入,尝试删除现有的虚拟环境并重新创建:

poetry env remove python3.x  # 根据需要选择 Python 版本 poetry env use python3.8    # 再次创建新的虚拟环境

❷ 退出虚拟环境:

使用以下命令退出虚拟环境:

1
exit

❸ 如何不激活虚拟环境?

使用 poetry 默认会为每个项目创建一个虚拟环境,但这在某些情况下不是我们想要的,比如在个人主机中。那么如何设置默认禁用虚拟环境呢?

方法¹ 全局配置禁用虚拟环境

poetry config virtualenvs.create false

# 验证配置,确保 virtualenvs.create 的值为 false
poetry config --list

方法² 项目级别禁用虚拟环境

# 编辑 pyproject.toml
[tool.poetry]
[tool.poetry.virtualenvs]
create = false

# 验证配置,确保 virtualenvs.create 的值为 false
poetry config --local --list

方法³ 临时禁用虚拟环境

poetry install --no-venv

禁用虚拟环境后,Poetry 将直接使用系统的 Python 环境。请确保系统的 Python 环境干净且与项目依赖兼容,避免依赖冲突。

如果需要重新启用虚拟环境,可以运行以下命令:

poetry config virtualenvs.create true

🪧 无论什么时候,都可以方便地使用 poetry env info 显示虚拟环境的启用状态。

5. 安装项目依赖

当你克隆一个使用 Poetry 管理的项目时,可以使用 poetry install 来安装项目的所有依赖:

1
poetry install

这会根据 pyproject.toml 文件中的依赖信息安装所有必要的包。

6. 运行命令

Poetry 允许你在项目的虚拟环境中直接运行 Python 命令或其他工具。例如,如果你想运行一个 Python 脚本,可以使用:

1
poetry run python my_script.py

7. 构建和发布包

Poetry 可以自动构建和发布 Python 包到 PyPI。要构建包,只需运行:

1
poetry build

这会在 dist/ 目录下生成 .tar.gz.whl 格式的包。

发布包

要将包发布到 PyPI,首先需要配置你的 PyPI 凭据:

1
poetry config pypi-token.pypi <your-token>

然后运行:

1
poetry publish --build

8. pyproject.toml 配置文件

pyproject.toml 文件是 Poetry 项目的核心配置文件,包含项目信息、依赖、构建工具等。下面是一个简单的 pyproject.toml 示例:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
[tool.poetry]
name = "my_project"
version = "0.1.0"
description = "A simple example project"
authors = ["Your Name <your.email@example.com>"]

[tool.poetry.dependencies]
python = "^3.8"
requests = "^2.25.0"

[tool.poetry.dev-dependencies]
pytest = "^6.2"

[build-system]
requires = ["poetry>=1.0"]
build-backend = "poetry.masonry.api"
  • [tool.poetry] 部分定义了项目的基本信息。
  • [tool.poetry.dependencies] 定义了项目的运行时依赖。
  • [tool.poetry.dev-dependencies] 定义了项目的开发时依赖。
  • [build-system] 定义了构建系统,Poetry 使用的是 poetry.masonry.api

9. 常用命令汇总

  • poetry new <project-name>:创建一个新的项目。
  • poetry init:初始化当前目录为一个 Poetry 项目(创建 pyproject.toml)。
  • poetry add <package>:添加依赖包。
  • poetry remove <package>:移除依赖包。
  • poetry install:安装依赖。
  • poetry update:更新依赖。
  • poetry shell:激活虚拟环境。
  • poetry run <command>:在虚拟环境中运行命令。
  • poetry build:构建包。
  • poetry publish:发布包到 PyPI。

10. Poetry 的优势

  • 简化依赖管理:Poetry 自动管理所有依赖和虚拟环境,无需手动编辑 requirements.txt
  • 一致性:Poetry 使用 pyproject.toml 来定义依赖,避免了传统的 setup.pyrequirements.txt 文件的不一致性。
  • 集成的发布功能:Poetry 让发布包到 PyPI 变得非常简单,几乎不需要配置。

总结

Poetry 提供了一种现代、简洁且强大的方式来管理 Python 项目,它解决了传统 Python 包管理工具的一些痛点,并使得依赖管理、虚拟环境、包构建和发布等变得更加简单和统一。如果你在开发中遇到问题,Poetry 的文档非常详细,并且社区支持活跃,可以随时查询或寻求帮助。

希望这个简要教程能帮助你更好地使用 Poetry!如果有任何问题,欢迎随时提问!