Erstellen und Testen eines Python-Projekts

Einführung

Diese Anleitung zeigt Dir, wie du ein Python-Paket baust, testest und veröffentlichst.

GitHub-gehostete Runner haben einen Toolcache mit vorinstallierter Software, die Python und PyPy einschließt. Du brauchst nichts zu installieren! Eine vollständige Liste der aktuellen Software und der vorinstallierten Versionen von Python und PyPy findest du unter Verwenden von auf GitHub gehosteten Runnern.

Voraussetzungen

Du solltest mit YAML und der Syntax für GitHub Actions vertraut sein. Weitere Informationen findest du unter Informationen zu GitHub Actions.

Du solltest ein grundlegendes Verständnis von Python und pip haben. Weitere Informationen finden Sie unter:

• Erste Schritte mit Python
• Pip-Paket-Manager

Verwenden eines Python-Starterworkflows

Für einen schnellen Einstieg füge einen Starterworkflow zum Verzeichnis .github/workflows deines Repositorys hinzu.

GitHub stellt einen Startworkflow für Python bereit, der funktionieren soll, wenn dein Repository bereits mindestens eine .py-Datei enthält. In den nachfolgenden Abschnitten dieser Anleitung finden Sie Beispiele dafür, wie dieser Starterworkflow angepasst werden kann.

1. Navigiere auf GitHub.com zur Hauptseite des Repositorys.

2. Klicke unter dem Namen deines Repositorys auf Aktionen.

   

3. Wenn du bereits über einen Workflow im Repository verfügst, klicke auf Neuer Workflow.

4. Die Seite „Workflow auswählen“ zeigt eine Auswahl empfohlener Startworkflows. Suchen Sie nach „Python-Anwendung“.

5. Klicken Sie im Workflow „Python-Anwendung“ auf Konfigurieren.

6. Bearbeiten Sie den Workflow nach Bedarf. Ändern Sie beispielsweise die Python-Version.

7. Klicke auf Änderungen committen.

Die python-app.yml-Workflowdatei wird dem .github/workflows-Verzeichnis Ihres Repositorys hinzugefügt.

Eine Python-Version angeben

Verwende die Aktion setup-python, um eine vorinstallierte Version von Python oder PyPy für einen von GitHub gehosteten Runner zu verwenden. Mit dieser Aktion wird im Toolcache der jeweiligen Runner nach einer bestimmten Version von Python oder PyPy gesucht, und die erforderlichen Binärdateien werden zu PATH hinzugefügt, das für den Rest des Auftrags bestehen bleibt. Wenn eine bestimmte Version von Python im Toolcache nicht vorinstalliert ist, wird die entsprechende Version mit der Aktion setup-python aus dem Repository python-versions heruntergeladen und eingerichtet.

Die Aktion setup-python wird als Methode zur Verwendung von Python mit GitHub Actions empfohlen, da damit ein konsistentes Verhalten bei verschiedenen Runnern und verschiedenen Version von Python gewährleistet wird. Wenn du einen selbst gehosteten Runner verwendest, musst du Python installieren und zu PATH hinzufügen. Weitere Informationen findest du im Artikel über die Aktion setup-python.

Die folgende Tabelle zeigt für jeden GitHub-gehosteten Runner, wo der Tools-Cache liegt.

Wenn du einen selbst gehosteten Runner verwendest, kannst du ihn so konfigurieren, dass die Aktion setup-python zum Verwalten von Abhängigkeiten verwendet wird. Weitere Informationen findest du unter Verwenden von „setup-python“ mit einem selbst gehosteten Runner in der Infodatei zu setup-python.

GitHub unterstützt dir Syntax für semantische Versionierung. Weitere Informationen findest du unter Using semantic versioning (Verwenden der semantischen Versionsverwaltung) und unter Semantic versioning specification (Spezifikation zur semantischen Versionsverwaltung).

Mehrere Python-Versionen verwenden

Im folgenden Beispiel wird eine Matrix für den Auftrag verwendet, um mehrere Python-Versionen einzurichten. Weitere Informationen findest du unter Verwenden von Matrizen für deine Aufträge.

name: Python package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["pypy3.9", "pypy3.10", "3.9", "3.10", "3.11", "3.12"]

    steps:
      - uses: actions/checkout@v4
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v4
        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)"

name: Python package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["pypy3.9", "pypy3.10", "3.9", "3.10", "3.11", "3.12"]

    steps:
      - uses: actions/checkout@v4
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v4
        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)"

Eine bestimmten Python-Version verwenden

Du kannst eine bestimmte Version von Python konfigurieren. Beispiel: 3.10. Alternativ kannst du auch Syntax für semantische Versionierung verwenden, um die neuste Nebenversion abzurufen. Dieses Beispiel verwendet das neueste Minor Release von Python 3.

name: Python package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        # This is the version of the action for setting up Python, not the Python version.
        uses: actions/setup-python@v4
        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)"

name: Python package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        # This is the version of the action for setting up Python, not the Python version.
        uses: actions/setup-python@v4
        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)"

Eine Version ausschließen

Wenn du eine nicht verfügbare Python-Version angibst, schlägt setup-python mit einer Fehlermeldung wie der folgenden fehl: ##[error]Version 3.6 with arch x64 not found. Die Fehlermeldung enthält die verfügbaren Versionen.

Du kannst im Workflow auch das Schlüsselwort exclude verwenden, wenn es eine Konfiguration von Python gibt, die du nicht verwenden möchtest. Weitere Informationen findest du unter Workflowsyntax für GitHub Actions.

name: Python package

on: [push]

jobs:
  build:

    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python-version: ["3.9", "3.10", "3.11", "pypy3.9", "pypy3.10"]
        exclude:
          - os: macos-latest
            python-version: "3.9"
          - os: windows-latest
            python-version: "3.9"

name: Python package

on: [push]

jobs:
  build:

    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python-version: ["3.9", "3.10", "3.11", "pypy3.9", "pypy3.10"]
        exclude:
          - os: macos-latest
            python-version: "3.9"
          - os: windows-latest
            python-version: "3.9"

Die Standard-Version von Python verwenden

Es wird empfohlen, setup-python zu verwenden, um die in den eigenen Workflows verwendete Version von Python zu konfigurieren, da du so Abhängigkeiten explizit machen kannst. Wenn du setup-python nicht verwendest, wird die in PATH festgelegte Standardversion von Python in allen Shells beim Aufrufen von python verwendet. Die Standardversion von Python variiert zwischen den GitHub-gehosteten Runnern. Dies kann zu unerwarteten Abweichungen führen oder es kann unerwartet eine ältere Version verwendet werden.

Installieren von Abhängigkeiten

Auf GitHub-gehosteten Runnern ist der Paketmanager pip installiert. Du kannst pip verwenden, um Abhängigkeiten von der PyPI-Paket-Registry zu installieren, bevor du deinen Code baust und testest. Mit dem folgenden YAML-Code werden beispielsweise das pip-Paketinstallationsprogramm und die Pakete setuptools und wheel installiert oder aktualisiert.

Du kannst Abhängigkeiten auch im Cache zwischenspeichern, um deinen Workflow zu beschleunigen. Weitere Informationen findest du unter Abhängigkeiten zwischenspeichern um Workflows zu beschleunigen.

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

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

Datei für „Requirements“ (Anforderungen)

Nach dem Aktualisieren von pip werden in der Regel als Nächstes Abhängigkeiten aus der Datei requirements.txt installiert. Weitere Informationen findest du unter pip.

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

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

Abhängigkeiten im Cache zwischenspeichern

Du kannst die Abhängigkeiten mithilfe der Aktion setup-python zwischenspeichern und wiederherstellen.

Im folgenden Beispiel werden Abhängigkeiten für pip zwischengespeichert.

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

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

Standardmäßig sucht die Aktion setup-python im gesamten Repository nach der Abhängigkeitsdatei (requirements.txt für pip, Pipfile.lock für pipenv oder poetry.lock für poetry). Weitere Informationen findest du unter Zwischenspeichern von Paketabhängigkeiten in der Infodatei zu setup-python.

Wenn du eine benutzerdefinierte Anforderung verwendest oder genauere Steuerungsmöglichkeiten zum Zwischenspeichern benötigst, kannst du die Aktion cache verwendest. Mit pip werden Abhängigkeiten je nach dem Betriebssystem des Runners an anderen Speicherorten zwischengespeichert. Der Pfad, den du zwischenspeichern musst, unterscheidet sich möglicherweise vom obigen Ubuntu-Beispiel, je nachdem, welches Betriebssystem du verwendest. Weitere Informationen findest du unter Beispiele zum Zwischenspeichern bei Python im Repository der Aktion cache.

Testen von Code

Du kannst die gleichen Befehle verwenden, die du auch lokal verwendest, um deinen Code zu bauen und zu testen.

Mit pytest und pytest-cov testen

In diesem Beispiel werden pytest und pytest-cov installiert und aktualisiert. Tests werden dann im JUnit-Format ausgeführt und ausgegeben, während die Code Coverage-Ergebnisse in Cobertura ausgegeben werden. Weitere Informationen findest du unter JUnit und Cobertura.

steps:
- uses: actions/checkout@v4
- name: Set up Python
  uses: actions/setup-python@v4
  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 pytest-cov
    pytest tests.py --doctest-modules --junitxml=junit/test-results.xml --cov=com --cov-report=xml --cov-report=html

steps:
- uses: actions/checkout@v4
- name: Set up Python
  uses: actions/setup-python@v4
  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 pytest-cov
    pytest tests.py --doctest-modules --junitxml=junit/test-results.xml --cov=com --cov-report=xml --cov-report=html

Verwenden von Ruff zum Linten von Code

Im folgenden Beispiel wird ruff installiert oder aktualisiert und zum Linten aller Dateien verwendet. Weitere Informationen findest du unter Ruff.

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

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

Beim Lintingschritt wurde continue-on-error: true festgelegt. Dadurch wird verhindert, dass der Workflow fehlschlägt, wenn der Lintingschritt nicht erfolgreich ist. Nachdem du alle Lintingfehler behoben hast, kannst du diese Option entfernen, sodass beim Workflow neue Issues erfasst werden können.

Tests mit Tox ausführen

Mit GitHub Actions kannst du Texts mit tox ausführen und die Arbeit auf mehrere Aufträge verteilen. Du musst tox mit der Option -e py aufrufen, um die Version von Python im eigenen PATH auszuwählen, statt eine bestimmte Version anzugeben. Weitere Informationen findest du unter tox.

name: Python package

on: [push]

jobs:
  build:

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

    steps:
      - uses: actions/checkout@v4
      - name: Setup Python
        uses: actions/setup-python@v4
        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

name: Python package

on: [push]

jobs:
  build:

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

    steps:
      - uses: actions/checkout@v4
      - name: Setup Python
        uses: actions/setup-python@v4
        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

Workflow-Daten als Artefakte paketieren

Du kannst Artefakte hochladen, um sie nach Abschluss eines Workflows anzuzeigen. Zum Beispiel kann es notwendig sein, Logdateien, Core Dumps, Testergebnisse oder Screenshots zu speichern. Weitere Informationen findest du unter Speichern von Workflowdaten als Artefakte.

Im folgenden Beispiel wird gezeigt, wie die Aktion upload-artifact zum Archivieren von Testergebnissen aus der Ausführung von pytest verwendet werden kann. Weitere Informationen findest du im Artikel über die Aktion upload-artifact.

name: Python package

on: [push]

jobs:
  build:

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

    steps:
      - uses: actions/checkout@v4
      - name: Setup Python # Set Python version
        uses: actions/setup-python@v4
        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@v4
        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() }}

name: Python package

on: [push]

jobs:
  build:

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

    steps:
      - uses: actions/checkout@v4
      - name: Setup Python # Set Python version
        uses: actions/setup-python@v4
        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@v4
        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() }}

In Paket-Registries veröffentlichen

Du kannst deinen Workflow so konfigurieren, dass das Python-Paket in einer Paketregistrierung veröffentlicht wird, wenn deine CI-Tests bestanden werden. In diesem Abschnitt erfährst du, wie du GitHub Actions verwenden kannst, um dein Paket bei einer Veröffentlichung eines Releases in PyPI hochzuladen.

In diesem Beispiel musst du zwei PyPI-API-Token erstellen. Du kannst Geheimnisse verwenden, um die Zugriffstoken oder Anmeldeinformationen zu speichern, die zum Veröffentlichen deines Pakets erforderlich sind. Weitere Informationen findest du unter Verwenden von Geheimnissen in GitHub-Aktionen.

# Dieser Workflow verwendet Aktionen, die nicht von GitHub zertifiziert sind.
# Sie werden von einem Drittanbieter bereitgestellt und unterliegen
# separaten Nutzungsbedingungen, Datenschutzbestimmungen und Support
# Onlinedokumentation.

# GitHub empfiehlt, Aktionen an einen Commit-SHA anzuheften.
# Um eine neuere Version zu erhalten, musst du den SHA aktualisieren.
# Du kannst auch auf ein Tag oder einen Branch verweisen, aber die Aktion kann sich ohne Vorwarnung ändern.

name: Upload Python Package

on:
  release:
    types: [published]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v4
        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@release/v1
        with:
          password: ${{ secrets.PYPI_API_TOKEN }}

# Dieser Workflow verwendet Aktionen, die nicht von GitHub zertifiziert sind.
# Sie werden von einem Drittanbieter bereitgestellt und unterliegen
# separaten Nutzungsbedingungen, Datenschutzbestimmungen und Support
# Onlinedokumentation.

# GitHub empfiehlt, Aktionen an einen Commit-SHA anzuheften.
# Um eine neuere Version zu erhalten, musst du den SHA aktualisieren.
# Du kannst auch auf ein Tag oder einen Branch verweisen, aber die Aktion kann sich ohne Vorwarnung ändern.

name: Upload Python Package

on:
  release:
    types: [published]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v4
        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@release/v1
        with:
          password: ${{ secrets.PYPI_API_TOKEN }}

Weitere Informationen zum Starterworkflow findest du unter python-publish.