Como projetar uma ferramenta de linha de comando em Python: argparse, main() e códigos de saída

Objetivo

Criar uma ferramenta de linha de comando que scripts de shell, jobs de CI e agentes consigam usar: argumentos previsíveis, texto de ajuda que serve como documentação, códigos de saída estruturados e fluxos (streams) limpos.

Pré-requisitos

Um pacote com pyproject.toml (veja o artigo sobre empacotamento) cuja lógica esteja em funções importáveis, separada do tratamento de argumentos.

Passos

1. Escreva def main(argv: list[str] | None = None) -> int, que monta o parser, analisa argv (usando sys.argv[1:] como alternativa) e retorna um código de saída. Registre-a como [project.scripts] tool = "pkg.cli:main" e adicione if __name__ == "__main__": sys.exit(main()). Assim, os testes podem chamar main(["--flag", "x"]) e verificar o valor retornado e a saída capturada.
2. Monte o parser com prog, description e um epilog com exemplos. Use conversores em type= (int, pathlib.Path ou uma função que lance ArgumentTypeError) para que valores inválidos sejam reportados como erros de uso, choices= para conjuntos fechados e add_subparsers(dest="command", required=True) para ferramentas com vários comandos.
3. Siga a convenção descrita na documentação de sys.exit: programas Unix geralmente usam 2 para erros de sintaxe na linha de comando e 1 para todos os outros erros, e 0 significa sucesso. O argparse já encerra com status 2 diante de argumentos inválidos. Adote outros códigos de sysexits.h (EX_USAGE 64, EX_NOINPUT 66, EX_UNAVAILABLE 69, EX_TEMPFAIL 75) somente se --help os documentar.
4. Escreva os resultados em stdout e os diagnósticos em stderr. Ofereça --json quando outros programas consumirem a saída, e --verbose/--quiet que definam o nível de logging, em vez de espalhar chamadas a print.
5. Capture as falhas esperadas (FileNotFoundError, erros de conexão, exceções de domínio) em main, imprima uma linha em stderr e retorne o código documentado; deixe as exceções inesperadas se propagarem, para preservar o traceback e o código de saída 1.
6. Trate KeyboardInterrupt fazendo a limpeza e retornando 130, conforme a convenção do shell de 128 mais o número do sinal, e ignore BrokenPipeError em stdout para que tool | head termine sem ruído.
7. Mantenha a ajuda fiel à realidade: use metavar para placeholders legíveis, ArgumentDefaultsHelpFormatter para que os valores padrão apareçam, e um teste que verifique que --help encerra com 0.

Resultado esperado

tool --help documenta toda a interface; tool --bad; echo $? imprime 2; um problema na entrada gera uma linha em stderr e um código documentado; quem chama a ferramenta pode decidir o fluxo pelo código, sem precisar interpretar texto.

Limites e base de verificação

A documentação de sys.exit observa que a maioria dos sistemas exige códigos de saída no intervalo de 0 a 127; valores maiores colidem com a codificação de sinais do shell. exit_on_error=False faz o parser lançar ArgumentError em vez de encerrar o programa, o que serve para uso embutido, mas exige tratamento de erros próprio. As convenções seguem a documentação citada; não se afirma nenhuma medição de usabilidade.

Encerrando após Ctrl-C

O shell decide se uma interrupção deve parar também o script que o contém verificando se o processo filho morreu por SIGINT, e não lendo o código de saída. Uma ferramenta que captura KeyboardInterrupt e retorna 130 parece, portanto, ter terminado normalmente, e for f in *; do tool "$f"; done segue para o próximo arquivo após cada Ctrl-C. Faça a limpeza e depois encerre o processo da mesma forma que uma interrupção não tratada faria (o Python faz isso sozinho desde a versão 3.8):

except KeyboardInterrupt:
    cleanup()
    signal.signal(signal.SIGINT, signal.SIG_DFL)
    os.kill(os.getpid(), signal.SIGINT)

$? continua valendo 130, e um processo pai que espera pelo filho vê uma morte por sinal. Reserve return 130 para chamadores que, sabidamente, leem apenas códigos de saída.