Automatizar as verificações do projeto com Nox

O Nox lê um arquivo chamado noxfile.py e executa as sessões declaradas nele. Cada sessão prepara um ambiente isolado, instala o que precisa e roda comandos.

Ele não substitui as ferramentas: Ruff continua formatando e analisando código; mypy verifica tipos; pytest executa testes; build cria artefatos. O papel do Nox é tornar essa sequência explícita e reproduzível.

A sessão usa seu próprio ambiente, mas trabalha sobre os mesmos arquivos do projeto.

No computador, crie uma pasta vazia para a prática. Dentro dela, crie pyproject.toml e src/saudacao/__init__.py com os conteúdos abaixo. Esta base é instalável, mas nesta primeira sessão ainda não vamos instalar nem testar o pacote.

Metadados mínimos para identificar o projeto.

Um módulo mínimo compartilhado pela futura rotina de verificações.

No noxfile.py, o decorador @nox.session registra uma função como sessão. Dentro dela, session.install(...) instala dependências no ambiente da sessão. Já session.run(...) executa um comando nesse ambiente.

Vamos apenas consultar a versão do Ruff. Isso confirma o isolamento e a instalação sem iniciar as verificações de qualidade ainda.

Crie este arquivo na raiz do projeto, ao lado de pyproject.toml.

Crie e ative, se desejar, um ambiente virtual dedicado ao Nox. Então instale uma versão definida e execute os comandos a partir da raiz do projeto.

As dependências em [project.dependencies] são necessárias para quem instala e usa sua aplicação. Já Nox, Ruff, mypy e pytest servem para desenvolver e validar o projeto; mantenha suas versões em arquivos de requisitos de verificação, separados.

Fixar uma versão direta, como ruff==0.9.10, torna a ferramenta escolhida explícita. O próprio Nox também deve ter uma versão controlada no ambiente local que o executa.

Crie estes arquivos no projeto. As versões são exemplos: escolha e atualize versões de acordo com a política do seu projeto.

Mantenha as opções das ferramentas no pyproject.toml. O Nox coordena instalações e comandos, mas não deve virar um segundo arquivo de configuração do Ruff, mypy ou pytest.

Cada sessão instala seu requisito direto. Os nomes dos alvos ficam explícitos; a implementação dos comandos de verificação será acrescentada nos próximos steps.

Configure a sessão test para a suíte unitária, por exemplo em tests/unit. Mantenha os testes de aceitação da distribuição em outro alvo, como tests/acceptance, reservado à futura sessão package.

Esses testes dependem de uma wheel construída na própria execução; portanto, executá-los junto dos unitários poderia tentar validá-los antes de existir um artefato.

Mantenha duas sessões: uma confere a formatação e outra executa o lint. Na rotina de entrega, use ruff format --check, que apenas compara o arquivo com a formatação esperada, e ruff check, sem --fix, que apenas relata problemas.

Assim, um desvio produz uma falha visível em vez de uma alteração silenciosa no código analisado.

Cada sessão cria seu próprio ambiente, executa o Ruff e lê os arquivos compartilhados do projeto. Os comandos de verificação não reescrevem esses arquivos.

No noxfile.py, use o arquivo de requisitos de verificação que você organizou no step anterior. Abaixo, ele está em requirements/verificacao.txt; ajuste somente esse caminho se o seu projeto adotou outro nome.

Adicione estas sessões ao arquivo. Elas instalam somente o Ruff e executam verificações sem opções de correção.

Crie temporariamente o arquivo formatacao_demo.py na raiz do projeto com o conteúdo abaixo. Em seguida, execute python -m nox -s format_check. Compare o arquivo com o conteúdo exibido: a sessão deve falhar, mas o arquivo deve continuar idêntico ao que você criou.

Este arquivo está propositalmente fora da formatação esperada.

Depois de observar a falha, restaure o arquivo manualmente para a versão formatada abaixo — ou apague o arquivo temporário — antes de continuar o projeto.

Uma sessão Nox deve instalar apenas o que precisa para seu trabalho. A sessão de mypy verifica anotações nos módulos escolhidos. A sessão de pytest testa comportamentos; se os testes fazem import do seu pacote, ela também instala o projeto no ambiente isolado.

Não inclua aqui os testes de aceitação da distribuição: eles dependem de um artefato construído e serão encadeados em outra sessão.

Cada sessão prepara seu próprio ambiente antes de executar seu comando.

Partindo dos requisitos de verificação organizados anteriormente, acrescente sessões como estas ao seu noxfile.py. Ajuste src e tests/unit se os diretórios do seu projeto tiverem outros nomes.

A instalação session.install(".") usa o projeto local no ambiente da sessão. Ela é necessária quando os testes importam o pacote, especialmente em layout src.

Na raiz do projeto, execute:

python -m nox -s typecheck
python -m nox -s tests

Se uma chamada de session.install(...) falhar, o problema ocorreu na preparação do ambiente: requisito inexistente, versão incompatível ou erro ao instalar o projeto. Se mypy ou pytest iniciar e retornar código não zero, a falha pertence à verificação indicada no diagnóstico. Nox preserva esse resultado como falha da sessão; não o oculte.

A sessão delivery deve conter toda a cadeia: instalar as ferramentas de verificação, construir a sdist e a wheel em uma pasta nova, localizar uma única wheel e executar os testes de aceitação apontando para ela.

Como session.run() interrompe a sessão quando um comando retorna código diferente de zero, uma falha no build impede automaticamente os testes seguintes. Isso é mais confiável do que supor uma ordem entre sessões independentes.

O ambiente da sessão contém build e pytest; o ambiente temporário criado pelo teste contém somente a aplicação instalada e suas dependências de execução.

Crie um arquivo de requisitos específico para a entrega. Ele controla as versões de build e pytest usadas no ambiente da sessão, sem adicioná-las às dependências normais da aplicação.

A sessão cria uma pasta temporária, constrói nela e transforma o caminho da wheel em caminho absoluto antes de passá-lo como WHEEL_PATH.

Crie este arquivo no projeto.

Adicione esta sessão ao noxfile.py. Ajuste somente o caminho de tests/acceptance se sua suíte estiver em outro local.

O teste lê WHEEL_PATH, rejeita um valor ausente ou que não aponte para uma wheel existente e instala exatamente esse arquivo. O diretório de trabalho fica fora da árvore do projeto e PYTHONPATH é removido: assim, as fontes locais não podem substituir a distribuição instalada.

O exemplo usa o comando tarefas, definido anteriormente em [project.scripts]. Se o seu projeto usa outro ponto de entrada, substitua apenas esse nome e os argumentos esperados.

Este teste é autocontido: ele cria o ambiente limpo, instala a wheel recebida e executa o comando instalado.

Considere um projeto com requires-python = ">=3.10". A rotina deve incluir obrigatoriamente o Python 3.10, pois ele é o limite mínimo prometido. Selecione também versões concretas que você realmente consegue executar, por exemplo 3.10 e 3.12.

O Python que inicia o Nox pode ser diferente dos interpretadores das sessões. Ferramentas estáticas, como Ruff e mypy, podem usar um único interpretador de referência — aqui, 3.12. Já os testes e a validação da distribuição devem rodar na matriz escolhida, porque executam a aplicação.

O argumento python de @nox.session expande uma função em sessões independentes. Com a matriz abaixo, python -m nox -l mostrará, entre outras, tests-3.10, tests-3.12, delivery-3.10 e delivery-3.12.

A sessão delivery continua construindo e validando a wheel como no passo anterior. Como o pytest dessa sessão é executado no ambiente Nox parametrizado, o teste de aceitação deve criar o ambiente limpo da aplicação a partir do interpretador atual dele — por exemplo, usando sys.executable ou venv.EnvBuilder dentro do teste. Assim, uma entrega em delivery-3.10 é instalada e executada com Python 3.10, não apenas analisada por outra versão.

Ajuste os comandos e os arquivos de requisitos aos que você já criou nas sessões anteriores.

Defina em noxfile.py quais sessões formam a validação obrigatória. Ao executar Nox sem -s, ele usará nox.options.sessions.

Inclua as verificações estáticas uma vez, no interpretador de referência, e as sessões parametrizadas de teste e entrega para cada versão que você decidiu cobrir. Os nomes com parênteses correspondem às expansões da matriz.

No início do noxfile.py, depois de importar nox:

As verificações estáticas não precisam se repetir em cada Python, mas os testes e a validação da wheel precisam usar cada interpretador selecionado.

Com o ambiente que contém Nox ativado, execute este comando na raiz — onde estão noxfile.py e pyproject.toml:

Se um comando chamado por session.run termina com código diferente de zero, aquela sessão falha. Ao final, basta uma sessão obrigatória falhar para o processo global do Nox terminar com código diferente de zero.

Sem uma política adicional, Nox pode continuar executando outras sessões independentes e mostrar mais diagnósticos. Isso não transforma a execução em sucesso.

Use esta variação apenas quando quiser privilegiar rapidez em vez de coletar todas as falhas da mesma execução:

Ao final, a validação completa é acionada da raiz do projeto com:

python -m nox --error-on-missing-interpreters

Cada arquivo tem uma responsabilidade: pyproject.toml reúne metadados e opções das ferramentas; os arquivos em requirements/ fixam as versões das ferramentas; e noxfile.py cria ambientes isolados e coordena os comandos. A suíte de aceitação criada anteriormente continua responsável por instalar e exercitar a wheel em um ambiente limpo.

A execução padrão percorre verificações estáticas, testes em mais de uma versão do Python e a entrega testada a partir da wheel recém-construída.

Mantenha os metadados de seu projeto já existentes e confirme que as opções abaixo estão em pyproject.toml. Os diretórios src, tests/unit e tests/acceptance correspondem à estrutura usada na prática anterior.

Acrescente estas tabelas ao seu pyproject.toml, preservando as demais tabelas de construção e de metadados do projeto.

Crie cada arquivo com o respectivo conteúdo. Essas dependências não pertencem a project.dependencies: elas existem para executar a validação.

Este arquivo torna Python 3.11 e 3.12 obrigatórios para os testes e para a validação da distribuição. As ferramentas estáticas usam Python 3.11 como interpretador de referência. A sessão delivery cria um diretório novo, exige exatamente uma wheel e entrega seu caminho absoluto à suíte de aceitação por PACKAGE_WHEEL.

Substitua ou complete seu noxfile.py por esta configuração. Ela pressupõe que tests/acceptance já lê PACKAGE_WHEEL, rejeita um caminho ausente ou inválido e instala a wheel indicada em um ambiente limpo.

1. No ambiente local dedicado ao Nox, instale a versão fixada: python -m pip install -r requirements/nox.txt.
2. Na raiz do projeto, execute python -m nox --error-on-missing-interpreters. Registre o resumo: todas as sessões devem passar e o processo deve terminar com código zero.
3. Em um arquivo Python de src/, escolha uma atribuição simples, como valor = 1, e introduza deliberadamente um espaço extra: valor = 1.
4. Execute o mesmo comando. A sessão format deve falhar. Compare o arquivo: ele ainda contém o espaço extra, pois ruff format --check apenas verifica; não corrige.
5. Restaure exatamente a linha original e execute o comando completo mais uma vez.

A aprovação só é completa se as sessões obrigatórias, incluindo cada versão selecionada e cada delivery, forem aprovadas. Um interpretador ausente, uma sessão ignorada ou a execução de apenas uma sessão não comprovam a entrega.