安装 Poetry Action

这是一个用于安装和配置 Poetry 的 Github action。

该 action 安装 Poetry，将可执行文件添加到运行器系统路径，并设置相关的 Poetry 配置。

使用方法

如果你只需要默认的 Poetry，只需在你的工作流中添加以下内容：

- name: 安装 Poetry
  uses: snok/install-poetry@v1

如果你想设置 Poetry 配置或安装特定版本，可以指定输入：

- name: 安装和配置 Poetry
  uses: snok/install-poetry@v1
  with:
    version: 1.5.1
    virtualenvs-create: true
    virtualenvs-in-project: false
    virtualenvs-path: ~/my-custom-path
    installer-parallel: true

如果你需要向安装程序脚本传递额外的参数，可以使用 installation-arguments 指定这些参数。

该 action 在 macOS 和 Ubuntu 运行器上经过充分测试，适用于 Poetry 版本 >= 1.1。如果你在 Windows 上使用它，请参阅 在 Windows 上运行 部分。

默认设置

当前的默认设置为：

version: latest
virtualenvs-create: true
virtualenvs-in-project: false
virtualenvs-path: {cache-dir}/virtualenvs
installer-parallel: true

你可以使用 installation-arguments 直接向 poetry 安装程序指定安装参数，方法如下：

- name: 安装和配置 Poetry
  uses: snok/install-poetry@v1
  with:
    installation-arguments: --git https://github.com/python-poetry/poetry.git@69bd6820e320f84900103fdf867e24b355d6aa5d

如果你想进行进一步的配置更改 - 例如，更改某个 experimental Poetry 配置设置，或者只是在调用 action 后更改 Poetry 配置 - 你可以在后续步骤中这样做：

- uses: snok/install-poetry@v1
- run: poetry config experimental.new-installer false

工作流示例和提示

本节包含一系列工作流示例，旨在帮助

• 为你设置自己的工作流程提供一个起点
• 演示如何实现缓存以提高性能
• 澄清不同设置的含义

一些示例可能比较长，所以这里有一些链接

• 安装 Poetry Action
  • 使用方法
  • 默认设置
  • 工作流示例和提示
    • 测试
    • 使用矩阵进行测试
    • Codecov 上传
    • 在 Windows 上运行
      • 在 Windows 运行器上缓存
    • 虚拟环境变化
    • 缓存 Poetry 安装
    • 安装 Poetry 插件
  • 贡献
  • 许可证
  • 显示你的支持

测试

运行测试套件的基本示例工作流可以这样构建：

name: test

on: pull_request

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      #----------------------------------------------
      #       检出仓库并设置 python
      #----------------------------------------------
      - name: 检出仓库
        uses: actions/checkout@v4
      - name: 设置 python
        id: setup-python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      #----------------------------------------------
      #  -----  安装 & 配置 poetry  -----
      #----------------------------------------------
      - name: 安装 Poetry
        uses: snok/install-poetry@v1
        with:
          virtualenvs-create: true
          virtualenvs-in-project: true
          virtualenvs-path: .venv
          installer-parallel: true

      #----------------------------------------------
      #       如果缓存存在，加载缓存的 venv
      #----------------------------------------------
      - name: 加载缓存的 venv
        id: cached-poetry-dependencies
        uses: actions/cache@v4
        with:
          path: .venv
          key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}
      #----------------------------------------------
      # 如果缓存不存在，安装依赖
      #----------------------------------------------
      - name: 安装依赖
        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
        run: poetry install --no-interaction --no-root
      #----------------------------------------------
      # 安装你的根项目，如果需要的话
      #----------------------------------------------
      - name: 安装项目
        run: poetry install --no-interaction
      #----------------------------------------------
      #              运行测试套件
      #----------------------------------------------
      - name: 运行测试
        run: |
          source .venv/bin/activate
          pytest tests/
          coverage report

使用矩阵进行测试

对于在多个操作系统、Python 版本或包版本组合上运行测试套件的更广泛示例，可以这样构建：

linting 作业与矩阵无关，仅作为灵感包含。

name: test

on: pull_request

jobs:
  linting:
    runs-on: ubuntu-latest
    steps:
      #----------------------------------------------
      #       检出仓库并设置 python
      #----------------------------------------------
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
      #----------------------------------------------
      #        如果缓存存在，加载 pip 缓存
      #----------------------------------------------
      - uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip
          restore-keys: ${{ runner.os }}-pip
      #----------------------------------------------
      #          安装并运行 linters
      #----------------------------------------------
      - run: python -m pip install black flake8 isort
      - run: |
          flake8 .
          black . --check
          isort .
  test:
    needs: linting
    strategy:
      fail-fast: true
      matrix:
        os: [ "ubuntu-latest", "macos-latest" ]
        python-version: [ "3.8", "3.9", "3.10", "3.11", "3.12" ]
        django-version: [ "4", "5" ]
    runs-on: ${{ matrix.os }}
    steps:
      #----------------------------------------------
      #       检出仓库并设置 python
      #----------------------------------------------
      - name: 检出仓库
        uses: actions/checkout@v4
      - name: 设置 python ${{ matrix.python-version }}
        id: setup-python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      #----------------------------------------------
      #  -----  安装 & 配置 poetry  -----
      #----------------------------------------------
      - name: 安装 Poetry
        uses: snok/install-poetry@v1
        with:
          virtualenvs-create: true
          virtualenvs-in-project: true
      #----------------------------------------------
      #       如果缓存存在，加载缓存的 venv
      #----------------------------------------------
      - name: 加载缓存的 venv
        id: cached-poetry-dependencies
        uses: actions/cache@v4
        with:
          path: .venv
          key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}
      #----------------------------------------------
      # 如果缓存不存在，安装依赖
      #----------------------------------------------
      - name: 安装依赖
        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
        run: poetry install --no-interaction --no-root
      #----------------------------------------------
      # 安装你的根项目，如果需要的话
      #----------------------------------------------
      - name: 安装库
        run: poetry install --no-interaction
      #----------------------------------------------
      #    添加矩阵特定内容并运行测试套件
      #----------------------------------------------
      - name: 安装 django ${{ matrix.django-version }}
        run: |
          source .venv/bin/activate
          pip install "Django==${{ matrix.django-version }}"
      - name: 运行测试
        run: |
          source .venv/bin/activate
          pytest tests/
          coverage report

Codecov 上传

本节包含一个简单的 codecov 上传。更多信息请参见 codecov action。

name: coverage

on:
  push:
    branches:
      - master

jobs:
  codecov:
    runs-on: ubuntu-latest
    steps:
      #----------------------------------------------
      #       检出仓库并设置 python
      #----------------------------------------------
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        id: setup-python
        with:
          python-version: '3.12'
      #----------------------------------------------
      #  -----  安装 & 配置 poetry  -----
      #----------------------------------------------
      - name: 安装 Poetry
        uses: snok/install-poetry@v1
        with:
          virtualenvs-create: true
          virtualenvs-in-project: true
      #----------------------------------------------
      #       如果缓存存在，加载缓存的 venv
      #----------------------------------------------
      - name: 加载缓存的 venv
        id: cached-poetry-dependencies
        uses: actions/cache@v4
        with:
          path: .venv
          key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}
      #----------------------------------------------
      # 如果缓存不存在，安装依赖
      #----------------------------------------------
      - name: 安装依赖
        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
        run: poetry install --no-interaction --no-root
      #----------------------------------------------
      # 安装你的根项目，如果需要的话
      #----------------------------------------------
      - name: 安装库
        run: poetry install --no-interaction
      #----------------------------------------------
      #    运行测试套件并输出覆盖率文件
      #----------------------------------------------
      - name: 使用 pytest 测试
        run: poetry run pytest --cov=<project-dir> --cov-report=xml
      #----------------------------------------------
      #             上传覆盖率统计
      # (需要在仓库 secrets 中设置 CODECOV_TOKEN)
      #----------------------------------------------
      - name: 上传覆盖率
        uses: codecov/codecov-action@v3
        with:
          token: ${{ secrets.CODECOV_TOKEN }}  # 仅私有仓库需要
          file: ./coverage.xml
          fail_ci_if_error: true

在 Windows 上运行

在 Windows 上运行此 action 是支持的，但有两点需要注意：

1. 你需要将作业级别的默认 shell 设置为 bash

   defaults:
     run:
       shell: bash

2. 如果你正在运行一个操作系统矩阵，并且想要在项目中激活你的 venv，你必须处理不同操作系统上的不同文件夹结构。要使其工作，你可以这样做

   - run: |
       source .venv/scripts/activate
       pytest --version
     if: runner.os == 'Windows'
   - run: |
       source .venv/bin/activate
       pytest --version
     if: runner.os != 'Windows'

但我们认为这种结构化工作流程的方式很烦人，所以我们设置了一个自定义环境变量 $VENV，它会指向特定操作系统的 venv 激活脚本，无论你运行的是 UNIX 还是 Windows。这意味着你可以这样做：

- run: |
    source $VENV
    pytest --version

作为参考，使用 windows-latest 的完整操作系统矩阵可以这样设置：

name: test

on: pull_request

jobs:
  test-windows:
    strategy:
      matrix: [ "ubuntu-latest", "macos-latest", "windows-latest" ]
    defaults:
      run:
        shell: bash
    runs-on: ${{ matrix.os }}
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
      - name: Set up python
        id: setup-python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - name: Install Poetry
        uses: snok/install-poetry@v1
        with:
          virtualenvs-create: true
          virtualenvs-in-project: true
      - name: Load cached venv
        id: cached-pip-wheels
        uses: actions/cache@v4
        with:
          path: ~/.cache
          key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}
      - name: Install dependencies
        run: poetry install --no-interaction --no-root
      - name: Install library
        run: poetry install --no-interaction
      - run: |
          source $VENV
          pytest --version

Windows 运行器上的缓存

由于某些原因，在 Windows 运行器上缓存你的 venv 似乎不能按预期工作。你可以在这里看到一个例子，其中一个工作流停滞并运行了超过3小时，直到被手动取消。

如果你确实想在 Windows 运行器上缓存你的依赖项，你应该考虑缓存你的 pip wheels 而不是你的 venv；这似乎可以正常工作。

虚拟环境变化

我们添加的所有示例都使用了这些 Poetry 设置

- name: Install Poetry
  uses: snok/install-poetry@v1
  with:
    virtualenvs-create: true
    virtualenvs-in-project: true

虽然这应该适用于大多数情况，而且我们通常更喜欢在项目中创建我们的 virtualenvs 以使缓存步骤尽可能简单，但有一些合理的理由不想在项目目录中构建 venv。

有两种其他相关的场景：

1. 创建 venv，但不在项目目录中

   如果你使用默认设置，venv 位置会从 .venv 变为使用 {cache-dir}/virtualenvs。你也可以将路径更改为你喜欢的任何位置。不过，通常这会让事情变得有点棘手，因为目录会根据操作系统而变化，使得编写与操作系统无关的工作流程变得更加困难。

   解决这个问题的一种方法是完全绕过这个问题，利用 Poetry 的 poetry run 命令。

   以矩阵测试示例中的最后两个步骤为例，这是我们之前记录的安装特定于矩阵的依赖项并运行测试套件的方法：

   - name: Install django ${{ matrix.django-version }}
     run: |
       source .venv/bin/activate
       pip install "Django==${{ matrix.django-version }}"
   - name: Run tests
     run: |
       source .venv/bin/activate
       pytest tests/
       coverage report

   使用远程 venv，你可以这样做：

   - name: Install django ${{ matrix.django-version }}
     run: poetry add "Django==${{ matrix.django-version }}"
   - name: Run tests
     run: |
       poetry run pytest tests/
       poetry run coverage report

   我们在工作流程中从未需要缓存远程 venv。 如果你有这方面的经验，欢迎提交 PR 解释如何做到这一点。

2. 跳过 venv 创建

   如果你想跳过 venv 创建，只需删除 venv 激活行：source .venv/bin/activate，原始示例就都变得有效了。

   要在这种情况下启用缓存，你可能需要设置类似于矩阵测试中 linting 作业缓存步骤的东西；缓存你的 pip wheels 而不是已安装的依赖项。

   由于你没有缓存整个 venv，你每次运行作业时都需要重新安装依赖项；然而，缓存仍然会为你节省下载 wheels 所需的时间（并且会减少对 PyPi 的压力）。

缓存 Poetry 安装

除了缓存 Python 依赖项外，你可能会发现缓存 Poetry 安装本身也很有用。这应该可以减少总运行时间约 10 秒，并减少此操作运行时间的约 95%。

name: test

on: pull_request

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
      - name: Set up python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - name: Load cached Poetry installation
        id: cached-poetry
        uses: actions/cache@v4
        with:
          path: ~/.local  # 路径取决于操作系统
          key: poetry-0  # 递增以重置缓存
      - name: Install Poetry
        if: steps.cached-poetry.outputs.cache-hit != 'true'
        uses: snok/install-poetry@v1

要缓存的目录将取决于运行器的操作系统。

请注意，当缓存命中并且跳过了 Install Poetry 步骤时，配置选项不会重新应用。缓存的 Poetry 安装现在将以默认设置运行。为了使事情保持一致，你可以添加一个专门的配置步骤来重新应用你的配置。例如：

- name: Configure poetry
  if: steps.cached-poetry.outputs.cache-hit == 'true'
  run: poetry config virtualenvs.in-project true

或者考虑使用 config.toml 文件来存储你的配置选项。详情请参见 Poetry 配置文档。

安装 Poetry 插件

使用 Poetry 1.2 或更高版本，你可以使用此操作安装插件：

- uses: snok/install-poetry@v1
  with:
    plugins: poetry-plugin-a

你可以使用空格分隔的列表：

- uses: snok/install-poetry@v1
  with:
    plugins: |
      poetry-plugin-a
      poetry-plugin-b

贡献

欢迎随时贡献；提交 PR！

许可证

install-poetry 使用 MIT 许可证。有关详细信息，请参阅许可证文件。

表示支持

如果这个项目对你有帮助，请留下⭐️！