如何在GitHub Actions中安装使用构建的Python包制品

问题背景 #

此前构建PyPDF2的PyPI发布包时出现配置失误：packages配置遗漏了一个子包，导致当时CI流程校验全部通过，但所有通过PyPI安装PyPDF2==2.3.0版本的用户在导入PyPDF2时都会触发报错。
问题核心原因：遗漏的子包存储在代码仓库中，但并未被打包进最终生成的分发包内。需要在CI流程中提前校验构建出的分发包文件，目前已完成包的构建步骤，仍有两个待解决问题：

• 如何安装本次构建生成的本地包制品
• 执行测试时如何确保pytest调用的是已安装的包制品，而非本地目录下的PyPDF2源码文件夹

现有构建配置 #

当前在GitHub Actions中使用的包构建配置如下：

package:
    name: Build & verify package
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v3
        with:
          python-version: ${{env.PYTHON_LATEST}}

      - run: python -m pip install build twine check-wheel-contents
      - run: python -m build --sdist --wheel .
      - run: ls -l dist
      - run: check-wheel-contents dist/*.whl
      - name: Check long_description
        run: python -m twine check dist/*

具体实现方法 #

1. 安装本地构建的包制品 #

构建完成后，dist目录下会生成.whl格式的二进制wheel包和.tar.gz格式的源码包，直接通过pip指定本地路径安装即可，优先安装wheel包，和普通用户从PyPI安装的场景完全一致：

python -m pip install dist/*.whl

注意：不要使用-e可编辑模式安装，该模式会直接关联本地源码，无法达到测试发布包的目的。

2. 确保pytest导入已安装的包而非本地源码 #

Python导入模块的默认优先级为：当前执行目录 > 已安装的第三方包目录，只要执行pytest时的工作目录下不存在PyPDF2源码文件夹，Python就会自动导入安装到site-packages目录下的包制品。
操作方式很简单：执行测试前新建一个空的临时目录，切换到该目录下，再通过绝对路径指定测试用例的位置执行pytest即可。

可以在执行测试前先运行导入校验命令，打印包的实际导入路径，确认导入来源正确：

python -c "import PyPDF2; print(PyPDF2.__file__)"

如果输出路径包含site-packages，说明导入的是已安装的包制品；如果输出路径指向仓库源码目录，说明工作目录切换有误。

修改后的完整CI配置 #

package:
    name: Build & verify package
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v3
        with:
          python-version: ${{env.PYTHON_LATEST}}

      - run: python -m pip install build twine check-wheel-contents pytest
      - run: python -m build --sdist --wheel .
      - run: ls -l dist
      - run: check-wheel-contents dist/*.whl
      - name: Check long_description
        run: python -m twine check dist/*
      
      # 安装本地构建完成的wheel包
      - name: Install built package artifact
        run: python -m pip install dist/*.whl
      
      # 切换到临时目录执行测试，避免导入本地源码
      - name: Run tests against installed package
        run: |
          mkdir -p /tmp/package_verify
          cd /tmp/package_verify
          # 校验导入路径是否正确
          python -c "import PyPDF2; print(f'Import PyPDF2 from: {PyPDF2.__file__}')"
          # 执行测试，传入测试目录的绝对路径
          pytest ${{github.workspace}}/tests

内容的提问来源于stack exchange，提问作者Martin Thoma