Observação: Executores hospedados em GitHub não são atualmente compatíveis com GitHub Enterprise Server. Você pode ver mais informações sobre suporte futuro planejado no Itinerário público do GitHub.
Introdução
Este guia mostra como criar, testar e publicar um pacote no Python.
GitHub têm um cache de ferramentas com software pré-instalado, que inclui Python e PyPy. Você não precisa instalar nada! Para obter uma lista completa do software atualizado e das versões pré-instaladas do Python e PyPy, consulte "Especificações para executores hospedados em GitHub".
Pré-requisitos
Você deve estar familiarizado com o YAML e a sintaxe do GitHub Actions. Para obter mais informações, consulte "Aprenda GitHub Actions".
Recomendamos que você tenha um entendimento básico do Python, PyPy e pip. Para obter mais informações, consulte:
Usar executores auto-hospedados no GitHub Enterprise Server
Ao usar ações de configuração (como actions/setup-LANGUAGE
) em GitHub Enterprise Server com executores auto-hospedados, você pode precisar configurar o armazenamento de ferramentas em executores que não possuem acesso � internet. Para obter mais informações, consulte "Configurar o cache da ferramenta em executores auto-hospedados sem acesso � internet".
Usando o fluxo de trabalho inicial do Python
GitHub fornece um fluxo de trabalho inicial do Python que deve funcionar na maioria dos projetos do Python. Este guia inclui exemplos que você pode usar para personalizar o fluxo de trabalho inicial. Para obter mais informações, consulte o fluxo de trabalho inicial do Python.
Para iniciar rapidamente, adicione o fluxo de trabalho inicial para o diretório .github/workflows
do seu repositório.
name: Python package
on: [push]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ["3.6", "3.7", "3.8", "3.9"]
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 uma versão do Python
Para usar uma versão pré-instalada do Python ou do PyPy em um executor hospedado em GitHub, use a ação setup-python
. Esta ação encontra uma versão específica do Python ou do PyPy na cache das ferramenatas em cada executor e adiciona os binários necessários ao PATH
, que persiste para o restante do trabalho. Se uma versão específica do Python não for pré-instalada na cache de ferramentas, a setup-python
ação fará o download e irá configurar a versão apropriada do repositório python-versions
.
Using the setup-action
is the recommended way of using Python with GitHub Actions because it ensures consistent behavior across different runners and different versions of Python. Se você estiver usando um executor auto-hospedado, você deverá instalar Python e adicioná-lo ao PATH
. Para obter mais informações, consulte a ação setup-python
.
A tabela abaixo descreve os locais para o armazenamento de ferramentas em cada executor hospedado em GitHub.
Ubuntu | Mac | Windows | |
---|---|---|---|
Diretório da cache da ferramenta | /opt/hostedtoolcache/* | /Users/runner/hostedtoolcache/* | C:\hostedtoolcache\windows\* |
Cache da ferramenta do Python | /opt/hostedtoolcache/Python/* | /Users/runner/hostedtoolcache/Python/* | C:\hostedtoolcache\windows\Python\* |
Cache da ferramenta do PyPy | /opt/hostedtoolcache/PyPy/* | /Users/runner/hostedtoolcache/PyPy/* | C:\hostedtoolcache\windows\PyPy\* |
Se você estiver usando um executor auto-hospedado, você poderá configurá-lo para usar a ação setup-python
para gerenciar suas dependências. Para obter mais informações, consulte usando o setup-python com um executor auto-hospedado na README do setup-python
.
O GitHub é compatível com a sintaxe semântica de versionamento. Para obter mais informações, consulte "Usar o versionamento semântico" e "Especificação do versionamento semântico".
Usar várias versões do Python
nome: Pacote Python
em: [push]
trabalhos:
criar:
runs-on: ubuntu-latest
estratégia:
# Você pode usar as versões do PyPy em python-version.
# For example, pypy2 and pypy3
matrix:
python-version: ["2.7", "3.6", "3.7", "3.8", "3.9"]
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 uma versão específica do Python
Você pode configurar uma versão específica do python. Por exemplo, 3,8. Como alternativa, você pode usar a sintaxe da versão semântica para obter a última versão secundária. Este exemplo usa a última versão secundária do 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 uma versão
Se especificar uma versão do Python que estiver indisponível, setup-python
ocorrerá uma falha com um erro como: ##[error]Version 3.4 with arch x64 not found
. A mensagem de erro inclui as versões disponíveis.
Também é possível usar a palavra-chave excluir
no seu fluxo de trabalho se houver uma configuração do Python que você não deseja executar. Para obter mais informações, consulte a sintaxe " 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.6", "3.7", "3.8", "3.9", pypy2, pypy3]
exclude:
- os: macos-latest
python-version: "3.6"
- os: windows-latest
python-version: "3.6"
Usar a versão padrão do Python
Recomendamos usar setup-python
para configurar a versão do Python usada nos seus fluxos de trabalho, porque isso ajuda a deixar as suas dependências explícitas. Se você não usar setup-python
, a versão padrão do Python definida em PATH
será usada em qualquer shell quando você chamar python
. A versão-padrão do Python varia entre executores hospedados no GitHub, o que pode causar mudanças inesperadas ou usar uma versão mais antiga do que o esperado.
Executor hospedado emGitHub | Descrição |
---|---|
Ubuntu | Os executores do Ubuntu têm várias versões do sistema do Python instaladas em /usr/bin/python e /usr/bin/python3 . As versões do Python que vêm empacotadas com o Ubuntu são adicionais � s versões que o GitHub instala na cache das ferramentas. |
Windows | Excluindo as versões do Python que estão na cache de ferramentas, o Windows não é compatível com uma versão equivalente do sistema do Python. Para manter um comportamento consistente com outros executores e permitir que o Python seja usado de forma inovadora sem a ação setup-python , GitHub adiciona algumas versões da cache das ferramentas ao PATH . |
macOS | Os executores do macOS têm mais de uma versão do sistema do Python instalada, além das versões que fazem parte da cache de ferramentas. As versões do sistema do Python estão localizadas no diretório /usr/local/Cellar/python/* . |
Instalar dependências
Os executores hospedados em GitHub têm instalado o gerenciador do pacote pip. Você pode usar o pip para instalar dependências do registro de pacotes do PyPI antes de criar e testar o seu código. Por exemplo, o YAML abaixo instala ou atualiza o instalador de pacotes pip
e as os pacotes setuptools
e 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
Arquivo de requisitos
Depois de atualizar o pip
, um o próximo passo típico é instalar as dependências de requirements.txt. Para obter mais informações, 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
Testar seu código
Você pode usar os mesmos comandos usados localmente para criar e testar seu código.
Testar com pytest e pytest-cov
Este exemplo instala ou atualiza pytest
e pytest-cov
. Em seguida, os testes são executados e retornados no formato JUnit enquanto os resultados da cobertura do código são emitidos em Cobertura. Para obter mais informações, consulte JUnit e 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
UsarFlake8 para código lint
O exemplo a seguir instala ou atualiza o flake8
e o usa para limpar todos os arquivos. Para obter mais informações, 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
O passo de limpeza de código foi configurado com continue-on-error: true
. Isto impedirá que o fluxo de trabalho falhe se a etapa de limpeza de código não for bem-sucedida. Após corrigir todos os erros de limpeza de código, você poderá remover essa opção para que o fluxo de trabalho capture novos problemas.
Executar testes com tox
Com GitHub Actions, você pode executar testes com tox e distribuir o trabalho para vários trabalhos. Você precisará invocar tox usando a opção -e py
para escolher a versão do Python no seu PATH
, em vez de especificar uma versão específica. Para obter mais informações, consulte tox.
name: Python package
on: [push]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
python: ["3.7", "3.8", "3.9"]
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
Empacotar dados do fluxo de trabalho como artefatos
Você pode fazer o upload de artefatos para visualização após a conclusão de um fluxo de trabalho. Por exemplo, é possível que você precise salvar os arquivos de registro, os despejos de núcleo, os resultados de teste ou capturas de tela. Para obter mais informações, consulte "Dados recorrentes do fluxo de trabalho que usam artefatos".
O exemplo a seguir demonstra como você pode usar a ação upload-artefact
para arquivar os resultados de teste da execução do pytest
. Para obter mais informações, consulte a ação <upload-artifact
.
name: Python package
on: [push]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ["3.6", "3.7", "3.8", "3.9"]
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 nos registros do pacote
Você pode configurar seu fluxo de trabalho para publicar seu pacote do Python em um pacote de registro assim que seu CI teste passar. Esta seção demonstra como você pode usar GitHub Actions para fazer o upload do seu pacote para o PyPI toda vez que publicar uma versão.
Para este exemplo, você deverá criar dois tokens da API do PyPI. Você pode usar segredos para armazenar os tokens de acesso ou credenciais necessárias para publicar o seu pacote. Para obter mais informações, consulte "Criando e usando segredos encriptados".
# This workflow uses actions that are not certified by GitHub.
# São fornecidas por terceiros e regidas por
# termos de serviço, política de privacidade e suporte separados
# documentação.
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 obter mais informações sobre o fluxo de trabalho inicial, consulte python-publish
.