Padronização de CLI para Fetchers¶
Esta é a referência do contribuidor: como implementar convenções de CLI e armazenamento num fetcher. Para entender como os arquivos são organizados como usuário final, veja Convenções de Armazenamento.
Para o contexto conceitual por trás destas regras, veja Arquitetura de CLI (os dois níveis) e o padrão UX de CLI: progresso vs. logs.
Este documento é o guia normativo para a construção de interfaces de linha de comando nos pacotes fetcher do ecossistema Quantilica. Cobre os dois níveis de interface que cada fetcher implementa: o wrapper da CLI standalone (cli.py) e o plugin para o hub unificado (plugin.py, Typer + Rich). A estrutura canônica de cli.py segue o ADR 2026-10-08-fetcher-cli-wrapper-e-canal-de-distribuicao: para fetchers baseados no FetcherApp, cli.py é apenas um wrapper fino do app Typer do plugin.py; argparse completo (§2) fica restrito a fetchers com comandos customizados fora do FetcherApp (hoje, ibge-sidra-fetcher).
Seguir este guia garante comportamento consistente entre fetchers, integração correta com quantilica-cli e UX homogênea para o usuário final.
1. Visão geral da arquitetura de dois níveis¶
Todo fetcher Quantilica expõe dois pontos de entrada CLI com responsabilidades distintas:
<pacote>/
├── src/<pacote>/
│ ├── cli.py ← Wrapper fino do Typer do plugin (padrão) ou argparse (fetcher customizado)
│ └── plugin.py ← Plugin para quantilica-cli (Typer + Rich)
| Dimensão | cli.py |
plugin.py |
|---|---|---|
| Framework | Wrapper do app Typer do plugin.py (padrão) ou argparse (fetcher customizado) |
typer + rich |
| Dependências extras | Nenhuma | typer, rich (fornecidos pelo host) |
| Ativado por | <pacote>-fetcher [comando] |
quantilica <fonte> [comando] |
| Propósito | Exposição como script, automação | Experiência interativa, UX rica |
| Registro | [project.scripts] |
[project.entry-points."quantilica.fetchers"] |
| Colorido / progresso | Rich (via plugin.py, no wrapper); tqdm: opcional em fetcher customizado (via core) |
Sim |
Import protegido é obrigatório em todo cli.py wrapper de FetcherApp: try/except ImportError que imprime instale via "quantilica install <fonte>" e encerra com código 1 — nunca ModuleNotFoundError cru. Referência canônica: bcb-sgs-fetcher/src/bcb_sgs_fetcher/cli.py.
O quantilica-cli descobre plugins dinamicamente via entry points — nunca declara fetchers como dependências diretas. Isso mantém o hub leve e desacoplado.
1.1 Por que dois níveis?¶
- UX superior no hub: quando carregado via
quantilica-cli, o ambiente já tem Typer e Rich disponíveis. Oplugin.pyusa isso sem declarar dependência. - Implementação única: com o
FetcherApp, a gramática de subcomandos (sync,check,--from-plan, ...) vive uma vez só emplugin.py; acli.pyapenas delega a ela, sem duplicar a lógica de CLI. - Instalação mínima apenas como biblioteca: um usuário que consome o fetcher como biblioteca (
import) não precisa de Typer nem Rich. Executar a CLI standalone sem o host não é objetivo (ADR2026-10-08-fetcher-cli-wrapper-e-canal-de-distribuicao): a instalação canônica équantilica install <fonte>, que já traz o host; sem ele, o wrapper imprimeinstale via "quantilica install <fonte>"e sai com código 1. Aqui,<fonte>é a chave doSOURCES_REGISTRY(ver §3.6) — não necessariamente o nome do pacote.
1.2 Vocabulário canônico de subcomandos¶
Para que a CLis sejam previsíveis, todo fetcher usa o mesmo verbo para a mesma intenção. Cada fetcher implementa apenas o subconjunto que faz sentido para sua fonte, mas nunca inventa um nome alternativo para um verbo já existente nesta tabela:
| Verbo | Significado | Default |
|---|---|---|
sync |
Baixar/atualizar os dados da fonte; idempotente (pula o que já está atualizado) | baixa tudo; aceita seleção opcional via argumento posicional ou --dataset; aceita --from-plan (plano do check) |
check |
Obrigatório (fetchers de arquivo estático): verificar remoto × local (HEAD por entrada) e emitir plano de freshness, sem baixar; --json gera plano consumível por sync --from-plan |
— |
list |
Listar o que está disponível remotamente (datasets, tabelas, pesquisas) | — |
info |
Exibir metadados de uma entidade específica | — |
convert |
Converter dados brutos para Parquet/formato analítico | — |
export |
Exportar para formatos externos (Excel, SQLite) | — |
pipeline |
Encadear sync → convert/export com cabeçalhos de passo e resumo |
— |
search |
Busca livre em índice ou catálogo remoto | — |
archive |
Mover arquivos desatualizados para diretório de histórico | — |
periods |
Listar os períodos disponíveis para uma entidade específica | — |
Verbos de domínio
Verbos específicos do pacote são permitidos além desta tabela (ex: archive no datasus-fetcher, periods no ibge-sidra-fetcher). A regra é nunca reutilizar um verbo da tabela com semântica diferente.
Regras de ouro:
syncé o verbo de download. Nunca usedownload,fetch,trade,dataou outro sinônimo para "baixar os dados da fonte".syncbaixa tudo por padrão. A seleção de datasets é sempre opcional — omitir o argumento significa "sincronizar o conjunto completo".- Pré-visualização é uma flag, não um comando. Use
--dry-runnosyncpara listar o que seria baixado sem tocar a rede; não crie um comandoinfo/statusseparado só para listar.infoé reservado para metadados de uma entidade. Exceção:check(ADR 2026-10-07) não é listagem — é verificação remoto × local com plano consumível (--json→sync --from-plan), etapa operacional distinta do download. -
Exceção declarada:
bcb-sgs-fetcher(ADR2026-10-07-check-obrigatorio-e-sidra-sync-rename.md): o SGS é uma API de séries temporais, consultada por janela de datas num endpoint REST dinâmico (/dados/serie/bcdata.sgs.<n>/dados), e não uma URL estável por arquivo. O fetcher grava um snapshot JSON por série e por dia (--skip-existingpula as séries cujo snapshot do dia já existe), sem o plano remoto × local docheck. A carga no Postgres é responsabilidade dobcb-sgs-sql.O que a API oferece (verificado em 2026-10-13, série 11)
A API aceita
HEAD, não enviaLast-Modifiede devolve umETagfraco que acompanha o corpo da resposta (muda com a janela pedida), com304paraIf-None-Match. Umcheckbaseado nesseETagseria viável; o ADR de 2026-10-07 o descartou por outro motivo e a exceção continua em vigor até que alguém o implemente.- Fetchers FTP (
pdet-fetcher,datasus-fetcher) —checkherdado é conforme. Servidores FTP não provêmHEADnemLast-Modifiedconfiável; ocheckcanônico doFetcherApp(HEAD sobre os mesmos URLs dodownload_entry) pressupõe HTTP estático. Ambos usam oFetcherAppcomFtpClient. Opdet-fetcherherda ocheck, que devolve o vereditometadata-unavailablepor não haverHEAD/Last-Modifiedno cliente FTP; odatasus-fetchersubstitui ocheck_entrypor uma sonda local (arquivo já presente =skip/atualizado, sem consultar o servidor) e serializa as entradas para quecheck --jsonalimentesync --from-plan. Ambos os comportamentos são conformes para fins de obrigatoriedade docheck(§1.2). A checagem real para FTP via listagem remota (tamanho/mtime do diretório FTP) segue pendência registrada no plano2026-10-08-conformidade-fetchers-auditoria-2026-10. Fetchers FTP não devem simular um plano de freshness com dados que o protocolo não garante. - Agrupe quando houver mais de um eixo semântico. Veja §3.5 — fetchers como
o
bcb-sgsseparam operações por série (series sync,series metadata) das operações de catálogo (catalogo sync,catalogo metadata-bulk).
- Fetchers FTP (
1.3 O Padrão FetcherApp (Recomendado)¶
Novo (Agosto/2026): Para reduzir o boilerplate, o
quantilica-cliexporta a classequantilica.cli.sdk.FetcherApp.
Fetchers padrão (que fazem download de datasets estruturados via HTTP estático) devem instanciar o FetcherApp em plugin.py e passar seus metadados, estrutura de catálogos (ex: GROUPS, GROUP_ALIASES) e uma factory de rotas (path_builder). Com isso, a cli.py atua apenas como wrapper de execução, removendo totalmente a necessidade de escrever argparse, subcomandos manuais, e formatações Rich descritas nas seções 2 a 5.
Fetchers mais complexos (como os baseados em FTP ou APIs REST paginadas, ex: datasus-fetcher e ibge-sidra-fetcher) não estão isentos desta regra: eles devem herdar da FetcherApp ou sobrepor seus comandos canônicos via aliases_dict e composição (_build_commands), e aproveitar o FtpClient do quantilica-core para manter o plugin alinhado à SDK padrão. Ressalva: o ibge-sidra-fetcher instancia o FetcherApp no plugin.py, mas mantém uma cli.py com argparse dedicado (única exceção, conforme o ADR 2026-10-08); logo, sua cli.py não é um wrapper fino.
As seções a seguir (2 a 5) devem ser aplicadas apenas para o entendimento da engenharia por trás do FetcherApp ou quando, em último caso, um fetcher precisar estender a CLI nativamente e customizar intensamente.
1.3.1 Suporte a Lake Hive: command_convert e command_pipeline¶
Coletores que oferecem transformação de seus microdados para Parquet particionado em Hive utilizam os decorators do FetcherApp:
fetcher.command_convert(func): Registra o subcomando canônicoconvert. Expõe opções padronizadas (-i/--input,--lake/-o/--output,--dataset,--force,--verbose), delega parafunc(input, lake, dataset=..., force=...)e intercepta ausência de dependências analíticas.fetcher.command_pipeline(func): Registra o subcomando canônicopipeline, encadeando o passo 1/2 (sync) e o passo 2/2 (convert). Suporta--dry-runpara inspecionar os planos antes da execução.
# plugin.py
from pathlib import Path
from typing import Any
from quantilica.cli.sdk import FetcherApp
fetcher = FetcherApp(name="pdet-fetcher", help="Microdados do PDET.")
def convert(input_dir: Path, lake_dir: Path, dataset: list[str] | None = None, force: bool = False) -> Any:
from pdet_fetcher import lake
return lake.converter.convert(input_dir, lake_dir, datasets=dataset, force=force)
fetcher.command_convert(convert)
fetcher.command_pipeline(convert)
1.3.2 Fronteira autorizada do Lake Hive: lake.py¶
A escrita e conversão de dados para o lake analítico seguem estritamente a norma Padronização de Lake Hive (Parquet).
- O módulo
lake.py(ou submódulolake/) dentro do coletor é a única fronteira autorizada para ingestão e gravação no lake. - Dependências pesadas (
polars,duckdb,quantilica-analytics) residem exclusivamente sob o extra opcional[project.optional-dependencies]no grupoanalysis. - Os coletores registram seus conversores no grupo de entry points
quantilica.lakedopyproject.toml(ex.:pdet = "pdet_fetcher.lake:converter"), ao lado do entry point de comandosquantilica.fetchers.
Sobreposição de comandos do FetcherApp — paridade de flags
Um fetcher que re-registra sync/list/check por cima dos defaults do FetcherApp (caso datasus-fetcher/plugin.py, que re-registra list e sync; o check permanece o do SDK, com check_entry próprio) deve manter paridade de flags com o comando do SDK: o sync próprio inclui --from-plan (plano do check, já presente no datasus-fetcher desde 2026-10-08) e o check próprio inclui --json. No Typer, o último registro vence — a sobreposição substitui o default, não o estende; flags omitidas deixam de existir para o usuário.
1.4 Manifests de proveniência — o que é exigido de fetchers¶
DownloadManifest— obrigatório por arquivo baixado. Todo arquivo baixado por um fetcher sai acompanhado do seu sidecarDownloadManifest(SHA-256, URL de origem, timestamps). O fetcher não o constrói manualmente: ele é provido por herança doFetcherApp—FetcherApp._download_filedelega aclient.download_with_manifest(quantilica-cli/src/quantilica/cli/sdk.py), implementado emHttpClient.download_with_manifest(quantilica-core/src/quantilica/core/http.py) eFtpClient.download_with_manifest(quantilica-core/src/quantilica/core/ftp.py), que faz freshness check, escrita atômica e emite o sidecar. Regra prática: baixe sempre via o caminho doFetcherApp(download_entry/download_datasets); nunca faça streaming próprio sem manifest.ExecutionManifest— não exigido por download.ExecutionManifesté apenas o alias deRunManifest(quantilica-core/src/quantilica/core/manifests.py), disponível no core e re-exportado emquantilica.core. O código não impõe sua produção a fetchers nem o SDK o emite no caminho de download — portanto nenhum fetcher precisa produzi-lo por arquivo baixado.
1.5 Arquétipos de coleta e cenários especiais¶
As fontes públicas brasileiras distribuem-se em 7 arquétipos canônicos de transporte e descoberta, documentados em detalhe em Cenários, arquétipos de fonte e casos especiais:
| Arquétipo | Protocolo / Descoberta | Exemplos de referência | Estratégia padrão |
|---|---|---|---|
| 1. Diretórios estáticos / FTP / WebDAV | Autoindex HTML, FtpClient (MLSD/LIST) ou PROPFIND |
cvm-fetcher, rfb-cnpj-fetcher, pdet-fetcher, datasus-fetcher |
FetcherApp + DataRepository, FreshnessPolicy head_or_manifest |
| 2. Portais CKAN v3 + Storage S3/HTTP | GET /api/3/action/package_show?id=<slug> |
tesouro-direto-fetcher, anp-fetcher, anac-fetcher |
Metadados extraídos do JSON CKAN (last_modified) propagados ao download |
| 3. APIs OData v4 (Olinda) e REST paginado | Paginação $top / $skip com $orderby determinístico |
bcb-sgs-fetcher, APIs Olinda, PNCP, SICONFI |
Coleta particionada por janela temporal com snapshots JSON/CSV |
| 4. Handshake / Tokens efêmeros / Base64 | Parâmetros Base64 na rota ou token de curta duração | b3-fetcher |
Resolução tardia (lazy) do token dentro de download_entry |
5. Elasticsearch POST (search_after) |
POST /_search com sort determinístico e cursor search_after |
Buscadores processuais (ex.: DataJud) | Chave pública da API documentada + lotes .jsonl por partição |
| 6. Serviços geoespaciais OGC WFS 2.0 | GetFeature paginado (count, startIndex, sortBy) |
GeoServer fundiário/ambiental (INCRA, CAR, ANA) | Fatiamento por UF/BBOX + conversão para geom_wkb (WKB) no Lake |
7. Endpoints dinâmicos sem HEAD |
GET/POST sem Content-Length ou Last-Modified |
anp-fetcher, inep-fetcher, exportadores legados |
head_fallback_get (Range: bytes=0-0) ou deduplicação SHA-256 + check_payload |
Mapa da norma¶
A norma é dividida por assunto. Os números de seção (§) se mantêm em todas as páginas.
| Página | Seções | Quando consultar |
|---|---|---|
| Esta página | §1, §12, §13, Nomes de fetchers | Arquitetura de dois níveis, vocabulário de subcomandos, FetcherApp, checklist, exemplos de referência e a convenção de nomes dos fetchers |
| CLI nativa | §2 | Fetcher customizado com cli.py em argparse |
| Plugin | §3 | plugin.py, setup_rich_logging, comandos, extras opcionais, entry points |
| Padrões visuais Rich | §4 | Status, barras de progresso, tabelas, painéis e mensagens |
| Progresso e logging | §5, §6 | Callbacks de progresso e níveis de log |
| Erros, fluxos e anti-padrões | §7 a §11 | Códigos de saída, pipelines, dry-run, anos, contornos HTTP e o que evitar |
| Cenários e casos especiais | §14 a §18 | Arquétipos de fonte (HTTP, FTP, CKAN, OData, WFS), políticas de freshness, Soft-200 e casos especiais do Lake |
12. Checklist para novos fetchers¶
Use esta lista ao implementar ou revisar a CLI de um fetcher:
cli.py — wrapper fino (padrão FetcherApp)¶
- Import do plugin protegido:
try/except ImportError→ imprimeinstale via "quantilica install <fonte>"emsys.stderre sai com código 1 — nuncaModuleNotFoundError(referência:bcb-sgs-fetcher/src/bcb_sgs_fetcher/cli.py). -
main(argv: list[str] | None = None)— aceita argv para testabilidade (obrigatório). -
main()delega ao app na forma canônicaapp(argv), comif argv is None: argv = sys.argv[1:](nenhuma gramática de subcomando duplicada aqui; referência:bcb-sgs-fetcher/src/bcb_sgs_fetcher/cli.py). A forma antiga (sys.argv = [sys.argv[0]] + argv; app(), ainda presente emanac,anp,cvm,inep,inmet,pdet,rfb-cnpjertn) é tolerada até a próxima revisão de cada fetcher — fetchers novos usamapp(argv)(já adotada embcb-sgs,comex,datasus,tesouro-diretoetse). -
cli.pynão importaquantilica.cli.sdk/quantilica.cli.uidiretamente — apenas oplugin.py(§3.2). - Entry point declarado em
[project.scripts].
cli.py — argparse (apenas fetcher customizado, ex: ibge-sidra-fetcher)¶
-
argparse.ArgumentParsercomprogedescriptiondefinidos. -
--versioncomaction="version"lendo de__version__. -
-o/--outputcom padrão/data/<fonte>. -
--verbosesem atalho-v. - Subcomandos com
add_subparsers(dest="command", required=True)ouparser.set_defaults(func=lambda _: parser.print_help())(§2.1). - Função de construção do parser nomeada
get_parser()(nãoset_parser, nãoget_args). -
main(argv: list[str] | None = None)— aceita argv para testabilidade (obrigatório). -
main()chamaconfigure_cli_logging(verbose=args.verbose)antes de qualquer I/O. - Se exibir progresso:
logging.getLogger("quantilica.core").setLevel(logging.WARNING)elogging.getLogger("<pacote_fetcher>").setLevel(logging.WARNING)quandonot verbose(§2.6). - Erros fatais escrevem em
stderre encerram comsys.exit(1). - Entry point declarado em
[project.scripts].
plugin.py (Typer + Rich)¶
- Docstring
"""Typer plugin for quantilica-cli integration.""". -
app = typer.Typer(help="...")no topo (ouapp = FetcherApp(...).app). -
console = get_console()compartilhado por todos os comandos próprios (importado dequantilica.cli.ui) — apenas se o plugin define comandos próprios; plugins 100%FetcherApp(ex.:comex,rtn) herdam do SDK e não o definem (§3.2). -
_DEFAULT_OUTPUT = Path("/data/<fonte>")— apenas se o plugin define comandos próprios; plugins 100%FetcherAppherdam o default do SDK (§3.2). - Cada comando chama
setup_rich_logging(verbose, console=console)como primeira linha. - Funções de comando nomeadas
cmd_<verbo>(ex:cmd_sync,cmd_list). - Nenhum
typer.echo()— apenasconsole.print(). - Nenhum
print()direto. -
-o/--outputpresente em todo comando que salva arquivos. -
--verbosepresente em todo comando que faz I/O de rede. - Operações únicas de rede usam
console.status(...). - Operações bulk usam
Progresscomconsole=console(ouLive + Grouppara dois níveis — §4.3). - Callbacks (
on_progress,on_grupo,on_page,ProgressCallback,on_done) separam display de lógica (§5.2). - Mensagens de sucesso usam
[green]✓[/green]. - Erros usam
[red]Erro:[/red]+raise typer.Exit(code=1). - Avisos usam
[yellow]Aviso:[/yellow]. - Entry point declarado em
[project.entry-points."quantilica.fetchers"]. - Entry point de conversão declarado em
[project.entry-points."quantilica.lake"](quando houver suporte a conversão para lake Hive). -
typererichnão estão em[project.dependencies]. - Fronteira:
quantilica.cli.sdk/quantilica.cli.uisão importados somente aqui — nenhum outro módulo do fetcher os importa (§3.2). - Fronteira do Lake: a conversão para Parquet Hive vive exclusivamente em
lake.pysob o extra[analysis], exposta viafetcher.command_convert()efetcher.command_pipeline()(Padronização de Lake Hive).
13. Exemplos de referência no ecossistema¶
| Padrão | Fetcher de referência | Arquivo |
|---|---|---|
| Pipeline completo com Rule + Progress + resumo | bcb-sgs-fetcher |
plugin.py :: pipeline_cmd (comando catalogo sync) |
Callbacks on_progress / on_grupo / on_page |
bcb-sgs-fetcher |
bulk.py |
setup_rich_logging — logging sem quebrar barras de progresso |
bcb-sgs-fetcher |
plugin.py :: fetch (qualquer comando) |
Live + Group — duas barras simultâneas (itens + bytes) |
comex-fetcher |
plugin.py :: sync |
ProgressCallback per-file + _file_callback |
comex-fetcher |
plugin.py |
on_done(filename, result) callback pós-arquivo |
rtn-fetcher |
plugin.py :: _sync_publications |
console.status + asyncio.run() para downloads async |
tesouro-direto-fetcher |
plugin.py :: cmd_sync |
getLogger("quantilica.core"/"<pacote>").setLevel(WARNING) em cli.py |
ibge-sidra-fetcher |
src/ibge_sidra_fetcher/cli.py :: main |
Wrapper fino de plugin.py com import protegido |
bcb-sgs-fetcher |
cli.py |
| Table com totais em rodapé | datasus-fetcher |
plugin.py :: cmd_list |
console.status em conexão FTP |
datasus-fetcher |
plugin.py :: cmd_list |
Subcommands aninhados (series_sub, catalogo_sub) |
bcb-sgs-fetcher |
plugin.py |
Expansão de intervalos de anos 2018:2020 |
comex-fetcher |
plugin.py :: expand_years_cli |
| Panel com metadados de entidade | ibge-sidra-fetcher |
plugin.py :: cmd_info |
--dry-run com tabela de pré-visualização |
datasus-fetcher |
plugin.py :: cmd_sync |
Pipeline sync → export/convert |
rtn-fetcher |
plugin.py :: cmd_pipeline |
_print_info como helper de tabela reutilizável |
tesouro-direto-fetcher |
plugin.py :: _print_info |
console.rule / console.print(Rule(...)) para seção |
tesouro-direto-fetcher |
plugin.py :: cmd_pipeline |
Nomes de fetchers¶
O nome de um fetcher é uma decisão pública: aparece no comando (quantilica install <id>), na distribuição instalada, na URL do repositório e na página da fonte. Renomear depois custa um renome em cadeia; acertar o nome na criação não custa nada.
Regra de base¶
- O id do fetcher é o nome do repositório sem
-fetcher. O repositório e a distribuição são<id>-fetcher; o módulo é<id_com_sublinhado>_fetcher. O teste de identidade de cada fetcher confere essa regra. - O id é kebab ASCII em minúsculas:
^[a-z0-9]+(-[a-z0-9]+)*$. Sem acento, sem sublinhado, sem maiúscula, sem-fetcherno id. - O nome diz a fonte (quem publica o dado), não a tecnologia nem o produto do consumidor.
Fontes subnacionais¶
| Escopo | Forma | Exemplos | Contraexemplos |
|---|---|---|---|
| Estado | <fonte>-<uf>; a UF é uma das 27 siglas, em minúsculas |
ssp-sp, tce-pe, transparencia-sp |
ssp-saopaulo (UF por extenso), ssp_sp (sublinhado), sp-ssp (UF no começo), tce-xx (xx não é UF) |
| Município, a fonte é a prefeitura | prefeitura-<município>-<produto>; o município em slug kebab |
prefeitura-sp-dados, prefeitura-recife-dados-abertos |
prefeitura-sp (falta o produto), sp-prefeitura-dados |
| Município, a fonte não é a prefeitura | <fonte>-<município>-<uf> |
ssp-campinas-sp |
ssp-campinas (falta a UF), ssp-sp-campinas (UF fora do fim) |
| Federal | sem sufixo; -federal só quando existe um irmão subnacional de mesmo nome |
transparencia-federal ao lado de transparencia-sp |
anac-federal (a ANAC não tem irmão estadual; é anac) |
Duas consequências práticas:
- A UF fecha o id. Se o id tem mais de um segmento e o último tem 2 letras, esse segmento é uma UF. É o que permite distinguir
transparencia-sp(estado de São Paulo) de um nome qualquer terminado em duas letras. Ob3(um segmento só) não é afetado. -federalé a exceção, não o padrão. O nome da fonte federal fica sem sufixo até aparecer o primeiro irmão subnacional; só então se acrescenta-federal(um renome, com apelido). Sem irmão, a checagem emite um aviso.
Prefixo de órgão¶
- Quando o órgão tem vários fetchers com nome de produto genérico, o id leva o órgão como prefixo:
ibge-sidra,ibge-microdados,bcb-sgs,bcb-microdados. Assim os fetchers do mesmo órgão aparecem juntos nas listas ordenadas, e um nome de produto (SIDRA) não é lido como nome do órgão. - O nome do sistema é uma alternativa legítima quando ele é, por si só, o nome conhecido da fonte:
datasus,sigtap,rtn. Esses não são candidatos a renome por falta de prefixo. - Um fetcher com nome de produto genérico sem irmão do mesmo órgão pode ficar sem prefixo; o prefixo entra com o segundo fetcher do órgão (um renome).
Checagem automática¶
infra/nomes_fetchers.py (no repositório do workspace) valida a gramática, a regra da UF e o aviso de -federal sem irmão:
python3 infra/nomes_fetchers.py ssp-sp transparencia-federal
python3 infra/nomes_fetchers.py --registro https://index.quantilica.com/registry.json
O script de renome (infra/rename_fetcher.py) recusa um id novo que a checagem reprova. O prefixo de órgão e o nome de sistema são decisões editoriais e ficam fora da máquina.
Saiba mais¶
- Arquitetura de CLI e Estratégia de Dependências — visão arquitetural de alto nível.
- quantilica-cli — como o hub descobre e monta os plugins.
- Padrões Práticos — UX de CLI — padrão progresso vs. logs.
- Renomear um fetcher — o contrato e o script de renome.
- Padronização de Versão — como expor
__version__em argparse e Typer.