O guia completo para a configuração do projeto Python

May 02 2023

Comece seu projeto da maneira certa e colha os frutos por anos

Python é uma linguagem excelente usada para tudo, desde a construção de sites até pesquisas científicas complexas. Mas configurar seu projeto pode ser um desafio.

Python é uma linguagem excelente usada para tudo, desde a construção de sites até pesquisas científicas complexas. Mas configurar seu projeto pode ser um desafio. É aí que entra este guia! Neste artigo, mostraremos como organizar seu projeto, configurar ambientes virtuais, gerenciar dependências, formatar seu código, testar seu código e muito mais. Abordaremos tudo o que você precisa saber para fazer seu projeto Python decolar e funcionar sem problemas.

Acima de tudo, mantenha-o simples

Python é feito para ser simples. Execute import thisem um Python REPL e você obterá The Zen of Python.

>>> import this
The Zen of Python, by Tim Peters

Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!

De fato, a proporção de tempo gasto lendo versus escrevendo é bem superior a 10 para 1. Estamos constantemente lendo códigos antigos como parte do esforço para escrever novos códigos. …[Portanto,] facilitar a leitura facilita a escrita.

Fonte: Robert C. Martin, Clean Code: A Handbook of Agile Software Craftsmanship

Ao configurar um projeto Python, é fundamental definir o padrão de escrita de código sustentável — código com baixa sobrecarga cognitiva. Fácil de ler. Fácil de encontrar. Fácil de seguir.

estrutura de diretório

Um projeto bem mantido começa com uma estrutura de diretório acessível. Seu objetivo aqui (e em todos os lugares, na verdade) é reduzir o atrito para que os desenvolvedores entendam o que o código faz.

Use um diretório raiz para seu projeto. Crie um diretório raiz para o seu projeto e nomeie-o com o nome do seu projeto. Dê um nome sensato ao seu projeto. Prefiro nomear projetos e módulos de acordo com o que eles fazem e evito usar codinomes para as coisas.
Use subdiretórios para seu código. Organize seu código em subdiretórios com base em componentes ou módulos lógicos. Por exemplo, você pode ter um subdiretório para seu código de processamento de dados, um subdiretório para seu código de visualização e assim por diante.
Use um __init__.pyarquivo em diretórios contendo módulos. Se você tiver um diretório contendo módulos Python, inclua um __init__.pyarquivo no diretório. Isso informa ao Python que o diretório é um pacote e permite que você importe módulos do pacote.
Use nomes descritivos para seu projeto, arquivos e diretórios. Use nomes descritivos que deixem claro o que cada módulo, arquivo e diretório contém. Isso tornará mais fácil para outras pessoas entenderem seu código e navegarem em seu projeto (e mais fácil para você depois de encerrar seu projeto por algumas semanas).
Mantenha seus testes ao lado de seu código. Alguns engenheiros gostam de criar um testsdiretório para escrever seus testes. Prefiro manter os testes ao lado do código que está sendo testado. Se você tiver um arquivo chamado models/user.py, o arquivo de teste deve ser models/user_test.py. Isso deixa claro onde está seu código e onde estão seus testes, além de permitir que você os mantenha no mesmo espaço cognitivo.
Utilize um ambiente virtual. Use um ambiente virtual para gerenciar suas dependências e garantir que seu projeto seja executado de forma consistente em diferentes ambientes. Mais sobre isso mais tarde.

ambientes virtuais

Um ambiente virtual é um ambiente Python independente que permite instalar pacotes e dependências para seu projeto sem afetar a instalação global do Python em seu sistema. Os ambientes virtuais são importantes porque ajudam a garantir que as dependências do seu projeto sejam consistentes em diferentes ambientes, facilitando a reprodução e a manutenção do seu projeto.

Para configurar um ambiente virtual para seu projeto, você pode usar uma ferramenta como Poetry , virtualenv ou conda . A maioria dos tutoriais e cursos usa virtualenv, então falarei sobre isso primeiro.

Veja como configurar um ambiente virtual usando virtualenv:

Instale virtualenv. Você pode instalar virtualenv usando pip, o gerenciador de pacotes Python. Abra seu terminal e execute pip install virtualenv.
Crie um ambiente virtual. Navegue até o diretório do seu projeto e execute virtualenv venv. Isso criará um novo ambiente virtual no diretório atual chamado venv.
Ative o ambiente virtual. Para ativar o ambiente virtual, execute source venv/bin/activateno Linux/Mac ou venv\Scripts\activateno Windows.

Eu uso o Poetry para gerenciar ambientes virtuais para todos os meus projetos Python. Veja como usar Poesia:

Instala Poesia. Você pode instalar o Poetry seguindo as instruções de instalação no site do Poetry .
Crie um novo projeto. Navegue até o diretório onde deseja criar seu projeto e execute poetry new myproject. Isso criará um novo diretório de projeto chamado myprojectcom uma estrutura básica de projeto dentro.
Ative o ambiente virtual. Para ativar o ambiente virtual do seu projeto, execute poetry shell. Isso criará um novo ambiente virtual e o ativará. Caso queira executar um comando no ambiente virtual sem ativá-lo, utilize poetry run <command>assim:poetry run python main.py
Instalar pacotes e dependências. Para instalar pacotes e dependências para seu projeto, execute poetry add package_name. Isso instalará o pacote e o adicionará ao pyproject.tomlarquivo do seu projeto. Mais sobre isso mais tarde.

Saiba mais sobre Poesia →

Se você estiver usando o VS Code, também poderá usar o Devcontainers como alternativa aos ambientes virtuais. Devcontainers são ambientes pré-configurados que rodam dentro de containers Docker e permitem que você desenvolva e teste seu código em um ambiente consistente. Eu prefiro Devcontainers porque trabalho em vários computadores com 3 sistemas operacionais diferentes. A combinação Poetry + Devcontainer significa que não gasto nenhum esforço tentando fazer meu código funcionar em sistemas diferentes. Isso sempre acontece.

Há um ótimo artigo de Dexter Williams sobre Python Devcontainers. Vá conferir →

Introdução aos contêineres de desenvolvimento do Python 3

Dependências

As dependências do projeto são pacotes externos ou bibliotecas (código que outras pessoas escreveram) que seu projeto Python usa para funcionar corretamente. As dependências podem incluir coisas como estruturas da web, drivers de banco de dados ou bibliotecas de aprendizado de máquina.

Em vez de copiar o código de outras bibliotecas para a sua própria, o Python (e a maioria das outras linguagens) oferece suporte à instalação de dependências por meio de uma ferramenta de gerenciamento de dependências chamada pip. Você pode encontrar projetos disponíveis para instalação em PyPI.org .

pipé uma boa ferramenta. Mas é básico. Em todos os meus projetos Python, eu uso poetrypara gerenciar dependências. É a mesma ferramenta que uso para gerenciar ambientes virtuais.

Instale o Poetry com este comando:

curl -sSL https://install.python-poetry.org | python3 -

poetry new myproject
cd myproject

poetry add requests

Existem alguns outros recursos que facilitam poetrya escolha. Seus documentos têm uma lista de recursos atualizada.

Use o show de poesia — árvore para ver as dependências downstream.

Saiba mais sobre Poesia →

Formatação de código

A formatação do código refere-se à maneira como o código é estruturado e estilizado, incluindo coisas como recuo, espaçamento entre linhas e convenções de nomenclatura. Embora possa parecer um pequeno detalhe, um código consistente e bem formatado é fundamental para a integridade de um projeto a longo prazo.

O código formatado de forma consistente torna seu código mais legível e compreensível para você e para outros desenvolvedores que possam estar trabalhando no projeto. Quando o código é formatado de forma consistente, fica mais fácil identificar padrões e estruturas dentro do código. Código formatado consistentemente é mais fácil de ler, entender e manter

Lembre-se de nossa citação de Bob Martin? Mais tempo é gasto lendo código do que escrevendo. Se esse código for formatado de forma consistente, a leitura será muito mais fácil.

Para isso, sempre uso black. Existem outros formatadores por aí. E blacknão é muito configurável. Mas esse é o ponto de venda. Qualquer equipe que optar por adotar blackreceberá um código exatamente igual em todos os lugares. Não há mais discussões sobre formatação porque a escolha já foi feita. E se integra a todos os editores de código que já usei.

poetry add black --group dev

Ao usar Black , você concorda em ceder o controle sobre as minúcias da formatação manual. Em troca, o preto oferece velocidade, determinismo e liberdade de pycodestyleresmungar sobre a formatação. Você economizará tempo e energia mental para assuntos mais importantes.

Saiba mais sobre Preto →

Linting de código

O linting de código e a formatação de código estão relacionados, mas não são a mesma coisa.

A formatação do código refere-se à maneira como o código é estruturado e estilizado, incluindo coisas como recuo, espaçamento entre linhas e convenções de nomenclatura. Trata-se de garantir que o código seja fácil de ler e entender, o que pode facilitar a depuração e a manutenção ao longo do tempo.

Por outro lado, code linting envolve a análise do código em busca de possíveis erros ou problemas que possam causar problemas. Linters analisam coisas como erros de sintaxe, variáveis não utilizadas e outros bugs em potencial e podem fornecer sugestões de como corrigi-los.

Minha ferramenta de linting de escolha é pylint. Ele analisa sua base de código Python para identificar possíveis erros e problemas. O Pylint também fornece sugestões de como corrigir esses problemas, juntamente com uma pontuação que representa a qualidade geral da sua base de código. Essa pontuação pode ser usada como referência para ajudá-lo a identificar áreas em que seu código pode ser melhorado e facilitar a manutenção ao longo do tempo.

poetry add pylint --group dev

Usando `pylint`com`black`

Você certamente terá alguns conflitos ao usar ferramentas sobrepostas. Black chama isso em seus documentos e fornece a solução: configuração clara.

A partir de hoje, há apenas uma opinião de estilo conflitante entre Pylint e Black: comprimento da linha. Você pode definir isso para Pylint em seu arquivo pyproject.toml.

# pyproject.toml
[tool.pylint.format]
max-line-length = "88"

Saiba mais sobre Pylint →

teste

Por que testar é importante
Tipos de testes que você pode escrever (por exemplo, testes de unidade, testes de integração)
Ferramentas que você pode usar para testar (por exemplo, pytest, unittest)
Práticas recomendadas para escrever e organizar testes

O padrão de fato para testes robustos em Python é o Pytest . O Pytest vem com recursos poderosos prontos para uso, como saída de falha de teste detalhada e uma API simples. Ele também se integra ao Django, Jupyter e dezenas de outras ferramentas Python.

poetry add pytest --group dev

Use uma estrutura de teste. O Python tem vários, embora eu recomende fortemente o uso do Pytest. Usar uma estrutura de teste facilita escrever e gerenciar seus testes.
Escreva testes para cada função e método. Escreva testes para cada função e método em sua base de código para garantir que eles funcionem conforme o esperado. Isso torna mais fácil identificar e corrigir problemas em sua base de código à medida que as coisas mudam.
Use nomes de teste descritivos. Dê a cada teste um nome que descreva o que ele está testando (por exemplo, test_user_can_authenticate). Isso facilita a compreensão do que cada teste está fazendo e pode ajudar a identificar problemas mais rapidamente.
Use métodos de configuração e desmontagem. Use métodos de configuração e desmontagem para configurar quaisquer acessórios de teste necessários e limpar após cada teste. Isso garante que os testes sejam executados em um ambiente limpo e que não haja efeitos colaterais persistentes de testes anteriores.
Organize seus testes em suítes de teste. Organize seus testes em suítes de teste com base em sua finalidade ou funcionalidade. Isso facilita a execução de testes específicos (ou grupos de testes) e pode identificar problemas mais rapidamente.

A Integração Contínua (CI) e a Implantação Contínua (CD) são processos que automatizam a criação, o teste e a implantação de alterações de código. CI é o processo de construir e testar automaticamente as alterações de código assim que elas são confirmadas no repositório de código. CD é o processo de implantação automática de alterações de código em ambientes de produção ou preparação depois que passam nos testes de CI.

CI/CD (juntos como um conceito) é importante porque detecta problemas no início do processo de desenvolvimento e garante que as alterações de código sejam seguras para implantação na produção. A chave para o sucesso é que essas ferramentas criam, testam e implementam mudanças automaticamente . Os desenvolvedores não precisam se lembrar de aplicar esses processos manualmente após cada alteração e não podem escolher. Simplesmente acontece, e simplesmente funciona.

Existem muitas ferramentas de CI/CD, e a melhor para o seu caso de uso é provavelmente a mais integrada ao seu fornecedor Git (GitHub, GitLab, Bitbucket, etc.). O processo é o mesmo para qualquer plataforma.