如何在 Linux 上使用 Poetry

全面指南：安装、配置与项目管理

关键要点

• 快速安装：通过官方脚本轻松安装 Poetry，确保最新版本。
• 简化依赖管理：使用 Poetry 轻松添加、移除和更新项目依赖，维护项目稳定性。
• 高效虚拟环境管理：自动创建和管理独立的虚拟环境，避免依赖冲突，提高开发效率。

1. 什麼是 Poetry？

Poetry 是一个现代化的依赖管理和包打包工具，专为 Python 项目设计。它致力于简化项目的依赖管理、虚拟环境配置以及包的构建与发布流程。Poetry 提供了一个统一的 CLI 工具，使开发者能够更高效地管理项目，避免了传统工具带来的复杂性和不一致性。

主要功能包括：

• 自动管理项目依赖并生成锁定文件，确保环境一致性。
• 便捷的虚拟环境创建与管理，隔离项目依赖。
• 简化的包构建与发布流程，支持多种发布渠道。

2. 环境准备

2.1 安装 Python

Poetry 需要 Python 3.7 或以上版本。可以使用以下命令检查当前安装的 Python 版本：

python3 --version

如果未安装或版本过低，可以通过系统的包管理器安装最新版本的 Python。例如，在基于 Debian 的系统上，可以使用以下命令：

sudo apt update
sudo apt install python3 python3-pip

2.2 更新包管理器

确保系统的包管理器和已安装的软件包是最新的，以避免潜在的兼容性问题。

sudo apt update && sudo apt upgrade -y

3. 安装 Poetry

3.1 使用官方安装脚本

Poetry 提供了一个官方推荐的安装脚本，可以通过以下命令进行安装。这种方式简单快捷，能够确保安装最新版本的 Poetry：

curl -sSL https://install.python-poetry.org | python3 -

此命令将下载并运行 Poetry 的安装脚本，将其安装到用户的本地目录中。

3.2 配置环境变量

安装完成后，需要将 Poetry 的可执行文件路径添加到系统的环境变量中，以便在终端中全局使用 Poetry 命令。可以使用以下命令：

export PATH="$HOME/.local/bin:$PATH"

为了在每次启动终端时自动加载，可将上述命令添加到你的 shell 配置文件中，如 ~/.bashrc 或 ~/.zshrc：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

3.3 验证安装

安装完成后，可以使用以下命令验证 Poetry 是否成功安装，并查看其版本号：

poetry --version

成功安装后，将显示类似于 Poetry (version 1.2.0) 的版本信息。

4. 创建和初始化项目

4.1 创建新项目

使用以下命令创建一个新的 Poetry 项目，这将生成项目的基本结构和必要的配置文件：

poetry new my_project

该命令将在当前目录下创建一个名为 my_project 的文件夹，包含以下结构：

my_project/
├── pyproject.toml
├── README.rst
├── my_project/
│   └── __init__.py
└── tests/
    └── __init__.py
  

pyproject.toml 是 Poetry 用来管理项目配置和依赖的主要文件。

4.2 初始化现有项目

对于已经存在的 Python 项目，可以通过以下命令初始化 Poetry 项目，并生成相应的配置文件：

cd existing_project
poetry init

运行该命令后，Poetry 将引导你回答一系列问题，如项目名称、版本、作者、依赖包等，最终生成 pyproject.toml 文件。

4.3 配置 pyproject.toml

pyproject.toml 文件包含项目的元数据、依赖关系以及构建配置。以下是一个示例配置：

[tool.poetry]
name = "my_project"
version = "0.1.0"
description = "A short description of the project."
authors = ["Your Name <you@example.com>"]

[tool.poetry.dependencies]
python = "^3.7"
requests = "^2.25.1"

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

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"
  

其中，[tool.poetry.dependencies] 列出了项目的运行依赖，[tool.poetry.dev-dependencies] 列出了开发环境的依赖。

5. 依赖管理

5.1 添加依赖

使用以下命令添加项目的依赖包，Poetry 会自动更新 pyproject.toml 文件并安装依赖：

poetry add package_name

例如，添加 requests 库：

poetry add requests

5.2 添加开发依赖

如果需要添加仅在开发环境中使用的依赖包，可以使用 --group dev 选项：

poetry add --group dev pytest

这将把 pytest 添加到 [tool.poetry.dev-dependencies] 中。

5.3 移除依赖

使用以下命令移除项目的依赖包，Poetry 会自动更新配置文件和锁定文件：

poetry remove package_name

5.4 更新依赖

使用以下命令更新项目中所有依赖包至最新版本，Poetry 会更新 poetry.lock 文件以锁定新版本：

poetry update

5.5 安装依赖

如果已有 pyproject.toml 和 poetry.lock 文件，但依赖尚未安装，可以使用以下命令安装所有依赖：

poetry install

该命令会读取锁定文件，安装所有指定版本的依赖，确保环境一致性。

5.6 查看依赖树

使用以下命令可以查看项目的依赖树，了解每个依赖的依赖关系：

poetry show --tree

6. 虚拟环境管理

6.1 激活虚拟环境

Poetry 会自动为每个项目创建独立的虚拟环境，确保项目之间的依赖互不干扰。要激活虚拟环境，可以使用以下命令：

poetry shell

激活后，你将进入虚拟环境，所有 Python 命令将使用该环境的解释器和依赖。

6.2 运行脚本

如果无需手动激活虚拟环境，可以直接使用 poetry run 命令在虚拟环境中运行脚本或命令：

poetry run python script.py

这样可以确保命令在正确的环境中执行，避免环境切换的麻烦。

6.3 更改虚拟环境位置

默认情况下，Poetry 将虚拟环境存储在用户级目录下。如果希望将虚拟环境存储在项目目录中，可以使用以下命令：

poetry config virtualenvs.in-project true

执行后，虚拟环境将创建在项目根目录下的 .venv 文件夹中，便于版本控制和项目管理。

6.4 查看虚拟环境信息

使用以下命令查看当前项目的虚拟环境路径和相关信息：

poetry env info

7. 打包与发布

7.1 构建项目包

使用以下命令构建 Python 包，该命令将在项目根目录下生成 dist 文件夹，包含构建后的分发文件：

poetry build

构建结果通常包括一个源代码压缩包（.tar.gz）和一个 Wheel 包（.whl）。

7.2 发布到 PyPI

使用以下命令将项目发布到 Python 包索引（PyPI）：

poetry publish --username your-username --password your-password

为了提高安全性，建议使用 PyPI 提供的 API Token 进行身份验证，而不是直接使用密码。可以先在 PyPI 网站上生成 API Token，然后使用以下命令配置：

poetry config pypi-token.pypi your-api-token

然后，只需运行：

poetry publish

7.3 配置发布源

默认情况下，Poetry 以 PyPI 为发布源。如果需要配置其他发布源，例如私有仓库，可以使用以下命令：

poetry config repositories.<repo-name> <repo-url>

例如，配置一个名为 myrepo 的私有仓库：

poetry config repositories.myrepo https://example.com/simple/

然后，在发布时指定该仓库：

poetry publish --repository myrepo

8. 常用命令汇总

命令	说明
poetry new my_project	创建一个新的 Poetry 项目，并生成基本的项目结构。
poetry init	初始化现有项目，生成 pyproject.toml 文件。
poetry add package_name	添加一个运行时依赖包。
poetry add --group dev package_name	添加一个开发环境依赖包。
poetry remove package_name	移除一个依赖包。
poetry install	安装项目中所有声明的依赖。
poetry update	更新项目中所有依赖包至最新版本，并更新锁定文件。
poetry lock	根据 pyproject.toml 生成或更新锁定文件 poetry.lock。
poetry show	显示当前项目的依赖列表。
poetry show --tree	以树状结构显示依赖关系。
poetry shell	激活项目的虚拟环境。
poetry run command	在虚拟环境中运行指定的命令。
poetry build	构建项目包，生成分发文件。
poetry publish	发布项目包到指定的包索引。
poetry config	配置 Poetry 的各种设置，如仓库源、认证信息等。
poetry self update	更新 Poetry 到最新版本。

9. 高级功能与最佳实践

9.1 配置自定义脚本

Poetry 允许在 pyproject.toml 中配置自定义脚本，以简化常用任务。例如，添加一个测试脚本：

[tool.poetry.scripts]
test = "pytest"
  

这样可以通过以下命令运行测试：

poetry run test

9.2 集成版本控制

将 pyproject.toml 和 poetry.lock 文件纳入版本控制（如 Git）是最佳实践之一。这样可以确保团队成员使用相同的依赖版本，保持项目环境一致性。

9.3 使用多环境配置

Poetry 支持为不同的环境配置不同的依赖，使用 --group 选项可以管理多个依赖组。例如，除了开发依赖，还可以配置测试或生产环境的依赖。

9.4 配置私有仓库

如果项目需要访问私有的包仓库，可以通过以下命令添加私有仓库源：

poetry config repositories.myrepo https://example.com/simple/

然后，添加依赖时指定仓库：

poetry add package_name --source myrepo

9.5 自动化工作流

结合持续集成（CI）工具，如 GitHub Actions 或 GitLab CI，可以自动化测试、构建和发布流程。例如，使用以下配置文件在 GitHub Actions 中设置 Poetry 环境：

name: Python package

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Set up Python
      uses: actions/setup-python@v2
      with:
        python-version: '3.8'
    - name: Install Poetry
      run: curl -sSL https://install.python-poetry.org | python3 -
    - name: Configure Poetry PATH
      run: echo 'export PATH="$HOME/.local/bin:$PATH"' >> $GITHUB_ENV
    - name: Install dependencies
      run: poetry install --no-root
    - name: Run tests
      run: poetry run pytest

10. 示例：从创建到发布

10.1 创建项目

首先，使用 Poetry 创建一个新的项目：

poetry new my_project
cd my_project

这将在当前目录下创建一个名为 my_project 的文件夹，包含基本的项目结构。

10.2 添加依赖

添加必要的依赖包，如 requests：

poetry add requests

10.3 编写代码

编辑项目的主模块文件 my_project/my_project/__init__.py，添加以下代码：

import requests

def fetch_github_api():
    response = requests.get("https://api.github.com")
    if response.status_code == 200:
        return response.json()
    else:
        response.raise_for_status()

if __name__ == "__main__":
    data = fetch_github_api()
    print(data)

10.4 运行项目

使用 Poetry 运行项目脚本：

poetry run python my_project/__init__.py

这将执行脚本并输出 GitHub API 的响应内容。

10.5 编写测试

在 tests 目录下，添加测试文件 test_my_project.py：

from my_project import fetch_github_api

def test_fetch_github_api():
    data = fetch_github_api()
    assert isinstance(data, dict)
    assert 'current_user_url' in data

10.6 运行测试

使用 Poetry 运行测试：

poetry run pytest

10.7 构建项目包

构建项目包：

poetry build

这将在 dist 目录下生成 .tar.gz 和 .whl 文件。

10.8 发布到 PyPI

使用以下命令将项目发布到 PyPI：

poetry publish --username your-username --password your-password

发布成功后，你的包将在 PyPI 上可用，其他用户可以通过 pip install your_package 进行安装。

11. 注意事项

• Python 版本兼容性：确保项目指定的 Python 版本与目标环境兼容。可以在 pyproject.toml 中设置版本范围，如 ^3.7。
• 依赖冲突：如果遇到依赖冲突，尝试运行 poetry update 更新依赖，或者手动调整 pyproject.toml 中的版本约束。
• 私有包的认证：发布或安装私有仓库的包时，确保正确配置认证信息，避免发布失败或无法访问私有包。
• 环境变量管理：避免将敏感信息（如 API 密钥）直接写入代码，使用环境变量或配置文件进行管理，并通过 .gitignore 排除相关文件。
• 版本控制：将 pyproject.toml 和 poetry.lock 纳入版本控制，确保团队成员使用相同的依赖版本。
• 持续集成：结合 CI 工具自动化测试和部署流程，提高开发效率和代码质量。

12. 常见问题与解决方案

12.1 Poetry 命令未找到

如果在终端中运行 Poetry 命令提示未找到，可能是因为环境变量未正确配置。请确保已将 $HOME/.local/bin 添加到 PATH 中，并重新加载终端配置：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

12.2 依赖安装失败

依赖安装失败可能是由于网络问题或包源配置不正确。可以尝试更换 PyPI 镜像源，例如使用阿里云镜像：

poetry config repositories.pypi https://mirrors.aliyun.com/pypi/simple/

然后重新运行 poetry install。

12.3 虚拟环境创建失败

如果 Poetry 无法创建虚拟环境，可能是由于缺少必要的系统依赖。确保已安装 python3-venv 模块：

sudo apt install python3-venv

然后再次尝试创建或激活虚拟环境。

12.4 发布失败

发布到 PyPI 失败可能是由于认证信息错误或包名冲突。请检查上传凭据是否正确，并确保包名在 PyPI 上尚未被占用。

13. 参考资料

结论

通过以上详细步骤，你可以在 Linux 系统上成功安装并使用 Poetry 来管理你的 Python 项目。Poetry 简化了依赖管理和虚拟环境配置，使项目开发更加高效和可靠。掌握了这些基本操作后，你将能够更好地维护项目的稳定性，提升开发效率，并轻松进行包的构建与发布。