Crear y probar en Python

Introducción

Esta guía te muestra cómo construir, probar y publicar un paquete de Python.

Los ejecutores alojados en GitHub tienen una memoria caché de herramientas con software preinstalado, que incluye Python y PyPy. ¡No tienes que instalar nada! A fin de obtener una lista completa de software actualizada y las versiones preinstaladas de Python y PyPy, consulte "Especificaciones de ejecutores alojados en GitHub".

Requisitos previos

Deberías estar familiarizado con YAML y la sintaxis para las GitHub Actions. Para más información, vea "Más información sobre GitHub Actions".

Te recomendamos que tengas una comprensión básica de Python, PyPy y pip. Para más información, consulte:

• Introducción a Python
• PyPy
• Administrador de paquetes pip

Utilizar ejecutores auto-hospedados en GitHub Enterprise Server

Cuando use acciones de configuración, (como actions/setup-LANGUAGE) en GitHub Enterprise Server con ejecutores autohospedados, es posible que necesite configurar la caché de herramientas en los ejecutores que no tienen acceso a Internet. Para más información, vea "Configuración de la caché de herramientas en ejecutores autohospedados sin acceso a Internet".

Utilizar el flujo de trabajo inicial de Python

GitHub proporciona un flujo de trabajo inicial de Python que debería funcionar para la mayoría de los proyectos de Python. Esta guía incluye ejemplos que puedes utilizar para personalizar los flujos de trabajo iniciales. Para obtener más información, consulte el flujo de trabajo de inicio de Python.

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

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

Especificar una versión de Python

Para usar una versión preinstalada de Python o PyPy en un ejecutor hospedado en GitHub, use la acción setup-python. Esta acción busca una versión específica de Python o PyPy en la 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 que tenga lugar un comportamiento uniforme en los distintos ejecutores y versiones de Python. Si va a usar un ejecutor autohospedado, debe instalar Python y agregarlo a PATH. Para más información, vea la acción setup-python.

La tabla que aparece a continuación describe las ubicaciones de la caché de herramientas en cada ejecutor alojado GitHub.

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 de control de versiones semántico. Para obtener más información, consulte "Uso del control de versiones semántico" y "Especificación del control de versiones semántico".

Usar múltiples versiones de Python

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

Usar una versión de Python específica

Puedes configurar una versión específica de Python. Por ejemplo, 3.9. Como alternativa, puedes utilizar una sintaxis de versión semántica para obtener el último lanzamiento menor. En este ejemplo se usa el último lanzamiento menor de Python 3.

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

Excluir una versión

Si especifica una versión de Python que no esté disponible, se produce un error en setup-python como: ##[error]Version 3.4 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 obtener más información, consulte "Sintaxis de flujo de trabajo para 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.7", "3.8", "3.9", "3.10", pypy2, pypy3]
        exclude:
          - os: macos-latest
            python-version: "3.7"
          - os: windows-latest
            python-version: "3.7"

Usar la versión de Python predeterminada

Recomendamos usar setup-python para configurar la versión de Python que se usa en sus flujos de trabajo porque permite 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 cuando llama a python. La versión predeterminada de Python varía entre los ejecutores alojados GitHub, que pueden causar cambios inesperados o usar una versión anterior a la esperada.

Instalación de dependencias

Los ejecutores alojados GitHub tienen instalado el administrador del paquete 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.

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

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.

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

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 y se emiten pruebas en formato JUnit, mientras que los resultados de la cobertura de código se emiten en Cobertura. Para obtener más información, consulte JUnit y Cobertura.

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

Usar Flake8 para el código lint

En el ejemplo siguiente se instala o actualiza flake8 y se usa para ejecutar el linting en todos los archivos. Para obtener más información, consulte Flake8.

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

El paso de linting tiene establecido continue-on-error: true. Esto prevendrá que el flujo de trabajo falle si el paso de limpieza de código no tiene éxito. Una vez que hayas abordado todos los errores de limpieza de código, puedes eliminar esta opción para que el flujo de trabajo atrape propuestas nuevas.

Ejecutar pruebas con tox

Con GitHub Actions, puedes ejecutar pruebas con tox y repartir el trabajo a través de múltiples trabajos. Deberá invocar tox mediante la opción -e py para elegir la versión de Python en PATH lugar de especificar una versión concreta. Para obtener más información, consulte tox.

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

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, vea "Conservación de datos de flujo de trabajo mediante artefactos".

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.

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

Publicar en registros de paquetes

Puedes configurar tu flujo de trabajo para publicar tu paquete de Python a un registro de paquetes una vez que pasen tus pruebas de IC. 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.

En este ejemplo, deberá crear dos tokens de API de PyPI. Puedes utilizar secretos para almacenar los tokens de acceso o las credenciales que se necesitan publicar en tu paquete. Para más información, vea "Creación y uso de secretos cifrados".

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

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

Para obtener más información sobre el flujo de trabajo de inicio, consulte python-publish.