Typer

Typer gera CLIs a partir de type hints do Python. Construído sobre Click, ele reduz o código repetitivo mantendo o ecossistema do Click.

Receita

import typer
 
app = typer.Typer()
 
@app.command()
def greet(name: str, loud: bool = False):
    msg = f"Hello, {name}"
    typer.echo(msg.upper() if loud else msg)
 
if __name__ == "__main__":
    app()

Quando usar isso:

O projeto já usa type hints em todo o código
Prototipagem rápida de CLI a partir de assinaturas de função
Poder do Click com menos código repetitivo de decoradores

Exemplo de Trabalho

import typer
from pathlib import Path
from typing import Optional
from enum import Enum
 
app = typer.Typer(help="CLI de gerenciamento de faturas")
 
class OutputFormat(str, Enum):
    json = "json"
    csv = "csv"
 
@app.command()
def export(
    invoice_id: int = typer.Argument(..., help="ID da fatura"),
    output: Path = typer.Option("out.json", help="Arquivo de saída"),
    format: OutputFormat = OutputFormat.json,
    verbose: bool = typer.Option(False, "--verbose", "-v"),
):
    if verbose:
        typer.echo(f"Exportando fatura {invoice_id} como {format.value}", err=True)
    # lógica de exportação
    typer.echo(f"Escrito em {output}")
 
@app.command()
def list(limit: int = typer.Option(10, min=1, max=100)):
    typer.echo(f"Listando {limit} faturas")
 
if __name__ == "__main__":
    app()

O que isso demonstra:

Type hints direcionam os tipos de argumento e o texto de ajuda
Enum se torna Choice automaticamente
Path valida caminhos de arquivo
typer.Option e typer.Argument para metadados

Mergulho Profundo

Mapeamento de Tipos

Type hint	Comportamento da CLI
`str`	Argumento de string
`int`	Inteiro com validação
`bool`	Flag (padrão False)
`Optional[str]`	Opção opcional
`Enum`	Escolha a partir dos valores do enum
`Path`	Caminho de arquivo/diretório

Armadilhas

Type hints ausentes - Typer não consegue inferir argumentos. Correção: anote cada parâmetro.
Validação complexa - hints não são suficientes. Correção: use modelos Pydantic ou validadores de callback.
Confusão posicional de bool - bool como posicional é complicado. Correção: use typer.Option para flags.
Não instalar typer[all] - faltam extras de conclusão de shell. Correção: uv add "typer[all]" para desenvolvimento.
Quebras de compatibilidade entre versões do Typer - fixe a versão. Correção: bloqueie em pyproject.toml.

Alternativas

Alternativa	Use Quando	Não Use Quando
Click	Mais controle sobre o parsing	Type hints atendem às suas necessidades
argparse	Zero dependências	CLI orientada a tipos desejada
cyclopts	Configuração pesada em dataclasses	Comandos de função simples

FAQs

Typer ou Click?

Typer para projetos com type hints. Click para controle granular.

Como testar Typer?

from typer.testing import CliRunner (mesmo padrão do Click).

Subcomandos?

app = typer.Typer() + sub = typer.Typer() + app.add_typer(sub, name="db").

Integração com Pydantic?

Use modelos Pydantic como tipos para configuração estruturada (Typer 0.12+).

Como adicionar ajuda?

typer.Argument(help="...") ou docstrings nos comandos.

Conclusão de shell?

typer[all] inclui conclusão. Instale via --install-completion.

Comandos assíncronos?

Use async def com suporte assíncrono do typer 0.9+ ou envolva com asyncio.run.

Múltiplos comandos em um app?

Múltiplas funções decoradas com @app.command().

Como lidar com arquivos de configuração?

Carregue a configuração separadamente; Typer lida com argumentos de CLI. Considere pydantic-settings.

Typer está pronto para produção?

Sim. Potencializa a CLI do FastAPI. Construído sobre a base estável do Click.

Relacionado

Click - framework subjacente
argparse - opção stdlib
Configuração e Ambiente - configurações
Melhores Práticas de CLI - regras 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+.

Typer

Typer gera CLIs a partir de type hints do Python. Construído sobre Click, ele reduz o código repetitivo mantendo o ecossistema do Click.

Receita

import typer
 
app = typer.Typer()
 
@app.command()
def greet(name: str, loud: bool = False):
    msg = f"Hello, {name}"
    typer.echo(msg.upper() if loud else msg)
 
if __name__ == "__main__":
    app()

Quando usar isso:

O projeto já usa type hints em todo o código
Prototipagem rápida de CLI a partir de assinaturas de função
Poder do Click com menos código repetitivo de decoradores

Exemplo de Trabalho

import typer
from pathlib import Path
from typing import Optional
from enum import Enum
 
app = typer.Typer(help="CLI de gerenciamento de faturas")
 
class OutputFormat(str, Enum):
    json = "json"
    csv = "csv"
 
@app.command()
def export(
    invoice_id: int = typer.Argument(..., help="ID da fatura"),
    output: Path = typer.Option("out.json", help="Arquivo de saída"),
    format: OutputFormat = OutputFormat.json,
    verbose: bool = typer.Option(False, "--verbose", "-v"),
):
    if verbose:
        typer.echo(f"Exportando fatura {invoice_id} como {format.value}", err=True)
    # lógica de exportação
    typer.echo(f"Escrito em {output}")
 
@app.command()
def list(limit: int = typer.Option(10, min=1, max=100)):
    typer.echo(f"Listando {limit} faturas")
 
if __name__ == "__main__":
    app()

O que isso demonstra:

Type hints direcionam os tipos de argumento e o texto de ajuda
Enum se torna Choice automaticamente
Path valida caminhos de arquivo
typer.Option e typer.Argument para metadados

Mergulho Profundo

Mapeamento de Tipos

Type hint	Comportamento da CLI
`str`	Argumento de string
`int`	Inteiro com validação
`bool`	Flag (padrão False)
`Optional[str]`	Opção opcional
`Enum`	Escolha a partir dos valores do enum
`Path`	Caminho de arquivo/diretório

Armadilhas

Type hints ausentes - Typer não consegue inferir argumentos. Correção: anote cada parâmetro.
Validação complexa - hints não são suficientes. Correção: use modelos Pydantic ou validadores de callback.
Confusão posicional de bool - bool como posicional é complicado. Correção: use typer.Option para flags.
Não instalar typer[all] - faltam extras de conclusão de shell. Correção: uv add "typer[all]" para desenvolvimento.
Quebras de compatibilidade entre versões do Typer - fixe a versão. Correção: bloqueie em pyproject.toml.

Alternativas

Alternativa	Use Quando	Não Use Quando
Click	Mais controle sobre o parsing	Type hints atendem às suas necessidades
argparse	Zero dependências	CLI orientada a tipos desejada
cyclopts	Configuração pesada em dataclasses	Comandos de função simples

FAQs

Typer ou Click?

Typer para projetos com type hints. Click para controle granular.

Como testar Typer?

from typer.testing import CliRunner (mesmo padrão do Click).

Subcomandos?

app = typer.Typer() + sub = typer.Typer() + app.add_typer(sub, name="db").

Integração com Pydantic?

Use modelos Pydantic como tipos para configuração estruturada (Typer 0.12+).

Como adicionar ajuda?

typer.Argument(help="...") ou docstrings nos comandos.

Conclusão de shell?

typer[all] inclui conclusão. Instale via --install-completion.

Comandos assíncronos?

Use async def com suporte assíncrono do typer 0.9+ ou envolva com asyncio.run.

Múltiplos comandos em um app?

Múltiplas funções decoradas com @app.command().

Como lidar com arquivos de configuração?

Carregue a configuração separadamente; Typer lida com argumentos de CLI. Considere pydantic-settings.

Typer está pronto para produção?

Sim. Potencializa a CLI do FastAPI. Construído sobre a base estável do Click.

Relacionado

Click - framework subjacente
argparse - opção stdlib
Configuração e Ambiente - configurações
Melhores Práticas de CLI - regras 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+.

Typer

Buscar na documentação

Typer