Criar e testar o Python

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:

• Primeiros passos com o Python
• PyPy
• Gerenciador de pacotes do Pip

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.

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.

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.

Ao usar executores hospedados em GitHub, você também poderá armazenar em cache dependências para acelerar seu fluxo de trabalho. Para obter mais informações, consulte "Memorizar dependências para acelerar fluxos de trabalho".

etapas:
- usa: actions/checkout@v2
- nome: Configurar Python
  usa: actions/setup-python@v2
  com:
    python-version: '3.x'
- Nome: Instalar dependências
  executar: 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.

etapas:
- usa: actions/checkout@v2
- nome: Configurar Python
  usa: actions/setup-python@v2
  com:
    python-version: '3.x'
- nome: Instalar dependências
  executar: |
    python -m pip install --upgrade pip
    pip install -r requirements.txt

Memorizar dependências

Ao usar executores hospedados em GitHub, você pode armazenar em cache e restaurar as dependências usando a ação setup-python.

O exemplo a seguir armazena dependências para pip.

steps:
- uses: actions/checkout@v2
- uses: actions/setup-python@v2
  with:
    python-version: '3.9'
    cache: 'pip'
- run: pip install -r requirements.txt
- run: pip test

Por padrão, a ação setup-python busca o arquivo de dependência (requirements.txt para pip ou Pipfile.lock para pipenv) em todo o repositório. Para obter mais informações, consulte "Armazenando em cache as dependências de pacotes" nas ações README do setup-python.

Se você tiver um requisito personalizado ou precisar de melhores controles para cache, você poderá usar a ação cache. O Pip armazena dependências em diferentes locais, dependendo do sistema operacional do executor. O caminho que você precisa efetuar o armazenamento em cache pode ser diferente do exemplo do Ubuntu acima, dependendo do sistema operacional que você usa. Para obter mais informações, consulte Exemplos de armazenamento em cache do Python no repositório de ação cache.

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.

etapas:
- usa: actions/checkout@v2
- nome: Set up Python
  usa: actions/setup-python@v2
  com:
    python-version: '3.x'
- nome: Instalar dependências
  executar: |
    python -m pip install --upgrade pip
    pip install -r requirements.txt
- Nome: Testar com pytest
  executar: |
    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.

etapas:
- usa: actions/checkout@v2
- nome: Configurar Python
  usa: actions/setup-python@v2
  com:
    python-version: '3.x'
- nome: Instalar dependências
  executar: |
    python -m pip install --upgrade pip
    pip install -r requirements.txt
- nome: 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.