argparse

argparse é o analisador de CLI da biblioteca padrão do Python. Ele gera --help, valida tipos e suporta subcomandos sem dependências de terceiros.

Receita

import argparse
 
def main():
    parser = argparse.ArgumentParser(prog="invoice", description="Gerenciar faturas")
    parser.add_argument("--format", choices=["json", "csv"], default="json")
    parser.add_argument("id", type=int, nargs="?", help="ID da fatura")
    args = parser.parse_args()
    print(args)
 
if __name__ == "__main__":
    main()

Quando usar isso:

• CLI sem dependências externas
• Scripts que precisam de --help e validação de tipo
• Ferramentas onde apenas a biblioteca padrão é um requisito

Exemplo de Trabalho

import argparse
import sys
 
def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        prog="deploy",
        description="Implantar aplicação em ambientes",
    )
    parser.add_argument("--verbose", "-v", action="count", default=0)
    sub = parser.add_subparsers(dest="env", required=True)
 
    for name in ("staging", "production"):
        p = sub.add_parser(name, help=f"Implantar em {name}")
        p.add_argument("--dry-run", action="store_true")
        p.add_argument("--tag", required=True, help="Tag da imagem Docker")
    return parser
 
def main(argv: list[str] | None = None) -> int:
    args = build_parser().parse_args(argv)
    if args.verbose:
        print(f"Implantando {args.tag} em {args.env}", file=sys.stderr)
    if args.dry_run:
        print("Simulação - nenhuma alteração feita")
        return 0
    # lógica de implantação aqui
    return 0
 
if __name__ == "__main__":
    raise SystemExit(main())

O que isso demonstra:

• Subcomandos para deploy staging / deploy production
• action="count" para verbosidade -v, -vv
• parse_args(argv) permite testes sem subprocessos
• raise SystemExit(main()) para códigos de saída corretos

Mergulho Profundo

Argumentos Comuns

Armadilhas

• Esquecer required=True em subcomandos - nenhum comando é executado. Correção: required=True (Python 3.7+).
• Não testável - apenas parse_args() sem argv. Correção: passar argv list em testes.
• Texto de ajuda como reflexão tardia - usuários confusos. Correção: help= em cada argumento.
• Imprimir segredos em padrões argparse - visível em --help. Correção: carregar segredos do ambiente em tempo de execução.
• argparse para comandos aninhados complexos - verboso. Correção: considerar Click ou Typer com 5+ subcomandos.

Alternativas

FAQs

Relacionado

• Fundamentos de CLI - Fundamentos de CLI
• Click - alternativa com decoradores
• Configuração e Ambiente - camadas de configuração
• Melhores Práticas de CLI - regras de design

Versões da Pilha: Esta página foi escrita para Python 3.14.0, 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+.