Ao criar ferramentas de linha de comando, uma mensagem de erro clara pode ser a diferença entre um usuário corrigir o problema em segundos ou abandonar o programa. O recurso suggest_on_error do módulo argparse melhora exatamente esse ponto: quando alguém digita uma opção ou escolha incorreta, o parser pode sugerir automaticamente o valor mais provável. Neste guia, você verá como usar esse comportamento, quando ele realmente ajuda, quais são seus limites e como combiná-lo com boas práticas de design de CLI.
O que é suggest_on_error
argparse é o módulo padrão do Python para interpretar argumentos de linha de comando. Normalmente, quando um usuário informa uma escolha inválida, o parser mostra apenas que o valor não pertence ao conjunto permitido. Com suggest_on_error=True, o parser tenta identificar erros de digitação e acrescenta uma sugestão útil à mensagem. Isso é especialmente interessante em comandos com choices, subcomandos ou opções textuais com nomes parecidos.
import argparse
parser = argparse.ArgumentParser(suggest_on_error=True)
parser.add_argument("action", choices=["start", "stop", "restart"])
args = parser.parse_args()
print(args.action)
Ao executar o programa com restar, o usuário recebe uma indicação próxima de restart. A ideia é semelhante aos sistemas de correção usados por shells, gerenciadores de pacotes e ferramentas modernas de desenvolvimento.
Por que mensagens de erro melhores importam
Uma CLI costuma ser usada em automações, servidores, pipelines e ambientes onde não existe interface gráfica. Por isso, a mensagem de erro é parte da própria experiência do produto. Um texto genérico força o usuário a abrir a documentação, repetir o comando ou inspecionar o código. Uma sugestão contextual reduz esse atrito e também diminui chamados de suporte.
Esse princípio complementa outras boas práticas de Python. Ao organizar aplicações maiores, vale conhecer contextlib.ExitStack no Python para gerenciar recursos, typing.override no Python para contratos mais seguros, string.Template no Python para mensagens configuráveis e TopologicalSorter no Python para fluxos dependentes.
Compatibilidade entre versões
suggest_on_error é um recurso recente. Se sua aplicação precisa rodar em versões anteriores do Python, não passe o argumento diretamente sem verificar a versão, pois isso pode gerar TypeError. Uma alternativa compatível é criar o parser normalmente e atribuir o atributo depois, quando ele existir.
import argparse
parser = argparse.ArgumentParser()
if hasattr(parser, "suggest_on_error"):
parser.suggest_on_error = True
Essa estratégia é útil para bibliotecas e CLIs distribuídas para ambientes variados. Em aplicações internas, onde a versão do Python é controlada, você pode definir o argumento diretamente e simplificar o código.
Uso com choices
O cenário mais direto envolve choices. Imagine uma ferramenta de implantação:
parser = argparse.ArgumentParser(suggest_on_error=True)
parser.add_argument(
"environment",
choices=["development", "staging", "production"]
)
Se alguém digitar prodution, a sugestão pode apontar para production. Isso funciona melhor quando as escolhas são strings e possuem distância textual pequena. Valores numéricos, objetos complexos ou palavras muito diferentes não oferecem a mesma qualidade de recomendação.
Subcomandos e estrutura da CLI
Em ferramentas maiores, subcomandos tornam a interface mais organizada. Um programa pode oferecer deploy, rollback, status e logs. Mesmo com sugestões, mantenha nomes curtos, consistentes e previsíveis. Evite misturar verbos, substantivos e abreviações sem padrão.
parser = argparse.ArgumentParser(suggest_on_error=True)
subparsers = parser.add_subparsers(dest="command", required=True)
subparsers.add_parser("deploy")
subparsers.add_parser("rollback")
subparsers.add_parser("status")
Uma boa taxonomia de comandos continua sendo responsabilidade do desenvolvedor. A sugestão melhora erros pequenos, mas não corrige uma arquitetura confusa.
Mensagens personalizadas ainda são importantes
Você pode personalizar descrições, epílogos e textos de ajuda. Use help em cada argumento e explique formatos esperados. Para validações específicas, crie funções de tipo que levantem argparse.ArgumentTypeError.
from pathlib import Path
import argparse
def existing_file(value: str) -> Path:
path = Path(value)
if not path.is_file():
raise argparse.ArgumentTypeError(f"Arquivo não encontrado: {value}")
return path
parser = argparse.ArgumentParser(suggest_on_error=True)
parser.add_argument("--config", type=existing_file)
Nesse exemplo, suggest_on_error não substitui a validação. Ele atua em erros textuais que o parser consegue comparar, enquanto a função personalizada verifica uma regra real do domínio.
Testando as sugestões
Mensagens de erro fazem parte do comportamento público da aplicação e merecem testes. Com pytest, você pode executar o parser com argumentos inválidos, capturar SystemExit e inspecionar a saída de erro. Evite depender de toda a frase se ela puder variar entre versões; valide os trechos essenciais.
import pytest
def test_invalid_choice(parser, capsys):
with pytest.raises(SystemExit):
parser.parse_args(["prodution"])
captured = capsys.readouterr()
assert "production" in captured.err
Também teste o comportamento sem suporte ao recurso, caso sua biblioteca mantenha compatibilidade com versões antigas.
Cuidados com segurança
A sugestão é apenas uma ajuda de interface. Não use o valor sugerido automaticamente sem confirmação. O parser deve continuar rejeitando a entrada inválida. Isso é importante em comandos destrutivos, como remoção de arquivos, migrações, alterações de infraestrutura ou operações financeiras.
Para ações sensíveis, adicione confirmações explícitas, modos de simulação e logs. Nunca transforme uma aproximação textual em execução automática. A documentação oficial do argparse explica o comportamento do parser, enquanto o guia de novidades do Python ajuda a acompanhar recursos recentes e requisitos de versão.
Quando ativar
Ative suggest_on_error em CLIs com escolhas textuais, vários subcomandos ou público menos técnico. O ganho é maior quando os valores permitidos são palavras legíveis e relativamente distintas. Em interfaces estritamente internas ou parsers que recebem apenas números, IDs e caminhos, o benefício pode ser pequeno.
Boas práticas finais
Combine sugestões com nomes consistentes, ajuda objetiva, exemplos reais, códigos de saída corretos e validações específicas. Mantenha compatibilidade consciente entre versões e registre a versão mínima do Python no projeto. Para bibliotecas, prefira detecção de capacidade com hasattr; para aplicações controladas, configure o recurso diretamente.
argparse suggest_on_error não muda a lógica central do seu programa, mas melhora uma área frequentemente negligenciada: a recuperação após um erro humano. Ao orientar o usuário sem aceitar entradas incorretas, a CLI se torna mais amigável, previsível e profissional.
