Creación y prueba de Python

Introducción

En esta guía se muestra cómo compilar, probar y publicar un paquete de Python.

GitHubLos ejecutores hospedados tienen una caché de herramientas que incluye software preinstalado, como Python y PyPy. ¡No tienes que instalar nada! Para obtener una lista completa de up-to-date software y las versiones preinstaladas de Python y PyPy, consulte Ejecutores hospedados en GitHub.

Requisitos previos

Debe estar familiarizado con YAML y la sintaxis de GitHub Actions. Para más información, consulta Escritura de flujos de trabajo.

Se recomienda tener conocimientos básicos de Python y pip. Para más información, vea:

Uso de una plantilla de flujo de trabajo de Python

Para comenzar rápidamente, agregue una plantilla de flujo de trabajo al directorio .github/workflows del repositorio.

GitHub proporciona una plantilla de flujo de trabajo para Python que debería funcionar si su repositorio ya contiene al menos un archivo .py. En las secciones siguientes de esta guía se proporcionan ejemplos de cómo puede personalizar esta plantilla de flujo de trabajo.

En GitHub, navegue hasta la página principal del repositorio.
En el nombre del repositorio, haz clic en Actions.
Si ya tiene un flujo de trabajo en su repositorio, haga clic en New workflow (Nuevo flujo de trabajo).
En la página "Elegir un flujo de trabajo" se muestra una selección de plantillas de flujo de trabajo recomendadas. Busque "Python aplicación".
En el flujo de trabajo "aplicación Python", haga clic en Configure.
Edita el flujo de trabajo según sea necesario. Por ejemplo, cambie la versión de Python.
Haga clic en Commit changes (Confirmar cambios).

El python-app.yml archivo de flujo de trabajo se agrega al .github/workflows directorio del repositorio.

Especificación de una versión de Python

Para usar una versión preinstalada de Python o PyPy en un ejecutor alojado en GitHub, usa la acción setup-python. Esta acción busca una versión específica de Python o PyPy desde la memoria caché de herramientas de cada ejecutor y agrega los archivos binarios necesarios a PATH, que se conserva para el resto del trabajo. Si una versión específica de Python no está preinstalada en la memoria caché de herramientas, la acción setup-python descargará y configurará la versión adecuada del repositorio python-versions.

El uso de la acción setup-python es la forma recomendada de usar Python con GitHub Actions, ya que garantiza un comportamiento coherente en diferentes ejecutores y versiones diferentes de Python. Si usa un ejecutor autohospedado, debe instalar Python y agregarlo a PATH. Para más información, vea la acción setup-python.

En la tabla siguiente se describen las ubicaciones de la memoria caché de herramientas en cada GitHubejecutor hospedado.

	Ubuntu	Mac	Windows
Directorio de caché de herramientas	`/opt/hostedtoolcache/*`	`/Users/runner/hostedtoolcache/*`	`C:\hostedtoolcache\windows\*`
Cache de herramientas de Python	`/opt/hostedtoolcache/Python/*`	`/Users/runner/hostedtoolcache/Python/*`	`C:\hostedtoolcache\windows\Python\*`
Caché de herramientas de PyPy	`/opt/hostedtoolcache/PyPy/*`	`/Users/runner/hostedtoolcache/PyPy/*`	`C:\hostedtoolcache\windows\PyPy\*`

Si está utilizando un ejecutor autohospedado, puede configurarlo para utilizar la acción setup-python para administrar sus dependencias. Para obtener más información, consulte uso de setup-python con un ejecutor autohospedado en el archivo README de setup-python.

GitHub admite la sintaxis del versionado semántico. Para obtener más información, consulta Uso del control de versiones semántico y Especificación del control de versiones semántico.

Uso de varias versiones de Python

En el ejemplo siguiente se usa una matriz para el trabajo para configurar varias versiones de Python. Para más información, consulta Ejecución de variaciones de trabajos en un flujo de trabajo.

YAML

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

Uso de una versión de Python específica

Puede configurar una versión específica de Python. Por ejemplo, 3.12. Como alternativa, puedes utilizar una sintaxis de versión semántica para obtener la versión menor más reciente. En este ejemplo se usa la versión secundaria más reciente de Python 3.

YAML

name: Python package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v6
      - 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@v6
      - 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)"

Excluir una versión

Si especifica una versión de Python que no está disponible, setup-python produce un error como: ##[error]Version 3.7 with arch x64 not found. El mensaje de error incluye las versiones disponibles.

También puede usar la palabra clave exclude en el flujo de trabajo si hay una configuración de Python que no desea ejecutar. Para más información, consulta Sintaxis del flujo de trabajo para Acciones de GitHub.

YAML

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"

Uso de la versión predeterminada de Python

Se recomienda usar setup-python para configurar la versión de Python usada en los flujos de trabajo, ya que ayuda a que las dependencias sean explícitas. Si no usa setup-python, la versión predeterminada de Python establecida en PATH se usa en cualquier shell al llamar a python. La versión predeterminada de Python varía entre los ejecutores hospedados en GitHub, lo que puede provocar cambios inesperados o usar una versión anterior de la esperada.

GitHubEjecutor hospedado	Descripción
Ubuntu	Los ejecutores de Ubuntu tienen varias versiones del sistema Python instaladas en `/usr/bin/python` y `/usr/bin/python3`. Las versiones de Python que vienen empaquetadas con Ubuntu se agregan a las versiones que GitHub instala en la memoria caché de herramientas.
Windows	Excluyendo las versiones de Python que se encuentran en el caché de herramientas, Windows no se suministra con una versión equivalente de Python del sistema operativo. Para mantener un comportamiento coherente con otros ejecutores y permitir que se pueda usar Python desde el primer momento sin la acción `setup-python`, GitHub añade algunas versiones desde la caché de herramientas a `PATH`.
macOS	Los ejecutores de macOS tienen más de una versión del sistema Python instaladas, además de las versiones que forman parte de la caché de herramientas. Las versiones de Python del sistema se encuentran en el directorio `/usr/local/Cellar/python/*`.

Instalación de dependencias

GitHubLos ejecutores hospedados tienen instalado el administrador de paquetes pip. Puedes usar pip para instalar dependencias desde el registro del paquete de PyPI antes de construir y probar tu código. Por ejemplo, el YAML siguiente instala o actualiza el instalador de paquetes pip y los paquetes setuptools y wheel.

También puede almacenar en caché sus dependencias para acelerar su flujo de trabajo. Para más información, consulta Referencia de almacenamiento en caché de dependencias.

YAML

steps:
- uses: actions/checkout@v6
- 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@v6
- 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

Archivo de requisitos

Después de actualizar pip, el siguiente paso típico consiste en instalar dependencias desde requirements.txt. Para obtener más información, consulte pip.

YAML

steps:
- uses: actions/checkout@v6
- 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@v6
- 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

Dependencias de almacenamiento en caché

Puedes almacenar en caché y restaurar las dependencias mediante la acción setup-python.

El siguiente ejemplo guarda las dependencias en caché para pip.

YAML

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

De manera predeterminada, la acción setup-python busca el archivo de dependencias (requirements.txt para pip, Pipfile.lock para pipenvo o poetry.lock para poetry) en todo el repositorio. Para obtener más información, consulte Almacenamiento en caché de dependencias de paquetes en el archivo LÉAME de setup-python.

Si tiene una necesidad específica o necesita controles más precisos para el almacenamiento en caché, puede usar la acción cache. Pip almacena en caché las dependencias en diferentes ubicaciones, en función del sistema operativo del ejecutor. La ruta que necesitarás para almacenar en caché puede diferir del ejemplo de Ubuntu que se muestra anteriormente, según el sistema operativo que uses. Para obtener más información, consulte ejemplos de almacenamiento en caché de Python en el repositorio de acciones de cache.

Probar el código

Puedes usar los mismos comandos que usas de forma local para construir y probar tu código.

Pruebas con pytest y pytest-cov

En este ejemplo se instalan o actualizan pytest y pytest-cov. A continuación, se ejecutan las pruebas que se presentan en formato JUnit, mientras que los resultados de la cobertura de código se generan en Cobertura. Para obtener más información, consulte JUnit y Cobertura.

YAML

steps:
- uses: actions/checkout@v6
- 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@v6
- 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

Sugerencia

En este ejemplo ya se genera un informe de cobertura XML de Cobertura (--cov-report=xml). Para mostrar los resultados de cobertura directamente en las pull requests, cargue el informe mediante la acción actions/upload-code-coverage. Consulte Setting up code coverage for your repository.

Uso de Ruff para hacer lint y/o formatear código

En el ejemplo siguiente se instala o actualiza ruff y se usa para ejecutar el linting en todos los archivos. Para más información, consulta Ruff.

YAML

steps:
- uses: actions/checkout@v6
- 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@v6
- 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

El paso de formateado tiene establecido continue-on-error: true. Esto evitará que el flujo de trabajo falle si el paso de formateo no tiene éxito. Una vez que hayas abordado todos los errores de formato, puedes eliminar esta opción para que el flujo de trabajo detecte problemas nuevos.

Ejecutar pruebas con tox

Con GitHub Actions, puedes ejecutar pruebas con tox y distribuir el trabajo entre varias tareas. Tendrá que invocar tox mediante la opción -e py para elegir la versión de Python en su PATH, en lugar de indicar una versión específica. Para obtener más información, consulte tox.

YAML

name: Python package

on: [push]

jobs:
  build:

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

    steps:
      - uses: actions/checkout@v6
      - 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@v6
      - 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

Empaquetar datos de flujo de trabajo como artefactos

Puedes cargar artefactos para ver después de que se complete un flujo de trabajo. Por ejemplo, es posible que debas guardar los archivos de registro, los vaciados de memoria, los resultados de las pruebas o las capturas de pantalla. Para más información, consulta Almacenamiento y uso compartido de datos con artefactos de flujo de trabajo.

En el ejemplo siguiente se muestra cómo puede usar la acción upload-artifact para archivar los resultados de la prueba después de ejecutar pytest. Para más información, vea la acción upload-artifact.

YAML

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@v6
      - 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@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.9", "3.10", "3.11", "3.12", "3.13"]

    steps:
      - uses: actions/checkout@v6
      - 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@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() }}

Publicación en PyPI

Puede configurar el flujo de trabajo para publicar el paquete de Python en PyPI una vez superadas las pruebas de CI. En esta sección se muestra cómo puede usar GitHub Actions para cargar el paquete en PyPI cada vez que publique una versión. Para más información, consulta Administrar lanzamientos en un repositorio.

En el flujo de trabajo de ejemplo siguiente se usa publicación de confianza para autenticarse con PyPI, lo que elimina la necesidad de un token de API configurado manualmente.

YAML

# Este flujo de trabajo usa acciones que no GitHub no certifica.
# Estas las proporcionan entidades terceras y las gobiernan
# condiciones de servicio, políticas de privacidad y documentación de soporte
# en línea.

# GitHub recomienda anclar acciones a un SHA de confirmación.
# Para obtener una versión más reciente, debes actualizar el SHA.
# También puedes hacer referencia a una etiqueta o rama, pero la acción puede cambiar sin ninguna advertencia.

name: Upload Python Package

on:
  release:
    types: [published]

permissions:
  contents: read

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

    steps:
      - uses: actions/checkout@v6

      - 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@v4
        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@v5
        with:
          name: release-dists
          path: dist/

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

# Este flujo de trabajo usa acciones que no GitHub no certifica.
# Estas las proporcionan entidades terceras y las gobiernan
# condiciones de servicio, políticas de privacidad y documentación de soporte
# en línea.

# GitHub recomienda anclar acciones a un SHA de confirmación.
# Para obtener una versión más reciente, debes actualizar el SHA.
# También puedes hacer referencia a una etiqueta o rama, pero la acción puede cambiar sin ninguna advertencia.

name: Upload Python Package

on:
  release:
    types: [published]

permissions:
  contents: read

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

    steps:
      - uses: actions/checkout@v6

      - 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@v4
        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@v5
        with:
          name: release-dists
          path: dist/

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

Para obtener más información sobre este flujo de trabajo, incluida la configuración de PyPI necesaria, consulte Configurar OpenID Connect en PyPI.

En este artículo