Convenções de Armazenamento — Fetchers¶

Este documento define os padrões de nomenclatura de arquivos, estrutura de pastas e interface CLI adotados por todos os pacotes fetcher da Quantilica. Novos fetchers e alterações em fetchers existentes devem seguir estas convenções.

Nomenclatura de Arquivos¶

O nome de cada arquivo baixado incorpora um timestamp extraído do servidor de origem (cabeçalho Last-Modified ou equivalente). A função stamp_filename() de quantilica_core.storage implementa o padrão.

Formato¶

{base}@{timestamp}.{ext}

O separador entre a base e o timestamp é sempre @. A base codifica o conjunto de dados e a partição; o timestamp indica quando o arquivo foi publicado na origem, não quando foi baixado.

Precisão do timestamp¶

Precisão	Formato	Quando usar
`date` (padrão)	`YYYYMMDD`	Fontes com granularidade diária
`datetime`	`YYYYMMDDTHHMMSS`	Fontes com múltiplas versões no mesmo dia

Quando o servidor não retorna timestamp, o arquivo é salvo sem @ — sem inventar uma data.

Exemplos por pacote¶

Pacote	Exemplo de nome
`comex-fetcher`	`[email protected]`
`datasus-fetcher`	`[email protected]`
`inmet-fetcher`	`[email protected]`
`pdet-fetcher`	`[email protected]`
`rtn-fetcher`	`[email protected]`
`tesouro-direto-fetcher`	`taxas-dos-titulos-ofertados-pelo-tesouro-direto@20240315T101530.csv`

Implementação¶

from quantilica_core.storage import stamp_filename

# Precisão date (padrão)
stamp_filename("exp_2023", "csv", date(2024, 3, 15))
# → "[email protected]"

# Precisão datetime
stamp_filename("rtn", "xlsx", datetime(2024, 3, 15, 10, 15), precision="datetime")
# → "[email protected]"

# Sem timestamp
stamp_filename("rtn", "xlsx", None)
# → "rtn.xlsx"

Estrutura de Pastas¶

Os arquivos são organizados em pastas diretamente nomeadas pelo dataset_id, sem camada intermediária de categoria (sem raw//processed//docs/). Esta é a estrutura adotada por todos os fetchers e implementada pelo método BaseDataRepository.dataset_path() do quantilica-core.

Princípio¶

{output}/
├── {dataset_id}/
│   ├── {partição}/      ← opcional; usada quando há agrupamento temporal ou geográfico
│   │   └── [email protected]
│   └── [email protected]
└── ...

O diretório raiz ({output}) é o único caminho fornecido pelo usuário. A estrutura interna é de responsabilidade exclusiva do pacote.

API do quantilica-core¶

from quantilica_core.storage import BaseDataRepository

class FooRepository(BaseDataRepository):
    def file_path(self, dataset_id: str, filename: str) -> Path:
        return self.dataset_path(dataset_id, filename)
        # → {root}/{dataset_id}/{filename}

Categorias adicionais (documentação, dados processados, etc.) são responsabilidade do fetcher — use self.storage.path_for(...) diretamente.

Exemplos por pacote¶

comex-fetcher

{output}/
├── exp/
│   └── [email protected]
├── imp/
│   └── [email protected]
├── exp-mun/
├── imp-mun/
├── auxiliary-tables/
│   └── [email protected]
├── repetro/
└── validacao/

datasus-fetcher

{output}/
├── sih-rd/
│   ├── 202001/
│   │   └── [email protected]
│   └── 202002/
├── sinasc-dn/
│   └── 2023/
│       └── [email protected]
├── _documentacao/
│   ├── sih/
│   │   └── [email protected]
│   └── sinasc/
└── _auxiliar/
    └── sih/
        └── [email protected]

Documentação e tabelas auxiliares são agrupadas pelo sistema (ex: sih, cnes), não pelo subsistema (ex: sih-rd, cnes-dc), pois um mesmo conjunto de documentos cobre todos os subsistemas de um sistema. O prefixo _ faz essas pastas aparecerem antes das pastas de dados em qualquer ordenação alfabética e evita nomes reservados do Windows (como aux).

inmet-fetcher

{output}/
└── bdmep/
    ├── 2022/
    │   └── [email protected]
    └── 2023/
        └── [email protected]

pdet-fetcher

{output}/
├── caged/
│   └── 2021/
│       └── [email protected]
├── caged-ajuste/
├── rais-vinculos/
│   └── 2023/
│       └── [email protected]
├── rais-estabelecimentos/
└── _documentacao/
    ├── caged/
    └── rais-vinculos/

rtn-fetcher

{output}/
├── metadata.html
├── metadata.json
├── 2024-01/
│   └── publicacao.pdf
└── [email protected]

tesouro-direto-fetcher

{output}/
├── taxas-dos-titulos-ofertados-pelo-tesouro-direto/
│   └── [email protected]
├── operacoes-do-tesouro-direto/
└── estoque-do-tesouro-direto/

Interface CLI¶

Todos os fetchers expõem o diretório de saída pelo argumento -o / --output.

Especificação¶

Propriedade	Valor
Nomes	`-o`, `--output`
Tipo	`Path` (via `type=Path` no argparse)
Padrão	`Path("/data/<fonte>")`
Obrigatoriedade	Opcional (o padrão é suficiente para uso imediato)

Padrões por pacote¶

Pacote	Default de `--output`
`comex-fetcher`	`/data/secex-comex`
`datasus-fetcher`	`/data/datasus`
`inmet-fetcher`	`/data/inmet`
`pdet-fetcher`	`/data/pdet`
`rtn-fetcher`	`/data/rtn`
`tesouro-direto-fetcher`	`/data/tesouro-direto`

Implementação¶

parser.add_argument(
    "-o", "--output",
    type=Path,
    default=Path("/data/secex-comex"),
    help="Diretório de saída.",
)

Notas¶

Comandos que recebem um diretório de entrada (leitura de arquivos já baixados) devem usar --input ou argumento posicional — nunca reutilizar --output para esse fim.
Subcomandos de uma mesma CLI devem todos aceitar --output com o mesmo default; não é necessário repetir o default em cada subcomando se o parser raiz o define.
O argumento --archive-dir do datasus-fetcher (diretório de arquivamento de versões antigas) é um segundo diretório de saída para operação específica — mantém nome próprio sem conflitar com --output.

Atualizado em: 11 de maio de 2026