Erstellen und Testen von Python

Einführung

In diesem Handbuch erfahren Sie, wie Sie ein Python-Paket erstellen, testen und veröffentlichen.

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 up-to-date-Software und der vorinstallierten Versionen von Python und PyPy finden Sie unter Von GitHub gehostete Runner.

Voraussetzungen

Du solltest mit YAML und der Syntax für GitHub Actions vertraut sein. Weitere Informationen finden Sie unter Schreiben von Workflows.

Es wird empfohlen, ein grundlegendes Verständnis von Python und Pip zu haben. Weitere Informationen finden Sie unter:

•         [Einführung in Python](https://www.python.org/about/gettingstarted/)
  

•         [Pip-Paket-Manager](https://pypi.org/project/pip/)
  

Verwendung von selbstgehosteten Runnern auf GitHub Enterprise Server

Wenn du Setup-Aktionen (wie z.B.actions/setup-LANGUAGE) auf GitHub Enterprise Server mit selbstgehosteten Runnern verwendest, musst du möglicherweise den Tools-Cache auf Runnern einrichten, die keinen Internetzugang haben. Weitere Informationen finden Sie unter Einrichten des Toolcaches auf selbstgehosteten Runnern ohne Internetzugriff.

Verwenden einer Python Workflowvorlage

Fügen Sie für einen schnellen Einstieg dem Verzeichnis .github/workflows Ihres Repositorys eine Workflowvorlage hinzu.

GitHub stellt eine Workflowvorlage für Python bereit, die funktionieren soll, wenn Ihr Repository bereits mindestens eine .py Datei enthält. In den nachfolgenden Abschnitten dieser Anleitung finden Sie Beispiele dafür, wie diese Workflowvorlage angepasst werden kann.

1. Navigieren Sie auf GitHub zur Hauptseite des Repositorys.

2. Klicke unter dem Repositorynamen auf Actions.

   

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

4. Auf der Seite „Workflow auswählen“ wird eine Auswahl empfohlener Workflowvorlagen angezeigt. Suchen Sie nach "Python Anwendung".

5. Klicken Sie im Workflow "Python Anwendung" auf Configure.

   Wenn Sie die Workflowvorlage "Python Anwendung" nicht finden, kopieren Sie den folgenden Workflowcode in eine neue Datei namens python-app.yml im Verzeichnis .github/workflows Ihres Repositorys.

   YAML

   name: Python application
   
   on:
     push:
       branches: [ "main" ]
     pull_request:
       branches: [ "main" ]
   
   permissions:
     contents: read
   
   jobs:
     build:
       runs-on: ubuntu-latest
   
       steps:
       - uses: actions/checkout@v5
       - name: Set up Python 3.13
         uses: actions/setup-python@v5
         with:
           python-version: "3.13"
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
           pip install ruff pytest
           if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
       - name: Lint and format Python code with ruff
         run: |
          # Lint with the default set of ruff rules with GitHub Annotations
          ruff check --format=github --target-version=py39
          # Verify the code is properly formatted
          ruff format --diff --target-version=py39
       - name: Test with pytest
         run: |
           pytest
   

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

7. Klicke auf Änderungen übernehmen.

Angeben einer Python-Version

Wenn Sie eine vorinstallierte Version von Python oder PyPy auf einem GitHubgehosteten Runner verwenden möchten, verwenden Sie die Aktion setup-python. Diese Aktion findet eine bestimmte Version von Python oder PyPy aus dem Toolscache auf jedem Runner und fügt die erforderlichen Binärdateien zu PATH hinzu, das für den Rest des Jobs bestehen bleibt. Wenn eine bestimmte Version von Python nicht im Toolscache vorinstalliert ist, lädt die aktion setup-python die entsprechende Version aus dem Repository python-versions herunter und richtet sie ein.

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 Sie einen selbst gehosteten Runner verwenden, müssen Sie Python installieren und zu PATH hinzufügen. Weitere Informationen finden Sie unter der setup-python Aktion.

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

          **Toolcacheverzeichnis** |`/opt/hostedtoolcache/*`|`/Users/runner/hostedtoolcache/*`|`C:\hostedtoolcache\windows\*`|

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 finden Sie unter Verwenden von „setup-python“ mit einem selbst gehosteten Runner in der setup-python README-Datei.

GitHub unterstützt die Syntax des Semantischen Versionierens. Weitere Informationen findest du unter Verwenden der semantischen Versionierung und unter Spezifikation zur semantischen Versionierung.

Verwenden mehrerer Python-Versionen

Im folgenden Beispiel wird eine Matrix für den Job verwendet, um mehrere Python-Versionen einzurichten. Weitere Informationen finden Sie unter Varianten von Aufgaben in einem Workflow ausführen.

name: Python package

on: [push]

jobs:
  build:

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

    steps:
      - uses: actions/checkout@v5
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        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.10", "3.9", "3.10", "3.11", "3.12", "3.13"]

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

Verwenden einer bestimmten Python-Version

Sie können eine bestimmte Version von Python konfigurieren. Beispiel: 3.12. Alternativ kannst du auch Syntax für semantische Versionierung verwenden, um die neuste Nebenversion abzurufen. In diesem Beispiel wird die neueste Nebenversion von Python 3 verwendet.

name: Python package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v5
      - name: Set up Python
        # This is the version of the action for setting up Python, not the Python version.
        uses: actions/setup-python@v5
        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@v5
      - name: Set up Python
        # This is the version of the action for setting up Python, not the Python version.
        uses: actions/setup-python@v5
        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 Sie eine nicht verfügbare Version von Python angeben, schlägt setup-python mit einem Fehler wie: ##[error]Version 3.7 with arch x64 not found fehl. Die Fehlermeldung enthält die verfügbaren Versionen.

Sie können auch das Schlüsselwort exclude in Ihrem Workflow verwenden, wenn eine Konfiguration von Python vorhanden ist, die Sie nicht ausführen möchten. Weitere Informationen finden Sie 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.11", "3.13", "pypy3.10"]
        exclude:
          - os: macos-latest
            python-version: "3.11"
          - os: windows-latest
            python-version: "3.11"

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.11", "3.13", "pypy3.10"]
        exclude:
          - os: macos-latest
            python-version: "3.11"
          - os: windows-latest
            python-version: "3.11"

Verwenden der Standardversion Python

Es wird empfohlen, setup-python zu verwenden, um die Version von Python zu konfigurieren, die in Ihren Workflows verwendet wird, da die Abhängigkeiten explizit sind. Wenn Sie setup-python nicht verwenden, wird die in PATH festgelegte Standardversion von Python in jeder Shell verwendet, wenn Sie python aufrufen. 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.

Sie können auch Abhängigkeiten zwischenspeichern, um Ihren Workflow zu beschleunigen. Weitere Informationen finden Sie unter Referenz zum Zwischenspeichern von Abhängigkeiten.

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

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

Anforderungsdatei

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

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

steps:
- uses: actions/checkout@v5
- name: Set up Python
  uses: actions/setup-python@v5
  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@v5
- uses: actions/setup-python@v5
  with:
    python-version: '3.12'
    cache: 'pip'
- run: pip install -r requirements.txt
- run: pip test

steps:
- uses: actions/checkout@v5
- uses: actions/setup-python@v5
  with:
    python-version: '3.12'
    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 finden Sie unter Zwischenspeichern von Paketabhängigkeiten in der setup-python README.

Wenn du eine benutzerdefinierte Anforderung hast oder genauere Steuerungsmöglichkeiten zum Zwischenspeichern benötigst, kannst du die cache Aktion verwenden. 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 finden Sie unter Python Zwischenspeicherungsbeispiele im cache-Aktionsrepository.

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 finden Sie unter JUnit und Cobertura.

steps:
- uses: actions/checkout@v5
- name: Set up Python
  uses: actions/setup-python@v5
  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@v5
- name: Set up Python
  uses: actions/setup-python@v5
  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 und/oder Formatieren von Code

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

steps:
- uses: actions/checkout@v5
- name: Set up Python
  uses: actions/setup-python@v5
  with:
    python-version: '3.x'
- name: Install the code linting and formatting tool Ruff
  run: pipx install ruff
- name: Lint code with Ruff
  run: ruff check --output-format=github --target-version=py39
- name: Check code formatting with Ruff
  run: ruff format --diff --target-version=py39
  continue-on-error: true

steps:
- uses: actions/checkout@v5
- name: Set up Python
  uses: actions/setup-python@v5
  with:
    python-version: '3.x'
- name: Install the code linting and formatting tool Ruff
  run: pipx install ruff
- name: Lint code with Ruff
  run: ruff check --output-format=github --target-version=py39
- name: Check code formatting with Ruff
  run: ruff format --diff --target-version=py39
  continue-on-error: true

Der Formatierungsschritt ist mit continue-on-error: true festgelegt. Dadurch wird verhindert, dass der Workflow fehlschlägt, wenn der Formatierungsschritt nicht erfolgreich ist. Nachdem Sie alle Formatierungsfehler behoben haben, können Sie diese Option entfernen, sodass der Workflow neue Probleme erkennt.

Tests mit Tox ausführen

Mit GitHub Actions kannst du Tests mit tox ausführen und die Arbeit auf mehrere Jobs verteilen. Sie müssen tox mithilfe der Option -e py aufrufen, um die Version von Python in Ihrem PATH auszuwählen, anstatt eine bestimmte Version anzugeben. Weitere Informationen finden Sie unter tox.

name: Python package

on: [push]

jobs:
  build:

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

    steps:
      - uses: actions/checkout@v5
      - name: Setup Python
        uses: actions/setup-python@v5
        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.11", "3.13"]

    steps:
      - uses: actions/checkout@v5
      - name: Setup Python
        uses: actions/setup-python@v5
        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 finden Sie unter Speichern und Freigeben von Daten mit Workflowartefakten.

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 finden Sie unter der upload-artifact Aktion.

name: Python package

on: [push]

jobs:
  build:

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

    steps:
      - uses: actions/checkout@v5
      - name: Setup Python # Set Python version
        uses: actions/setup-python@v5
        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@v3
        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.9", "3.10", "3.11", "3.12", "3.13"]

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

Veröffentlichen in PyPI

Sie können Ihren Workflow so konfigurieren, dass Ihr Python-Paket nach dem Bestehen ihrer CI-Tests in PyPI veröffentlicht wird. In diesem Abschnitt erfährst du, wie du GitHub Actions verwenden kannst, um dein Paket bei einer Veröffentlichung eines Releases in PyPI hochzuladen. Weitere Informationen finden Sie unter Veröffentlichungen in einem Repository verwalten.

Im folgenden Beispielworkflow wird Trusted Publishing zur Authentifizierung mit PyPI verwendet, wodurch kein manuell konfiguriertes API-Token mehr notwendig ist.

# 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]

permissions:
  contents: read

jobs:
  release-build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v5

      - uses: actions/setup-python@v5
        with:
          python-version: "3.x"

      - name: Build release distributions
        run: |
          # NOTE: put your own distribution build steps here.
          python -m pip install build
          python -m build

      - name: Upload distributions
        uses: actions/upload-artifact@v3
        with:
          name: release-dists
          path: dist/

  pypi-publish:
    runs-on: ubuntu-latest

    needs:
      - release-build

    permissions:
      # IMPORTANT: this permission is mandatory for trusted publishing
      id-token: write

    # Dedicated environments with protections for publishing are strongly recommended.
    environment:
      name: pypi
      # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
      # url: https://pypi.org/p/YOURPROJECT

    steps:
      - name: Retrieve release distributions
        uses: actions/download-artifact@v3
        with:
          name: release-dists
          path: dist/

      - name: Publish release distributions to PyPI
        uses: pypa/gh-action-pypi-publish@6f7e8d9c0b1a2c3d4e5f6a7b8c9d0e1f2a3b4c5d

# 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]

permissions:
  contents: read

jobs:
  release-build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v5

      - uses: actions/setup-python@v5
        with:
          python-version: "3.x"

      - name: Build release distributions
        run: |
          # NOTE: put your own distribution build steps here.
          python -m pip install build
          python -m build

      - name: Upload distributions
        uses: actions/upload-artifact@v3
        with:
          name: release-dists
          path: dist/

  pypi-publish:
    runs-on: ubuntu-latest

    needs:
      - release-build

    permissions:
      # IMPORTANT: this permission is mandatory for trusted publishing
      id-token: write

    # Dedicated environments with protections for publishing are strongly recommended.
    environment:
      name: pypi
      # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
      # url: https://pypi.org/p/YOURPROJECT

    steps:
      - name: Retrieve release distributions
        uses: actions/download-artifact@v3
        with:
          name: release-dists
          path: dist/

      - name: Publish release distributions to PyPI
        uses: pypa/gh-action-pypi-publish@6f7e8d9c0b1a2c3d4e5f6a7b8c9d0e1f2a3b4c5d