Click
O Click constrói CLIs com decoradores. Ele lida com texto de ajuda, conversão de tipos, subcomandos e saída de terminal melhor do que o argparse puro.
Receita
import click
@click.command()
@click.option("--name", default="World", help="Quem saudar")
def hello(name):
click.echo(f"Hello, {name}!")
if __name__ == "__main__":
hello()Quando usar isso:
- Ferramentas CLI multi-comando
- Mensagens de ajuda e erro amigáveis ao usuário
- Necessidade de prompts, cores e barras de progresso
Exemplo Funcional
import click
@click.group()
@click.option("--verbose", "-v", is_flag=True)
@click.pass_context
def cli(ctx, verbose):
ctx.ensure_object(dict)
ctx.obj["verbose"] = verbose
@cli.command()
@click.argument("filename", type=click.Path(exists=True))
@click.option("--format", type=click.Choice(["json", "csv"]), default="json")
@click.pass_context
def convert(ctx, filename, format):
if ctx.obj["verbose"]:
click.echo(f"Convertendo {filename} para {format}", err=True)
# lógica de conversão
click.echo(f"Feito: {filename}")
@cli.command()
@click.option("--force", is_flag=True, help="Pular confirmação")
def clean(force):
if not force and not click.confirm("Deletar todos os arquivos temporários?"):
raise click.Abort()
click.echo("Limpo.")
if __name__ == "__main__":
cli()O que isso demonstra:
@click.group()para subcomandosclick.Path(exists=True)valida caminhos de arquivoclick.Choicerestringe valores de opçõesclick.confirmpara prompts interativoserr=Trueenvia saída detalhada para stderr
Mergulho Profundo
Click vs argparse
| Recurso | Click | argparse |
|---|---|---|
| Sintaxe | Decoradores | Imperativa |
| Formatação de ajuda | Rica | Básica |
| Teste | CliRunner | parse_args |
| Prompts | Embutido | Manual |
Armadilhas
- Não usar
click.echo- problemas de codificação no Windows. Correção: sempre useclick.echo, nãoprint. - Falta de
pass_context- opções pai indisponíveis. Correção:@click.pass_contextectx.obj. - Callback de comando não testável - apenas invocação da CLI. Correção: use
CliRunnerno pytest. - Muitas opções em um comando - inutilizável. Correção: dividir em subcomandos ou arquivo de configuração.
- Click sem ponto de entrada - usuários não podem instalar globalmente. Correção: registrar em
[project.scripts].
Alternativas
| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| Typer | Preferência por type hints | Sem tipagem no projeto |
| argparse | Zero dependências | Necessidade de CLI rica |
| cyclopts | Configuração com Dataclass | Equipe conhece Click |
FAQs
Click ou Typer?
Typer se você usa type hints em tudo. Click para mais controle e maturidade.
Como testar aplicativos Click?
from click.testing import CliRunner; runner = CliRunner(); runner.invoke(cli, ["convert", "f.txt"]).
Como adicionar completação de shell?
@click.group() + instalar completação: _MYAPP_COMPLETE=bash_source myapp.
Como lidar com exceções?
Deixe as exceções propagarem para obter tracebacks, ou capture e raise click.ClickException("msg") para erros limpos.
Múltiplos argumentos?
Múltiplos decoradores @click.argument() em ordem.
Valores padrão de variáveis de ambiente?
@click.option("--host", envvar="HOST", default="localhost").
Como mostrar uma barra de progresso?
with click.progressbar(items) as bar: ....
Click e async?
Use @click.command() com asyncio.run() dentro, ou o fork asyncclick.
Como versionar uma CLI?
Decorador @click.version_option().
Grupos aninhados?
Grupos podem conter grupos: @cli.group() dentro de outro grupo.
Relacionado
- Typer - CLI com type hints sobre Click
- argparse - alternativa da biblioteca padrão
- Saída Rica - formatação aprimorada
- Boas Práticas de CLI - diretrizes de design
Versões da Stack: 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+.