Caderno operacional — instalação limpa e segura

Situação concreta

Uma tarefa de importação depende de uma variável que existia apenas no terminal do autor. Em homologação, ela começa, cria arquivos parciais e falha. Você construirá um projeto mínimo que verifica ambiente antes de qualquer efeito e pode ser recriado sem Internet.

Pré-requisitos, objetivos e artefatos

Leia A oficina reproduzível. Tenha Python 3 e PowerShell ou Bash. Crie uma pasta descartável chamada oficina-terminal. Entregue doctor.py, verify.py, requirements.lock, SETUP.md e transcript.txt sanitizado.

Bootstrap é o procedimento que prepara o projeto. Idempotente significa que repetir produz o mesmo efeito pretendido. Transcript é o registro textual dos comandos e resultados. Dry run descreve o que faria sem aplicar alterações.

Modelo mental e limite

O laboratório não instala pacote externo e, portanto, não prova resolução de dependências de terceiros. Ele isola runtime, configuração e comandos. Num projeto real, manifesto e lockfile entram no mesmo ciclo.

Antes e agora

Um README pode listar passos que envelhecem. Um bootstrap atual combina instrução curta com comandos testáveis e integração contínua. Contêiner pode reforçar isolamento, mas não é requisito para um script pequeno. Escolha a menor ferramenta que outra pessoa consegue recriar e verificar.

Passo 1 — crie o diagnóstico

Crie doctor.py:

from pathlib import Path
import os
import platform
import sys

problemas = []
if sys.version_info < (3, 11):
    problemas.append(f"Python >= 3.11 esperado; observado {platform.python_version()}")
if not os.environ.get("APP_ENV"):
    problemas.append("APP_ENV ausente; defina development ou test")

print("python:", platform.python_version())
print("diretorio:", Path.cwd())
print("executavel:", sys.executable)
for problema in problemas:
    print("ERRO:", problema)

raise SystemExit(1 if problemas else 0)

O programa apenas observa. Ele não cria pastas nem corrige configuração. Isso torna seguro executá-lo repetidamente. A mensagem apresenta esperado e observado.

Passo 2 — crie a verificação

Crie verify.py:

from pathlib import Path
import ast

fontes = [Path("doctor.py"), Path("verify.py")]
faltantes = [str(caminho) for caminho in fontes if not caminho.exists()]
if faltantes:
    raise SystemExit("arquivos ausentes: " + ", ".join(faltantes))

for caminho in fontes:
    ast.parse(caminho.read_text(encoding="utf-8"))
    print("sintaxe válida:", caminho)

print("VERIFY_OK")

ast.parse verifica sintaxe Python sem executar o arquivo. Num projeto real, verify também rodaria formatação, tipos, testes e build. Cada etapa precisa encerrar com falha se seu controle falhar.

Passo 3 — crie e use o ambiente

No PowerShell:

python -m venv .venv
& .\.venv\Scripts\python.exe doctor.py
$env:APP_ENV = 'test'
& .\.venv\Scripts\python.exe doctor.py
& .\.venv\Scripts\python.exe verify.py
& .\.venv\Scripts\python.exe -m pip freeze | Set-Content -Encoding utf8 requirements.lock

No Bash, o executável costuma ser .venv/bin/python e a variável pode ser definida com export APP_ENV=test. O primeiro doctor deve retornar 1; os seguintes, 0. Um lock vazio é resultado válido neste projeto sem dependência.

Passo 4 — remova somente o ambiente e recrie

Pare antes da limpeza. Resolva o caminho de .venv, confirme que termina na pasta do projeto e que o código está fora dela. Remova somente esse ambiente com o comando nativo do seu shell. Não use curingas, raiz ou pasta pessoal. Em seguida, execute novamente python -m venv .venv e os comandos de verificação.

O segundo resultado não deve depender de arquivo gerado dentro do ambiente antigo. Se depender, o bootstrap está incompleto. Guarde comandos e códigos de saída, não todo o ambiente.

Resultado esperado e como confirmar

Não use apenas a frase “funcionou” como evidência. O transcript precisa mostrar uma sequência que outra pessoa consiga comparar com a própria execução:

1. o primeiro doctor apresenta a versão e o diretório, informa APP_ENV ausente e encerra com código 1;
2. depois de definir APP_ENV=test, o mesmo arquivo encerra com código 0 sem criar ou modificar artefatos do projeto;
3. verify imprime uma linha de sintaxe válida para cada fonte e termina com VERIFY_OK;
4. após remover e recriar .venv, os passos 2 e 3 produzem o mesmo resultado observável.

No PowerShell, execute $LASTEXITCODE imediatamente depois de cada processo Python. No Bash, use echo $?. Leia o código antes de executar o comando seguinte, porque uma nova execução substitui esse valor. Registre também python --version, o caminho do executável e o diretório do projeto; eles permitem distinguir falha no código de falha causada pelo ambiente errado.

Evite um doctor --fix neste exercício. Corrigir automaticamente parece conveniente, mas mistura diagnóstico e alteração, pode esconder a causa e exige permissões maiores. Primeiro torne a divergência visível. Se o projeto futuro precisar de correção automatizada, crie um comando separado, com dry run, alvo explícito e teste que demonstre exatamente o que será modificado.

Falhas e diagnóstico

Execute doctor.py sem APP_ENV: a falha esperada é configuração ausente. Para simular versão incompatível sem instalar Python antigo, altere temporariamente o requisito para (99, 0) e registre mensagem; reverta. Mova doctor.py e rode verify.py: ele deve listar o arquivo ausente.

Classifique cada falha como runtime, configuração, caminho ou conteúdo. A correção mínima não usa administrador. Se permissão de escrita falhar, confirme se o projeto está numa pasta apropriada; não amplie acesso ao disco inteiro.

Aplicação em manutenção e ERP

Para um job real, doctor pode verificar presença — nunca o valor — da credencial, URL de homologação e pasta de entrada. Não deve chamar o sistema de planejamento de recursos empresariais (ERP) nem alterar ordem. verify valida o artefato antes da promoção. run executa o lote com identificador e idempotência.

Uma matriz de ambientes registra runtime, artefato, configuração, identidade, dados e destino dos logs. O mesmo artefato segue para homologação e produção; credenciais e configuração mudam por ambiente.

Segurança e privacidade

Use APP_ENV=test, nunca segredo real. Não capture Get-ChildItem Env: ou env completo no transcript. Não versionar .venv nem credenciais. Pacotes instalados executam código e pertencem à cadeia de suprimentos; este laboratório evita rede para manter escopo seguro.

Ao documentar limpeza, escreva alvo e pré-condições. “Apague a pasta” é insuficiente. Prefira ferramenta ou comando que aceite caminho literal e confirme escopo.

Exercício guiado

Acrescente a exigência ERP_BASE_URL, aceitando apenas valor iniciado por https:// ou uma URL local de teste explicitamente permitida. Não faça conexão. Crie três casos: ausente, insegura e válida. Execute doctor duas vezes e compare códigos.

Desafio e evidência

Entregue os cinco artefatos e peça a outra pessoa para recriar em outra pasta. Ela deve observar uma falha prevista e depois sucesso.

Critérios de aceite:

• ambiente virtual é criado do zero e recriado;
• doctor não altera o projeto e retorna código útil;
• verify falha quando fonte está ausente;
• transcript registra versões e comandos sem segredos;
• limpeza aponta somente para ambiente validado;
• segunda execução não depende da primeira.

Conclusão e transição

Você separou diagnóstico, preparação e verificação; provou uma falha antes de corrigi-la; e recriou apenas o ambiente. Essa oficina sustentará os próximos algoritmos: código correto precisa de execução reproduzível para que seus testes tenham valor.

Fontes oficiais

• Python — venv: ambiente virtual usado.
• Python — os: acesso controlado a variáveis de ambiente.
• Python — pathlib: caminhos usados pelo diagnóstico.
• pip — freeze: relatório de pacotes instalados.