Introducción
Esta guía te muestra cómo construir, probar y publicar un paquete de Python.
Los ejecutores hospedados en GitHub tienen un caché de herramientas con software pre-instalado, lo cual incluye a Python y PyPy. ¡No tienes que instalar nada! Para obtener una lista completa de software actualizado y las versiones preinstaladas de Python y PyPy, consulta "Utilizar los ejecutores hospedados en GitHub".
Requisitos previos
Deberías estar familiarizado con YAML y la sintaxis para las GitHub Actions. Para obtener más información, vea «Escritura de flujos de trabajo».
Te recomendamos que tengas una comprensión básica 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 debe funcionar si el 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 Acciones.
-
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. Busca «aplicación Python».
-
En el flujo de trabajo «Aplicación de Python», haz clic en Configurar.
-
Edita el flujo de trabajo según sea necesario. Por ejemplo, cambia la versión de Python.
-
Haga clic en Commit changes (Confirmar cambios).
El archivo de flujo de trabajo python-app.yml se agrega al directorio .github/workflows de tu repositorio.
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.
| Ubuntu | Mac | Windows | |
|---|---|---|---|
| Directorio de caché de herramientas | /opt/hostedtoolcache/* | /Users/runner/hostedtoolcache/* | C:\hostedtoolcache\windows\* |
| Caché 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 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
En el ejemplo siguiente se usa una matriz para el trabajo que sirve para configurar varias versiones de Python. Para obtener más información, vea «Ejecución de variaciones de trabajos en un flujo de trabajo».
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@v4
- 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@v4
- 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)"
Usar una versión de Python específica
Puedes 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 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@v4
- 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@v4
- 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, se produce un error en setup-python 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 obtener más información, vea «Sintaxis del flujo de trabajo para Acciones de GitHub».
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"
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.
| Ejecutor alojado de GitHub | 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 suman a las versiones que GitHub instala en la caché de herramientas. |
| Windows | Excluyendo las versiones de Python que están en la caché de herramientas, Windows no se envía con una versión equivalente de Python del sistema. Para mantener un comportamiento uniforme con otros ejecutores y para permitir que Python se use de forma integrada sin la acción setup-python, GitHub agrega algunas versiones desde la caché de herramientas a PATH. |
| macOS | Los ejecutores de macOS tienen más de una versión de Python del sistema instalada, además de las versiones que son parte de la caché de las herramientas. Las versiones de Python del sistema se encuentran en el directorio /usr/local/Cellar/python/*. |
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.
También puede almacenar en caché sus dependencias para acelerar su flujo de trabajo. Para obtener más información, vea «Almacenar en caché las dependencias para agilizar los flujos de trabajo».
steps:
- uses: actions/checkout@v4
- 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@v4
- 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.
steps:
- uses: actions/checkout@v4
- 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@v4
- 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.
steps:
- uses: actions/checkout@v4
- 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@v4
- 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, consulta "Almacenamiento en caché de dependencias de paquetes" en el archivo README 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 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@v4
- 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@v4
- 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
Uso de Ruff para lint o formato de 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.
steps:
- uses: actions/checkout@v4
- 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@v4
- 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
Se ha establecido continue-on-error: true para el paso de formato. Esto prevendrá que el flujo de trabajo falle si el paso de formato de código no tiene éxito. Una vez que hayas abordado todos los errores de formato 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.9", "3.11", "3.13"]
steps:
- uses: actions/checkout@v4
- 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@v4
- 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 obtener más información, vea «Almacenamiento y uso compartido de datos desde un 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.
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@v4
- 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@v4
- 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 su flujo de trabajo para publicar su paquete Python en PyPI una vez que sus pruebas CI pasen. 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 obtener más información, vea «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.
# 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@v4
- 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@v4
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@v4
- 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@v4
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.