10 etapas para um projeto Python bem-sucedido

O material, cuja tradução publicamos hoje, é dedicado a ferramentas que permitem equipar os projetos Python com ferramentas de formatação de código, teste, integração contínua e análise de dependência. Isso ajuda a acelerar o processo de desenvolvimento, ajuda a melhorar a qualidade, uniformidade e segurança do código. Supõe-se que o leitor deste material já tenha alguma experiência no desenvolvimento de Python e um projeto de Python com o qual ele, durante a leitura, experimentará. Se você não possui um projeto, aqui pode aprender como preparar um ambiente de desenvolvimento e criar um pacote Python. Os exemplos que serão dados aqui são preparados usando o macOS e o Python 3.7.

Etapa 1. Instalando o Black

O código do projeto deve seguir as convenções de estilo de código. Black é um pacote Python que formata automaticamente o código, trazendo sua aparência para o padrão PEP 8 . O preto é um projeto relativamente novo, mas já ganhou mais de um milhão de downloads. Seu uso rapidamente se tornou um sinal de bom gosto no desenvolvimento do Python. Aqui está o manual preto.

Como editor de código, uso o Atom, então adicionei o pacote Python-Black ao Atom. Você pode descobrir como instalá-lo aqui . Depois de instalar este pacote, o Atom reformatará o código após salvar o arquivo.

Enquanto falamos de Black - vamos equipar esta ferramenta com o ambiente de desenvolvimento daqueles que trabalham conosco no projeto. Como resultado, todos que trabalham no projeto usarão as mesmas regras de formatação de código, caso contrário, suas solicitações de recebimento não serão aceitas.

Inclua o black==18.9b0 na primeira linha livre encontrada do arquivo requirements_dev.txt e execute o comando install -r requirements_dev.txt .

Preto, por padrão, define o comprimento da linha de código para 88 caracteres. Alguns guias de estilo, como o Sphinx , exigem um comprimento de string de 79 caracteres. Nas configurações do pacote Black-Atom , você pode definir o comprimento de linha desejado.

Agora que temos uma ferramenta que ajudará a economizar tempo na formatação do código, pensaremos em como acelerar e simplificar o envio de código para o PyPI.

Etapa 2. Criando o arquivo .pypirc

Quando o fio é usado para enviar assemblies de aplicativos para TestPyPI e PyPI, você deve inserir manualmente as informações de login. Se você não está familiarizado com o barbante, dê uma olhada neste material. Agora vamos automatizar esse processo.

O fio pode trabalhar com o arquivo .pypirc , que deve estar em nosso diretório pessoal. Essa ferramenta, descarregando dados, usa um URL, nome de usuário e senha de um determinado arquivo.

Portanto, crie um arquivo .pypirc no seu diretório pessoal:

 touch ~/.pypirc 

Adicione o seguinte texto a ele:

 [distutils] index-servers =   pypi   testpypi [testpypi] repository: https://test.pypi.org/legacy username = your_username password = your_pypitest_password [pypi] username = your_username password = your_pypi_password 

É claro que aqui você deve digitar seu nome de usuário e senha reais. Além disso, verifique se esse arquivo está salvo no diretório inicial e não no diretório de trabalho atual. Se você deseja proteger este arquivo de outros usuários, é possível, usando as ferramentas de linha de comando, configurar suas permissões:

 chmod 600 ~/.pypirc 

Agora seu pacote pode ser carregado no TestPyPI usando o seguinte comando:

 twine upload -r testpypi dist/* 

No PyPI comum, você pode carregar pacotes como este:

 twine upload dist/* 

Depois de obter o arquivo .pypirc , você não precisa mais digitar manualmente seu nome de usuário e senha.

Agora, vamos adicionar ferramentas de teste ao nosso ambiente de desenvolvimento que nos permitirão verificar a operação correta do pacote que estamos criando.

Etapa 3. Instale e configure o pytest

O Pytest é a biblioteca mais popular e fácil de usar para testar código escrito em Python. Neste exemplo, adicionaremos testes simples ao projeto. Agora , se você estiver interessado nos detalhes do pytest, um bom guia introdutório para esta ferramenta.

Adicione os detalhes do pytest ao requirements_dev.txt :

 pytest==4.3.0 

Vamos instalar o pacote:

 pip install requirements_dev.txt 

Agora execute o seguinte comando, que permitirá ao pytest encontrar nosso pacote:

 pip install -e . 

Se você desativou seu ambiente de desenvolvimento virtual, precisará executar os dois comandos pip novamente para executar os testes.

Etapa 4. Criando testes

Adicione a pasta de test ao diretório raiz do seu projeto. Coloque o arquivo test_your_package_name.py nele. Meu arquivo é chamado test_notebookc.py . Se o nome do arquivo começar com test_ , o pytest poderá detectar automaticamente esse arquivo.

test_notebookc.py o seguinte teste ao arquivo test_notebookc.py , que visa verificar se a função exibe o nome correto. Modifique este código para que os nomes de arquivo e função usados ​​correspondam aos seus e descreva seus próprios testes.

 """Tests for `notebookc` package.""" import pytest from notebookc import notebookc def test_convert(capsys):   """Correct my_name argument prints"""   notebookc.convert("Jill")   captured = capsys.readouterr()   assert "Jall" in captured.out 

O que está acontecendo aqui?

Primeiro importamos nosso módulo aqui. Em seguida, criamos uma função cujo nome é construído de acordo com o modelo test_my_function_name . Essa convenção de nomenclatura de funções permite que outras pessoas que leem o código do seu projeto entendam rapidamente o que exatamente está sendo testado nos testes. Além disso, isso é necessário para um pacote que ajuda a controlar a cobertura do código com testes, que discutiremos abaixo.

Depois disso, chamamos a função ( convert ), passando o nome Jill como argumento. Próximo - capture o que a função exibe. Aqui vale a pena dizer que a função em questão é extremamente simples. Ela usa o parâmetro my_name e faz o seguinte:

 print(f"I'll convert a notebook for you some day, {my_name}.") 

O Pytest verifica se Jall está Jall no que a função gera. Essa linha não deve estar lá, pois passamos as funções Jill . Aqui está a documentação do pytest, onde você pode encontrar informações sobre a interceptação de saída.

Execute o teste digitando pytest no prompt de comando. Este teste deve falhar. As informações do erro são exibidas em vermelho.


Um erro foi detectado durante o teste.

Recomenda-se verificar se os testes estão corretos, descrevendo-os para que, sob certas condições, eles terminem com um erro. Você não deve escrever testes que fornecem apenas mensagens verdes; caso contrário, pode acontecer que os testes não verifiquem o que foram escritos para verificar.

Depois de garantir que o teste falhe, altere a instrução Jall para Jill e execute o teste novamente. Agora deve ser concluído com sucesso.


Conclusão bem sucedida do teste.

Agora está tudo bem. O teste permite garantir que, se alguém passar uma linha para nossa função, essa linha cairá no texto que essa função exibe.

Você também pode escrever um teste que verifique a função de como ele lida com os dados passados ​​para ele. Nomeadamente, se ele receber dados cujo tipo é diferente da sequência, ele deverá causar um erro de TypeError. Aqui estão algumas coisas boas sobre exceções e manipulação de erros no Python.

Quando criamos o teste anterior, escrevemos um código que leva à conclusão bem-sucedida do teste. Isso é chamado de Desenvolvimento Orientado a Testes (TDD). TDD é uma abordagem de programação comprovada que ajuda a escrever código com menos erros do que seria sem o TDD. Aqui está um material TDD útil.

Agora, como exercício, tente escrever um teste que verifique a função convert() para que, ao passar algo diferente da string, ela gere um erro e implemente os mecanismos apropriados para essa função. Observe que números inteiros, listas e dicionários são convertidos em seqüências de caracteres.

Depois que o pacote passou nos testes com sucesso, estamos prontos para tirar proveito do sistema de integração contínua.

Etapa 5. Registro no serviço Travis CI e sua configuração

O Travis CI é um "serviço da Web distribuído para criação e teste de software". Foi comprado recentemente pela Idera . Existem outros sistemas de integração contínua, mas o Travis CI é uma ferramenta popular, de código aberto e bem documentada, por isso vamos usá-la.

O Travis CI permite integrar no seu projeto apenas o código que passa nos testes e atende aos padrões. Aqui você pode ler mais sobre o Travis CI e aqui sobre integração contínua.

Crie uma conta em https://travis-ci.org/ . Em seguida, clique no link Review and add your authorized organizations na página de perfil. Você será solicitado a fornecer uma senha para acessar o GitHub. Clique em Grant na seção de Organization access da Organization access .


Configurar uma conta Travis CI

Eu precisava sincronizar a conta para que as informações sobre notebooktoall e o repositório notebookc aparecessem na conta. Normalmente, para o Travis CI trabalhar com código, leva cerca de um minuto. Depois disso, você precisa ativar o repositório usando a opção mostrada na figura a seguir.


Ativação de Repositório

Agora clique no botão Settings . Aqui você precisa indicar se o Travis pode construir com base em solicitações pull ou ramificações enviadas ao repositório.


Configuração de construção do projeto

Agora é hora de configurar o projeto em que estamos trabalhando, o que permitirá que Travis construa o projeto para cada solicitação de recebimento.

Etapa 6. Criando o arquivo .travis.yml

Na pasta raiz do projeto, crie um arquivo .travis.yml com o seguinte conteúdo:

 dist: xenial language: python python: 3.7.2 install: - pip install -r requirements_dev.txt - pip install -e . script: - pytest 

A dist: xenial necessária para dizer ao Travis para usar o Ubuntu Xenial 16.04 para organizar o ambiente virtual. Para testar o código Python 3.7, é necessário o Ubuntu Xenial, detalhes sobre isso podem ser encontrados aqui .

A seção de install permite instalar pacotes usados ​​no desenvolvimento do projeto. Comando pip install -e . realiza a instalação do nosso pacote no ambiente virtual do Travis. Depois disso, Travis, iniciando o pytest, poderá encontrar nosso pacote.

Etapa 7. Testando no Travis CI

Confirme as alterações, envie-as ao GitHub, faça o PR. Travis deve começar a trabalhar em segundos.


Travis no trabalho

É isso que Travis faz ao lidar com o projeto.


Ações executadas por Travis durante o processamento do projeto

Se o PR não tiver êxito - Travis o denunciará. Observe que, se a solicitação de recebimento não for bem-sucedida, você poderá enviar as alterações para a mesma filial e o Travis começará a funcionar automaticamente.

Vá para a página do seu repositório no site do Travis e olhe por aí. Aqui você encontra muitas coisas interessantes sobre montagens. Provavelmente, no futuro, você se tornará um convidado frequente desta página ao tentar entender o que causou a falha na montagem.

Se assumirmos que tudo correu bem, se a página contiver rótulos verdes, a verificação e montagem do projeto foram bem-sucedidas.


Montagem do projeto concluída com sucesso

Se não houver rótulos verdes ou vermelhos na página, abra o menu More options e selecione Requests . Se você vir aqui mensagens de erro vermelhas, analise-as. Se você .travis.yml mensagem de erro Build config file is required , significa que o Travis não pode encontrar o arquivo .travis.yml no repositório. Corrija-o e o erro desaparecerá.

Travis envia e-mails aos usuários nos casos em que a montagem do projeto não é bem-sucedida e nos casos em que é possível corrigi-lo.

Lembre-se de que você pode enviar confirmações para abrir o PR e o Travis reiniciará automaticamente o processo de criação do projeto.

Agora vamos analisar nosso projeto para cobrir o código com testes.

Etapa 8. Avaliando a cobertura do código com testes

O relatório sobre a cobertura do código com testes permite descobrir qual parte do código do projeto, embora pequena, foi testada. Para criar esses relatórios, usaremos o pacote pytest-cov .

Adicione a seguinte linha ao arquivo requirements_dev.txt :

 pytest-cov==2.6.1 

Execute o seguinte comando:

 pytest --cov=my_project_name 

No meu caso, após a pytest --cov=notebookc , o seguinte relatório foi exibido.


Relatório de Cobertura de Código

Como se viu, todo o código do projeto é fornecido com testes. Esses indicadores são muito fáceis de serem alcançados se o projeto inteiro consistir em várias linhas de código.

Agora, vamos falar sobre uma ferramenta que permite manter um histórico público do estado do projeto em termos de cobertura de seu código com testes.

Etapa 9. Usando Macacão

O projeto Coveralls permite manter informações históricas sobre a cobertura de código com testes.


Macacão

Para aproveitar os recursos deste projeto, você precisa se registrar no site https://coveralls.io/ usando os dados da sua conta do GitHub. Então você precisa conectar o repositório.

No arquivo requirements_dev.txt , inclua a linha coveralls==1.6.0 . Este arquivo, a propósito, nesta fase do trabalho no projeto deve se parecer com o seguinte:

 pip==19.0.3 wheel==0.33.0 twine==1.13.0 pytest==4.3.0 pytest-cov==2.6.1 coveralls==1.6.0 

.travis.yml arquivo .travis.yml , trazendo-o para este formulário (no seu caso, o nome do seu projeto estará aqui):

 dist: xenial language: python python: 3.7.2 install: — pip install -r requirements_dev.txt — pip install -e . script: — pytest --cov=my_package_name after_success: — coveralls 

Agora, quando Travis criar o projeto, ele instalará os pacotes necessários, executará os testes e criará um relatório sobre a cobertura do código com os testes. Em seguida, esse relatório será enviado ao serviço Coveralls.

Confirme, envie o código ao GitHub e observe o que acontece. Pode levar alguns minutos para o relatório de teste de cobertura de código entrar no Coveralls.


Processamento do projeto, relatório de cobertura do teste

Agora, entre as verificações de relações públicas, há também uma verificação realizada pelo Coveralls.

Na página Macacões, você pode verificar se o projeto é 100% coberto em testes.


Informações sobre cobertura de teste

Agora vamos equipar nosso projeto com outra ferramenta útil.

Etapa 10. Trabalhando com PyUp

O serviço PyUp.io permite que o desenvolvedor descubra se as dependências usadas por ele estão desatualizadas e se possuem vulnerabilidades. Este serviço executa automaticamente solicitações pull destinadas a atualizar o pacote no GitHub. Para tirar proveito dos recursos deste projeto, você precisa se registrar usando uma conta do GitHub, no site - https://pyup.io/ . Ao adicionar um repositório, é recomendável definir os Update Schedules every week . Com essa abordagem, se o seu projeto tiver muitas dependências, você não encontrará muitas solicitações pull.


Configurar atualizações

Aqui está a aparência das informações do pacote, algumas das quais estão desatualizadas, no site do PyUp.io.


Detalhes do pacote

Usando este serviço, você sempre saberá quando as versões mais recentes dos pacotes que você usar serão lançadas. O conhecimento, como se costuma dizer, é metade da vitória. E a segunda metade é, obviamente, solicitações de recebimento automáticas para atualizar dependências.

Sumário

Neste artigo, você aprendeu como usar ferramentas como Black, pytest, Travis CI, Coveralls e PyUp ao desenvolver projetos Python. Eles ajudam a controlar as dependências do projeto, formatar e testar o código, além de verificar e criar projetos. Esperamos que você ache essas ferramentas úteis.

Caros leitores! Quais ferramentas você usa ao desenvolver projetos Python?