Pular para conteúdo

quantilica-cli

CLI unificada que serve como ponto de entrada único para todos os fetchers do Ecossistema Quantilica. Descobre fetchers instalados via entry point quantilica.fetchers e os monta como subcomandos diretos na raiz (quantilica <fonte>). Não tem dependência direta de nenhum fetcher — você instala apenas os pacotes que vai usar.

A arquitetura híbrida (argparse no fetcher + Typer no plugin) está descrita em detalhes em Arquitetura de CLI. Esta página foca em como usar o quantilica-cli no dia-a-dia.

Instalação

uv tool install quantilica-cli
# Ou via pip:
pip install quantilica-cli

Em seguida, instale as fontes de dados (fetchers) que quiser usar diretamente pela CLI:

quantilica install comex
quantilica install rtn
# ...

O quantilica-cli faz o download da distribuição do fetcher a partir do índice estático e o registra automaticamente no ambiente.

Uso

Gerenciamento de Fontes de Dados

  • Instalar uma fonte: 
    quantilica install <fonte>
  • Desinstalar uma fonte: 
    quantilica uninstall <fonte>
  • Listar fontes instaladas: 
    quantilica list-sources
  • Listar todas as fontes conhecidas no repositório remoto: 
    quantilica list-sources --remote
  • Diagnosticar e recuperar fontes em caso de ambiente recriado: 
    quantilica doctor

Executar um fetcher

quantilica <fonte> [opções...]

Cada <fonte> corresponde ao nome do entry point declarado pelo fetcher (ex.: comex, sidra, datasus, bcb-sgs, td, rtn, pdet, inmet). As opções e subcomandos disponíveis são definidos pelo próprio plugin Typer do fetcher — use quantilica <fonte> --help para vê-las.

Exemplos:

quantilica comex --help
quantilica comex sync 2023
quantilica sidra info 1737
quantilica bcb-sgs series sync 432

Versão

quantilica --version
quantilica -V

Como um fetcher é descoberto

Cada fetcher do ecossistema registra seu plugin Typer no pyproject.toml:

[project.entry-points."quantilica.fetchers"]
comex = "comex_fetcher.plugin:app"

Na inicialização, quantilica-cli itera os entry points do grupo quantilica.fetchers, importa o typer.Typer exportado por cada um e o monta diretamente na raiz como quantilica <nome>. Falhas de carga são reportadas como aviso (não derrubam a CLI).

Para registrar um novo fetcher como plugin:

  1. Crie src/<nome>_fetcher/plugin.py com um objeto app: typer.Typer.
  2. Declare o entry point no pyproject.toml do pacote.
  3. Reinstale (uv pip install -e .) — o plugin aparece automaticamente no próximo quantilica list-sources.

A diretriz é que typer e rich não apareçam em [project].dependencies do fetcher — são fornecidas pelo host quantilica-cli. Veja Arquitetura de CLI para a justificativa.

Saiba mais