Desenhar uma ferramenta de linha de comandos em Python: argparse, main() e códigos de saída

Objetivo

Construir uma ferramenta de linha de comandos que scripts de shell, jobs de CI e agentes consigam controlar: argumentos previsíveis, um texto de ajuda que serve de documentação, códigos de saída estruturados e streams limpos.

Pré-requisitos

Um pacote com um pyproject.toml (ver o artigo sobre empacotamento) cuja lógica resida em funções importáveis, separadas do tratamento dos argumentos.

Passos

1. Escreva def main(argv: list[str] | None = None) -> int que construa o parser, analise argv (recorrendo a sys.argv[1:] por defeito) e devolva um código de saída. Registe-a como [project.scripts] tool = "pkg.cli:main" e acrescente if __name__ == "__main__": sys.exit(main()). Os testes passam então a chamar main(["--flag", "x"]) e a verificar o valor devolvido e o output capturado.
2. Construa o parser com prog, description e um epilog com exemplos. Use conversores type= (int, pathlib.Path, ou uma função que lance ArgumentTypeError) para que valores inválidos sejam reportados como erros de utilização, 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 do sys.exit: os programas Unix usam geralmente 2 para erros de sintaxe na linha de comandos e 1 para todos os outros erros, sendo 0 sucesso. O argparse já termina com o estado 2 perante argumentos inválidos. Adote outros códigos de sysexits.h (EX_USAGE 64, EX_NOINPUT 66, EX_UNAVAILABLE 69, EX_TEMPFAIL 75) apenas se --help os documentar.
4. Escreva os resultados em stdout e os diagnósticos em stderr. Disponibilize --json quando outros programas consomem o output, e --verbose/--quiet que ajustem o nível de logging, em vez de espalhar chamadas a print.
5. Capture as falhas esperadas (FileNotFoundError, erros de ligação, exceções de domínio) em main, imprima uma linha em stderr e devolva o código documentado; deixe propagar as exceções inesperadas, para que o traceback e o código de saída 1 sejam preservados.
6. Trate KeyboardInterrupt fazendo a limpeza necessária e devolvendo 130, em conformidade com a convenção da shell de 128 mais o número do sinal, e absorva BrokenPipeError em stdout para que tool | head termine sem alarido.
7. Mantenha a ajuda honesta: metavar para marcadores de posição legíveis, ArgumentDefaultsHelpFormatter para que os valores por omissão apareçam, e um teste que confirme que --help termina com 0.

Resultado esperado

tool --help documenta toda a interface; tool --bad; echo $? imprime 2; um problema de entrada imprime uma linha em stderr e um código documentado; quem chama a ferramenta consegue ramificar com base no código, sem analisar texto.

Limites e base de verificação

A documentação do sys.exit observa que a maioria dos sistemas exige códigos de saída no intervalo de 0 a 127; valores acima disso colidem com a codificação de sinais da shell. exit_on_error=False faz com que o parser lance ArgumentError em vez de terminar o processo, o que é adequado para incorporação (embedding), mas exige tratamento de erros próprio. As convenções seguem a documentação citada; não se reivindica nenhuma medição de usabilidade.

Encerramento após Ctrl-C

Uma shell decide se uma interrupção também deve parar o script que a envolve verificando se o processo filho morreu por causa de SIGINT, e não lendo o código de saída. Por isso, uma ferramenta que captura KeyboardInterrupt e devolve 130 parece uma saída normal, e for f in *; do tool "$f"; done continua para o ficheiro seguinte depois de cada Ctrl-C. Faça a limpeza necessária e depois termine o processo da mesma forma que uma interrupção não tratada terminaria (o próprio Python já faz isto sozinho desde a versão 3.8):

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

$? continua a mostrar 130, e um processo pai que aguarda (wait) pelo processo vê uma morte por sinal. Reserve return 130 para chamadores que se sabe lerem apenas códigos.