构建和测试 Python

注： GitHub 托管的运行器目前在 GitHub Enterprise Server 上不受支持。您可以在 GitHub 公共路线图上查看有关未来支持计划的更多信息。

简介

本指南介绍如何构建、测试和发布 Python 包。

GitHub 托管的运行器有工具缓存预安装的软件，包括 Python 和 PyPy。您� 需安装任何项目！有关最新版软件以及 Python 和 PyPy 预安装版本的完整列表，请参阅 GitHub 托管的运行器的规� �。

基本要求

您应该熟悉 YAML 和 GitHub Actions 的语法。更多信息请参阅“Learn GitHub Actions”。

建议您对 Python、PyPy 和 pip 有个基本的了解。更多信息请参阅：

在 GitHub Enterprise Server 上使用自托管的运行器

在包含自托管运行器的 GitHub Enterprise Server 上使用设置操作（例如 actions/setup-LANGUAGE）时，您可能需要在没有连接互联网的运行器上设置工具缓存。更多信息请参阅“在没有互联网连接的自托管运行器上设置工具缓存”。

Using the Python starter workflow

GitHub provides a Python starter workflow that should work for most Python projects. This guide includes examples that you can use to customize the starter workflow. For more information, see the Python starter workflow.

To get started quickly, add the starter workflow to the .github/workflows directory of your repository.

YAML

name: Python package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.6", "3.7", "3.8", "3.9"]

    steps:
      - uses: actions/checkout@v2
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v2
        with:
          python-version: ${{ matrix.python-version }}
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install flake8 pytest
          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
      - name: Lint with flake8
        run: |
          # stop the build if there are Python syntax errors or undefined names
          flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
          # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
          flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
      - name: Test with pytest
        run: |
          pytest

指定 Python 版本

要在 GitHub 托管的运行器上使用预安装的 Python 或 PyPy 版本，请使用 setup-python 操作。此操作从每个运行器上的工具缓存中查找特定版本的 Python 或 PyPy，并将必要的二进制文件添� 到 PATH，这可继续用于作业的其余部分。如果工具缓存中未安装特定版本的 Python，setup-python 操作将从 python-versions 仓库下载并设置适当的版本。

使用 setup-action 是 Python 与 GitHub Actions 结合使用时的推荐方式，� 为它能确保不同运行器和不同版本的 Python 行为一致。如果使用自托管运行器，则必须安装 Python 并将其添� 到 PATH。更多信息请参阅 setup-python 操作。

下表描述了每个 GitHub 托管的运行器中工具缓存的位置。

	Ubuntu	Mac	Windows
工具缓存目录	`/opt/hostedtoolcache/*`	`/Users/runner/hostedtoolcache/*`	`C:\hostedtoolcache\windows\*`
Python 工具缓存	`/opt/hostedtoolcache/Python/*`	`/Users/runner/hostedtoolcache/Python/*`	`C:\hostedtoolcache\windows\Python\*`
PyPy 工具缓存	`/opt/hostedtoolcache/PyPy/*`	`/Users/runner/hostedtoolcache/PyPy/*`	`C:\hostedtoolcache\windows\PyPy\*`

如果您正在使用自托管的运行器，则可以配置运行器使用 setup-python 操作来管理您的依赖项。更多信息请参阅 setup-python 自述文件中的

将 setup-python 与自托管运行器一起使用。

GitHub 支持语义版本控制语法。更多信息请参阅“使用语义版本控制”和“语义版本控制规范”。

使用多个 Python 版本

YAML

name: Python package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest
    strategy:
      # You can use PyPy versions in python-version.
      # For example, pypy2 and pypy3
      matrix:
        python-version: ["2.7", "3.6", "3.7", "3.8", "3.9"]

    steps:
      - uses: actions/checkout@v2
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v2
        with:
          python-version: ${{ matrix.python-version }}
      # You can test your matrix by printing the current Python version
      - name: Display Python version
        run: python -c "import sys; print(sys.version)"

使用特定的 Python 版本

您可以配置 python 的特定版本。例如，3.8。或者，您也可以使用语义版本语法来获得最新的次要版本。此示例使用 Python 3 最新的次要版本。

YAML

name: Python package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2
      - name: Set up Python 3.x
        uses: actions/setup-python@v2
        with:
          # Semantic version range syntax or exact version of a Python version
          python-version: '3.x'
          # Optional - x64 or x86 architecture, defaults to x64
          architecture: 'x64'
      # You can test your matrix by printing the current Python version
      - name: Display Python version
        run: python -c "import sys; print(sys.version)"

排除版本

如果指定不可用的 Python 版本，setup-python 将会失败，且显示如下错误：##[error]Version 3.4 with arch x64 not found。错误消息包含可用的版本。

如果存在您不想运行的 Python 配置，您也可以在工作流程中使用 exclude 关键字。更多信息请参阅“GitHub Actions 的工作流程语法”。

YAML

name: Python package

on: [push]

jobs:
  build:

    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python-version: ["3.6", "3.7", "3.8", "3.9", pypy2, pypy3]
        exclude:
          - os: macos-latest
            python-version: "3.6"
          - os: windows-latest
            python-version: "3.6"

使用默认 Python 版本

建议使用 setup-python 配置工作流程中使用的 Python 版本，� 为它有助于使您的依赖关系变得明朗。如果不使用 setup-python，调用 python 时将在任何 shell 中使用 PATH 中设置的 Python 默认版本。 GitHub 托管的运行器之间有不同的 Python 默认版本，这可能导致非预期的更改或使用的版本比预期更旧。

GitHub 托管的运行器	描述
Ubuntu	Ubuntu 运行器有多个版本的系统 Python 安装在 `/usr/bin/python` 和 `/usr/bin/python3` 下。 GitHub 除了安装在工具缓存中的版本，还有与 Ubuntu 一起打包的 Python 版本。
Windows	不包括工具缓存中的 Python 版本，Windows 未随附同等版本的系统 Python。为保持与其他运行器一致的行为，并允许 Python 在没有 `setup-python` 操作的情况下开箱即用，GitHub 将从工具缓存中添� � 个版本到 `PATH`。
macOS	除了作为工具缓存一部分的版本外，macOS 运行器还安装了多个版本的系统 Python。系统 Python 版本位于 `/usr/local/Cellar/python/*` 目录中。

安装依赖项

GitHub 托管的运行器安装了 pip 软件包管理器。在构建和测试代� �之前，您可以使用 pip 从 PyPI 软件包注册表安装依赖项。例如，下面的 YAML 安装或升级 pip 软件包安装程序以及 setuptools 和 wheel 软件包。

使用 GitHub 托管的运行器时，您还可以缓存依赖项以� 速工作流程。更多信息请参阅“缓存依赖项以� 快工作流程”。

YAML

steps:
- uses: actions/checkout@v2
- name: Set up Python
  uses: actions/setup-python@v2
  with:
    python-version: '3.x'
- name: Install dependencies
  run: python -m pip install --upgrade pip setuptools wheel

要求文件

在更新 pip 后，下一步通常是从 requires.txt 安装依赖项。更多信息请参阅 pip。

YAML

steps:
- uses: actions/checkout@v2
- name: Set up Python
  uses: actions/setup-python@v2
  with:
    python-version: '3.x'
- name: Install dependencies
  run: |
    python -m pip install --upgrade pip
    pip install -r requirements.txt

缓存依赖项

When using GitHub-hosted runners, you can cache and restore the dependencies using the setup-python action.

The following example caches dependencies for pip.

YAML

steps:
- uses: actions/checkout@v2
- uses: actions/setup-python@v2
  with:
    python-version: '3.9'
    cache: 'pip'
- run: pip install -r requirements.txt
- run: pip test

By default, the setup-python action searches for the dependency file (requirements.txt for pip or Pipfile.lock for pipenv) in the whole repository. For more information, see "Caching packages dependencies" in the setup-python actions README.

If you have a custom requirement or need finer controls for caching, you can use the cache action. Pip � �据运行器的操作系统将依赖项缓存在不同的位置。 The path you'll need to cache may differ from the Ubuntu example above, depending on the operating system you use. For more information, see Python caching examples in the cache action repository.

测试代� �

您可以使用与本地相同的命令来构建和测试代� �。

使用 pytest 和 pytest-cov 测试

此示例安装或升级 pytest 和 pest-cov。然后进行测试并以 JUnit � �式输出，而代� �覆盖结果则以 Cobertura 输出。更多信息请参阅 JUnit 和 Cobertura。

YAML

steps:
- uses: actions/checkout@v2
- name: Set up Python
  uses: actions/setup-python@v2
  with:
    python-version: '3.x'
- name: Install dependencies
  run: |
    python -m pip install --upgrade pip
    pip install -r requirements.txt
- name: Test with pytest
  run: |
    pip install pytest
    pip install pytest-cov
    pytest tests.py --doctest-modules --junitxml=junit/test-results.xml --cov=com --cov-report=xml --cov-report=html

使用 Flake8 嵌入代� �

下面的示例安装或升级 flake8 并用它来嵌入所有文件。更多信息请参阅 Flake8。

YAML

steps:
- uses: actions/checkout@v2
- name: Set up Python
  uses: actions/setup-python@v2
  with:
    python-version: '3.x'
- name: Install dependencies
  run: |
    python -m pip install --upgrade pip
    pip install -r requirements.txt
- name: Lint with flake8
  run: |
    pip install flake8
    flake8 .
  continue-on-error: true

嵌入步骤设置了 continue-on-error: true。这可防止在嵌入步骤不成功时工作流程失败。解决所有嵌入错误后，您可以� 除此选项，以便工作流程捕获新问题。

使用 tox 运行测试

通过 GitHub Actions，您可以使用 tox 运行测试并将工作分散到多个作业。您需要使用 -e py 选项调用 tox，以在 PATH 中选择 Python 版本，而不是指定特定版本。更多信息请参阅 tox。

YAML

name: Python package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest
    strategy:
      matrix:
        python: ["3.7", "3.8", "3.9"]

    steps:
      - uses: actions/checkout@v2
      - name: Setup Python
        uses: actions/setup-python@v2
        with:
          python-version: ${{ matrix.python }}
      - name: Install tox and any other packages
        run: pip install tox
      - name: Run tox
        # Run tox using the version of Python in `PATH`
        run: tox -e py

将工作流数据打包为构件

您可以在工作流程完成后上� 构件以查看。例如，您可能需要保存日志文件、� �心转储、测试结果或屏幕截图。更多信息请参阅“使用构件持久化工作流程”。

下面的示例演示如何使用 upload-artifact 操作来存档运行 pytest 的测试结果。更多信息请参阅 upload-artifact 操作。

YAML

name: Python package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.6", "3.7", "3.8", "3.9"]

    steps:
      - uses: actions/checkout@v2
      - name: Setup Python # Set Python version
        uses: actions/setup-python@v2
        with:
          python-version: ${{ matrix.python-version }}
      # Install pip and pytest
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install pytest
      - name: Test with pytest
        run: pytest tests.py --doctest-modules --junitxml=junit/test-results-${{ matrix.python-version }}.xml
      - name: Upload pytest test results
        uses: actions/upload-artifact@v2
        with:
          name: pytest-results-${{ matrix.python-version }}
          path: junit/test-results-${{ matrix.python-version }}.xml
        # Use always() to always run this step to publish test results when there are test failures
        if: ${{ always() }}

发布到包注册表

您可以配置工作流程在 CI 测试通过后将 Python 包发布到包注册表。此部分展示在您每次发布版本时如何使用 GitHub Actions 将包上� 到 PyPI。

在本例中，您将需要创建两个 PyPI API 令牌。您可以使用机密来存储发布软件包所需的访问令牌或凭据。更多信息请参阅“创建和使用� 密密� �”。

YAML

# 此工作流使用未经 GitHub 认证的操作。
# 它们由第三方提供，并受
# 单独的服务条款、隐私政策和支持
# 文档管理。

name: Upload Python Package

on:
  release:
    types: [published]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Set up Python
        uses: actions/setup-python@v2
        with:
          python-version: '3.x'
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install build
      - name: Build package
        run: python -m build
      - name: Publish package
        uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
        with:
          user: __token__
          password: ${{ secrets.PYPI_API_TOKEN }}

For more information about the starter workflow, see python-publish.

构建和测试 Python

本文内容

简介

基本要求

在 GitHub Enterprise Server 上使用自托管的运行器

Using the Python starter workflow

指定 Python 版本

使用多个 Python 版本

使用特定的 Python 版本

排除版本

使用默认 Python 版本

安装依赖项

要求文件

缓存依赖项

测试代� �

使用 pytest 和 pytest-cov 测试

使用 Flake8 嵌入代� �

使用 tox 运行测试

将工作流数据打包为构件

发布到包注册表