Skip to main content

Création et test du code Python

Vous pouvez créer un workflow d’intégration continue (CI) pour générer et tester votre projet Python.

Remarque : Les exécuteurs hébergés sur GitHub ne sont pas pris en charge sur GitHub Enterprise Server. Vous pouvez voir plus d’informations sur le support futur planifié dans la GitHub public roadmap.

Introduction

Ce guide explique comment générer, tester et publier un package Python.

Les exécuteurs hébergés dans GitHub ont un cache d’outils où des logiciels sont préinstallés, notamment Python et PyPy. Vous n’avez donc rien à installer ! Pour obtenir la liste complète des logiciels les plus récents et des versions préinstallées de Python et PyPy, consultez « Spécifications pour les exécuteurs hébergés dans GitHub ».

Prérequis

Vous devez être familiarisé avec YAML et la syntaxe GitHub Actions. Pour plus d’informations, consultez « Découvrir GitHub Actions ».

Il est recommandé de connaître les bases de Python, PyPy et pip. Pour plus d'informations, consultez les pages suivantes :

Utilisation d’exécuteurs auto-hébergés sur GitHub Enterprise Server

Quand vous utilisez des actions de configuration (comme actions/setup-LANGUAGE) sur GitHub Enterprise Server avec des exécuteurs auto-hébergés, vous pouvez être amené à configurer le cache des outils sur les exécuteurs qui n’ont pas accès à Internet. Pour plus d’informations, consultez « Configuration du cache d’outils sur les exécuteurs auto-hébergés sans accès à Internet ».

Utilisation du workflow de démarrage Python

GitHub fournit un workflow de démarrage Python qui doit fonctionner pour la plupart des projets Python. Ce guide inclut des exemples que vous pouvez utiliser pour personnaliser le workflow de démarrage. Pour plus d’informations, consultez le Workflow de démarrage Python.

Pour commencer rapidement, ajoutez le workflow de démarrage au répertoire .github/workflows de votre dépôt.

YAML
name: Python package

on: [push]

jobs:
  build:

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

    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

Spécification d’une version de Python

Pour utiliser une version préinstallée de Python ou de PyPy sur un exécuteur hébergé dans GitHub, utilisez l’action setup-python. Cette action recherche une version spécifique de Python ou de PyPy dans le cache d’outils de chaque exécuteur, et ajoute les fichiers binaires nécessaires à PATH, qui est conservé pour la suite du travail. Si une version spécifique de Python n’est pas préinstallée dans le cache d’outils, l’action setup-python télécharge et configure la version appropriée à partir du dépôt python-versions.

L’action setup-python est recommandée pour utiliser Python avec GitHub Actions, car cela garantit un comportement cohérent sur tous les exécuteurs et toutes les versions de Python. Si vous utilisez un exécuteur auto-hébergé, vous devez installer Python et l’ajouter à PATH. Pour plus d’informations, consultez l’action setup-python.

Le tableau ci-dessous décrit les emplacements du cache d’outils pour chaque exécuteur hébergé dans GitHub.

UbuntuMacWindows
Répertoire du cache d’outils/opt/hostedtoolcache/*/Users/runner/hostedtoolcache/*C:\hostedtoolcache\windows\*
Cache d’outils Python/opt/hostedtoolcache/Python/*/Users/runner/hostedtoolcache/Python/*C:\hostedtoolcache\windows\Python\*
Cache d’outils PyPy/opt/hostedtoolcache/PyPy/*/Users/runner/hostedtoolcache/PyPy/*C:\hostedtoolcache\windows\PyPy\*

Si vous utilisez un exécuteur auto-hébergé, vous pouvez configurer l’exécuteur afin qu’il utilise l’action setup-python pour gérer vos dépendances. Pour plus d’informations, consultez Utilisation de setup-python avec un exécuteur auto-hébergé dans le fichier README setup-python.

GitHub prend en charge la syntaxe du versioning sémantique. Pour plus d’informations, consultez « Utilisation du versioning sémantique » et « Spécification du versioning sémantique ».

Utilisation de plusieurs versions de 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.7", "3.8", "3.9", "3.10"]

    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)"

Utilisation d’une version spécifique de Python

Vous pouvez configurer une version spécifique de Python. Par exemple 3.9. Vous pouvez également utiliser la syntaxe de versioning sémantique pour obtenir la dernière version mineure. Cet exemple utilise la dernière version mineure de 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)"

Exclusion d’une version

Si vous spécifiez une version de Python qui n’est pas disponible, setup-python échoue avec une erreur comme celle-ci : ##[error]Version 3.4 with arch x64 not found. Le message d’erreur mentionne les versions disponibles.

Vous pouvez également utiliser le mot clé exclude dans votre workflow s’il existe une configuration de Python que vous ne souhaitez pas exécuter. Pour plus d’informations, consultez « Syntaxe des workflows pour 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.7", "3.8", "3.9", "3.10", pypy2, pypy3]
        exclude:
          - os: macos-latest
            python-version: "3.7"
          - os: windows-latest
            python-version: "3.7"

Utilisation de la version par défaut de Python

Nous vous recommandons d’utiliser setup-python pour configurer la version de Python qui est utilisée dans vos workflows, car cela permet de rendre vos dépendances explicites. Si vous n’utilisez pas setup-python, la version par défaut de Python qui est définie dans PATH sera utilisée dans n’importe quel interpréteur de commandes lorsque vous appellerez python. La version par défaut de Python varie en fonction de l’exécuteur hébergé dans GitHub, ce qui peut entraîner des modifications inattendues ou l’utilisation d’une version plus ancienne que prévu.

Exécuteur hébergé dans GitHubDescription
UbuntuPlusieurs versions de Python système sont installées sur les exécuteurs Ubuntu, sous /usr/bin/python et /usr/bin/python3. Les versions Python fournies avec Ubuntu viennent s’ajouter aux versions que GitHub installe dans le cache d’outils.
WindowsÀ l’exception des versions de Python qui se trouvent dans le cache d’outils, Windows n’est pas fourni avec une version équivalente de Python système. Pour maintenir un comportement cohérent avec les autres exécuteurs et permettre à Python d’être utilisé immédiatement sans l’action setup-python, GitHub ajoute quelques versions à PATH à partir du cache d’outils.
macOSPlusieurs versions de Python système sont installées sur les exécuteurs macOS, en plus des versions qui se trouvent dans le cache d’outils. Les versions de Python système se trouvent dans le répertoire /usr/local/Cellar/python/*.

Installer les dépendances

Le gestionnaire de package pip est installé sur les exécuteurs hébergés dans GitHub. Vous pouvez utiliser pip pour installer des dépendances à partir du registre de package PyPI avant de générer et de tester votre code. Par exemple, le code YAML ci-dessous installe ou met à niveau le programme d’installation du package pip, ainsi que les packages setuptools et wheel.

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

Fichier de spécifications

Une fois que vous avez mis à jour pip, l’étape qui suit classiquement consiste à installer les dépendances à partir de requirements.txt. Pour plus d’informations, consultez 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

Test de votre code

Vous pouvez utiliser les mêmes commandes que celles que vous utilisez localement pour générer et tester votre code.

Effectuer des tests avec pytest et pytest-cov

Cet exemple installe ou met à niveau pytest et pytest-cov. Les tests sont ensuite exécutés et une sortie est générée au format JUnit pendant que les résultats de couverture du code sont générés dans Cobertura. Pour plus d’informations, consultez JUnit et 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

Utilisation de Flake8 pour linter du code

L’exemple suivant installe ou met à niveau flake8, et l’utilise pour effectuer le linting de tous les fichiers. Pour plus d’informations, consultez 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 est défini dans l’étape de linting. Cela empêche le workflow d’échouer si l’étape de linting ne réussit pas. Une fois que vous avez résolu toutes les erreurs de linting, vous pouvez supprimer cette option afin que le workflow intercepte de nouveaux problèmes.

Exécution de tests avec tox

Avec GitHub Actions, vous pouvez exécuter des tests avec tox et répartir les tâches entre plusieurs travaux. Vous devez appeler tox à l’aide de l’option -e py pour choisir la version de Python de votre PATH, plutôt que de spécifier une version. Pour plus d’informations, consultez tox.

YAML
name: Python package

on: [push]

jobs:
  build:

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

    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

Empaquetage des données de workflow en tant qu’artefacts

Vous pouvez charger des artefacts à afficher une fois un workflow terminé. Par exemple, vous devrez peut-être enregistrer des fichiers journaux, des vidages principaux, des résultats de test ou des captures d’écran. Pour plus d’informations, consultez « Rendre persistantes des données de workflow à l’aide d’artefacts ».

L’exemple suivant montre comment utiliser l’action upload-artifact pour archiver les résultats des tests obtenus par l’exécution de pytest. Pour plus d’informations, consultez l’action upload-artifact.

YAML
name: Python package

on: [push]

jobs:
  build:

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

    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() }}

Publication dans des registres de package

Vous pouvez configurer votre workflow pour publier votre package Python dans un registre de package une fois vos tests CI réussis. Cette section montre comment utiliser GitHub Actions pour charger votre package sur PyPI chaque fois que vous publiez une version.

Pour cet exemple, vous devez créer deux jetons d’API PyPI. Vous pouvez utiliser des secrets pour stocker les jetons d’accès ou les informations d’identification nécessaires à la publication de votre package. Pour plus d’informations, consultez « Création et utilisation de secrets chiffrés ».

YAML
# Ce workflow utilise des actions qui ne sont pas certifiées par GitHub.
# Elles sont fournies par un tiers et régies par
# des conditions d’utilisation du service, une politique de confidentialité et un support distincts.
# documentation en ligne.

# GitHub recommande d’épingler les actions à un SHA de commit.
# Pour obtenir une version plus récente, vous devez mettre à jour le SHA.
# Vous pouvez également référencer une balise ou une branche, mais l’action peut changer sans avertissement.

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 }}

Pour plus d’informations sur le workflow de démarrage, consultez python-publish.