Diferença Entre Entradas E Bandeiras

Entendendo a diferença prática entre entradas e bandeiras no dia a dia

Vou direto ao ponto porque já vi muita gente confundir os dois conceitos e perder horas debugando script que não funciona como deveria. Entrada (input/argumento posicional) é algo que você passa para o programa e que ele espera receber com um valor. Bandeira (flag/option) é um modificador booleano ou chave-valor que altera o comportamento do programa sem ser obrigatório. A distinção parece óbvia na teoria, mas na hora de construir uma CLI ou interpretar argumentos de linha de comando, a coisa se complica. No Python, com o argparse, entrada se define com add_argument sem o prefixo de traço duplo, e bandeira recebe esse prefixo. Mas isso é só a superfície. O problema real aparece quando você precisa lidar com argumentos opcionais que se comportam como ambos, ou quando a mesma flag precisa aceitar valor opcional.

Eu estava fazendo um script de deploy automatizado há uns meses, um daqueles que sobe containers Docker e executa migrações. Usei uma bandeira --env que podia receber um valor (staging, production) ou ser omitida para usar o padrão. Aí tive um comportamento curioso: quando passava --env sozinho, sem valor, o parser não falhava, mas atribuía o valor True, quebrando toda a lógica de seleção de ambiente. A solução foi simples na prática, mas custou três horas de teste. Mudei para --env com nargs='?' e defini const='production', mas também precisei validar manualmente se o usuário tinha passado algo ou se era apenas a presença da flag. O argparse não distingue bem entre "flag presente sem valor" e "flag ausente" nesse cenário. Outro detalhe que ninguém menciona: bandeiras booleanas (como --verbose) têm um comportamento que varia completamente entre bibliotecas. No argparse, ao marcar action='store_true', o valor padrão já é False. Mas se você usar action='store_false', o valor padrão vira code=True. Parece besteira, mas em scripts grandes com dezenas de flags, é fácil esquecer e acabar com uma lógica invertida que só aparece em produção. Tem também a questão das bandeiras que aceitam múltiplos valores. --tag com action='append' permite que o usuário passe a mesma flag várias vezes e todas sejam acumuladas em uma lista. Isso resolve um problema comum de forma elegante, mas gera outra armadilha: o valor padrão vira None, não uma lista vazia. Então todo código que consome essa flag precisa verificar se é None antes de iterar. Eu costumo usar default=[] junto com action='append' exatamente para evitar esse erro.

Como implementar corretamente

A estrutura básica de separação fica assim: Para entradas posicionais, defina o nome sem hífenes e trate como obrigatório quando necessário. Para bandeiras, use o prefixo -- e decida desde o início se ela é booleana, se aceita valor, ou se é opcional. A decisão mais importante é: essa coisa é necessária para o programa rodar ou é apenas um controle de comportamento? Se for necessária, entra como entrada. Se for um controle, vai para bandeira. Não tente forçar um argumento obrigatório como bandeira só porque parece mais bonito na ajuda, porque depois você vai ter que justificar pro usuário que precisa passar uma flag pra script funcionar, e ninguém vai gostar disso.

Uma coisa que aprendi na marra: sempre teste seus parsers com entradas inválidas antes de distribuir. Passar uma flag onde se espera um valor, ou vice-versa, gera erros que variam conforme a versão da biblioteca. No argparse do Python 3.9 versus 3.12, algumas mensagens de erro mudaram e o comportamento de argumentos ambíguos também não é idêntico. Se você está começando agora, recomendo usar typer ou click em vez do argparse puro. A curva de aprendizado é menor, a validação é mais rigorosa por padrão, e a diferença entre entrada e bandeira fica muito mais explícita na assinatura da função. No typer, por exemplo, um parâmetro normal é entrada, e um parâmetro com --flag é bandeira. O tipo Python já atua como validador. Leva cerca de dez minutos pra configurar algo que no argparse levaria cinquenta.

Erros comuns que todo mundo comete

O mais frequente é tratar tudo como bandeira, mesmo quando o dado é um valor obrigatório. O resultado é uma CLI feia e confusa onde o usuário precisa decorar flags pra saber quais são opcionais e quais não são. Outro erro é usar bandenas para dados que mudam a cada execução, como nomes de arquivo ou URLs. Bandeira existe pra configuração, não pra dados. Também vejo muita gente usando bandeiras booleanas quando deveria usar um argumento de escolha. --modo-producao é uma bandeira booleana ruim. --modo producao é um argumento com choices, que é mais claro, mais fácil de manter e evita o caso em que o usuário esquece a flag e o script roda em modo errado sem avisar. A parte mais chata é a documentação. Quando a diferença entre entrada e bandeira fica clara no código, ela some na hora de escrever a help text. Eu passo sempre um help explicativo em cada definição, mesmo que pareça óbvio no momento. Três meses depois, quando você volta no código, a ajuda escrita é o que vai te dizer o que cada coisa faz.

Cenários onde a separação não funciona bem

Em algumas situações, a distinção entre entrada e bandeira se torna artificial. Ferramentas como o rsync usam hífen duplo só pra separar opções de caminhos, mas internamente trata tudo de forma quase igual. Se o seu programa precisa de uma interface parecida, force categorias de forma rígida e você vai se arrepender. Outro caso limite: quando uma bandeira precisa existir apenas para disparar uma ação secundária, sem valor próprio. Nesse ponto, muitos desenvolvedores chegam no action='store_true' e pronto. Mas se essa ação secundaria depender de outros argumentos, a validação cross-field vai aparecer na sua cara. O argparse não valida dependências entre flags e entradas nativamente. Você precisa fazer essa validação manualmente no handler pós-parse. Na prática, eu resolvi isso criando uma função de validação separada que roda depois do parse, verifica combinações impossíveis e levanta exceções com mensagens claras. Custa cerca de duas horas a mais de desenvolvimento, mas economiza dias de suporte depois.

Resumo rápido, sem enrolação

Entrada é dado obrigatório ou semiobrigatório que o programa precisa para funcionar. Bandeira é modificador de comportamento que o programa pode ou não aceitar. Separe esses dois conceitos na hora de projetar sua interface, documente cada um com help específico, e valide combinações depois do parse. Se quiser algo mais prático desde o começo, fuja do argparse puro e vá de typer ou click. O tempo que você economiza na implementação compensa a pequena curva de adaptação.