Melhores Práticas de Scripting de Sistema
Scripts nos quais você pode confiar sem supervisão seguem as mesmas regras de operabilidade dos serviços de produção: modos de falha previsíveis, padrões seguros e logs que os operadores podem pesquisar às 3 da manhã.
Como Usar Esta Lista
- Aplique antes de agendar qualquer script no cron ou CI.
- Bloqueie a revisão se faltar
--dry-runpara ferramentas mutáveis. - Revise após qualquer incidente causado por reexecuções de automação ou trabalhos sobrepostos.
A - Estrutura e CLI
- Use
if __name__ == "__main__"e uma funçãomain() -> int. Mantém os módulos importáveis e testáveis. - Analise argumentos com argparse ou typer. Documente flags em
--helpe no README. - Suporte a
--dry-runpara ações destrutivas. Imprima as mudanças pretendidas sem efeitos colaterais. - Reserve stdout para saída de máquina; registre para humanos em stderr. Permite o encadeamento limpo de linhas JSON.
- Retorne códigos de saída documentados. 0 ok, 2 uso, 1 falha - corresponda às convenções da organização.
B - Arquivos e Dados
- Use pathlib para todas as operações de caminho. Evite junções de caminhos de string.
- Especifique
encoding="utf-8"em arquivos de texto. Evite surpresas com padrões de plataforma. - Escreva saídas atomicamente (temp + replace). Leitores nunca veem arquivos parcialmente escritos.
- Valide entradas antes da mutação. Falhe rapidamente em diretórios vazios, variáveis de ambiente ausentes, flags incorretas.
- Torne as reexecuções idempotentes. Sobreposição segura do cron ou comportamento explícito de flock/skip.
C - Processos e Rede
- Chame subprocessos com listas de argv, não strings de shell. Elimine injeção, a menos que seja uma exceção documentada.
- Defina timeouts de subprocesso e HTTP. Trabalhos travados não devem bloquear o cron para sempre.
- Tente novamente erros transitórios com um limite de backoff. Registre a falha final com contexto.
- Nunca registre segredos, tokens ou URLs pré-assinados. Redija cabeçalhos de Autorização.
- Verifique as assinaturas de webhook antes de processar o corpo. Rejeite eventos de entrada não assinados.
D - Agendamento e Operações
- Use caminhos absolutos para o python do venv no crontab. Inclua
cdpara a raiz do projeto. - Evite execuções sobrepostas com um bloqueio de arquivo ou distribuído. Saia com 0 ao pular uma instância duplicada, se apropriado.
- Emita logs estruturados (JSON) para scripts de produção. Inclua ação, caminho, duração, ID de correlação.
- Monitore o heartbeat de último sucesso externamente. Detecte falhas silenciosas do cron.
- Versionar scripts no git com CI executando ruff/pytest. O mesmo portão de qualidade do código da aplicação.
E - Remoto e Escala
- Prefira Ansible em vez de loops SSH ad-hoc para frotas. Use scripts SSH apenas para emergências.
- Rejeite chaves de host SSH desconhecidas em automação.
known_hostsgerenciados ou certificados. - Limite operações remotas paralelas. Evite atingir limites de taxa e bloqueios.
- Transmita arquivos de log grandes linha por linha. Não leia arquivos de vários GB para a memória.
- Promova scripts estáveis para CLIs empacotadas. Pontos de entrada
pyproject.tomlquando o escopo aumenta.
FAQs
Por que o dry-run é obrigatório?
A primeira execução em produção sem prévia causa exclusões irreversíveis - o dry-run é o seguro mais barato.
Posso usar print em scripts?
Para ferramentas locais rápidas, sim; scripts de produção agendados devem usar logging com níveis.
Como escolho entre argparse e typer?
argparse para scripts cron sem dependências; typer ao construir ferramentas de operador com múltiplos comandos.
E sobre arquivos de configuração?
YAML/TOML no git para não-segredos; variáveis de ambiente para segredos; CLI substitui em caso de conflito.
Como documento scripts para plantão?
Runbook com comandos de exemplo, códigos de saída, tempo de execução esperado e etapas de rollback.
Scripts devem chamar APIs da AWS?
Sim, com sessão boto3 reutilizada, retentativas e função de menor privilégio - veja a seção Cloud SDK.
Como testar scripts de cron?
pytest main() com tmp_path; teste de integração em staging com dry-run e depois ao vivo em dados de amostra.
Quando migrar para Airflow/Prefect?
Quando dependências, SLAs e observabilidade excederem um arquivo e a matriz de cron se tornar insustentável.
Como lidar com fusos horários?
Armazene UTC em logs e nomes de arquivos; documente o cron em horário local apenas quando o negócio exigir.
Qual é o maior antipadrão de scripting?
Sucesso silencioso em falha parcial - sempre agregue erros e saia com código não-zero quando algo falhar.
Relacionados
- Scripts Robustos - padrão completo de operabilidade
- Noções Básicas de Scripting - pontos de entrada e CLI
- Agendamento e Cron - higiene do cron
- subprocess e Interoperabilidade Shell - execução segura de comandos
- Melhores Práticas de SDK de Nuvem - AWS a partir de scripts
Versões de Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.