quantilica-cli 0.12.0__tar.gz → 0.14.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. quantilica_cli-0.14.0/.github/workflows/public-hygiene.yml +104 -0
  2. {quantilica_cli-0.12.0 → quantilica_cli-0.14.0}/.github/workflows/test.yml +7 -2
  3. {quantilica_cli-0.12.0 → quantilica_cli-0.14.0}/CHANGELOG.md +26 -5
  4. quantilica_cli-0.14.0/PKG-INFO +83 -0
  5. quantilica_cli-0.14.0/README.md +58 -0
  6. {quantilica_cli-0.12.0 → quantilica_cli-0.14.0}/pyproject.toml +6 -2
  7. {quantilica_cli-0.12.0 → quantilica_cli-0.14.0}/src/quantilica/cli/cli.py +2 -0
  8. quantilica_cli-0.14.0/src/quantilica/cli/lake.py +418 -0
  9. {quantilica_cli-0.12.0 → quantilica_cli-0.14.0}/src/quantilica/cli/sdk.py +165 -30
  10. {quantilica_cli-0.12.0 → quantilica_cli-0.14.0}/src/quantilica/cli/sources.py +69 -15
  11. quantilica_cli-0.14.0/tests/lake_build_fakes.py +95 -0
  12. quantilica_cli-0.14.0/tests/lake_fixtures.py +101 -0
  13. quantilica_cli-0.14.0/tests/test_lake_cli.py +471 -0
  14. {quantilica_cli-0.12.0 → quantilica_cli-0.14.0}/tests/test_sdk.py +139 -0
  15. {quantilica_cli-0.12.0 → quantilica_cli-0.14.0}/tests/test_sdk_onda_a2.py +8 -5
  16. {quantilica_cli-0.12.0 → quantilica_cli-0.14.0}/tests/test_sources.py +31 -0
  17. quantilica_cli-0.12.0/PKG-INFO +0 -49
  18. quantilica_cli-0.12.0/README.md +0 -26
  19. {quantilica_cli-0.12.0 → quantilica_cli-0.14.0}/.githooks/pre-commit +0 -0
  20. {quantilica_cli-0.12.0 → quantilica_cli-0.14.0}/.githooks/pre-push +0 -0
  21. {quantilica_cli-0.12.0 → quantilica_cli-0.14.0}/.github/workflows/publish.yml +0 -0
  22. {quantilica_cli-0.12.0 → quantilica_cli-0.14.0}/.gitignore +0 -0
  23. {quantilica_cli-0.12.0 → quantilica_cli-0.14.0}/LICENSE +0 -0
  24. {quantilica_cli-0.12.0 → quantilica_cli-0.14.0}/src/quantilica/cli/__init__.py +0 -0
  25. {quantilica_cli-0.12.0 → quantilica_cli-0.14.0}/src/quantilica/cli/health.py +0 -0
  26. {quantilica_cli-0.12.0 → quantilica_cli-0.14.0}/src/quantilica/cli/manifests.py +0 -0
  27. {quantilica_cli-0.12.0 → quantilica_cli-0.14.0}/src/quantilica/cli/ui.py +0 -0
  28. {quantilica_cli-0.12.0 → quantilica_cli-0.14.0}/src/quantilica/py.typed +0 -0
  29. {quantilica_cli-0.12.0 → quantilica_cli-0.14.0}/tests/__init__.py +0 -0
  30. {quantilica_cli-0.12.0 → quantilica_cli-0.14.0}/tests/test_health.py +0 -0
  31. {quantilica_cli-0.12.0 → quantilica_cli-0.14.0}/tests/test_manifests.py +0 -0
  32. {quantilica_cli-0.12.0 → quantilica_cli-0.14.0}/tests/test_package_hygiene.py +0 -0
  33. {quantilica_cli-0.12.0 → quantilica_cli-0.14.0}/tests/test_sdk_force_probe.py +0 -0
  34. {quantilica_cli-0.12.0 → quantilica_cli-0.14.0}/tests/test_sdk_mes_string.py +0 -0
  35. {quantilica_cli-0.12.0 → quantilica_cli-0.14.0}/tests/test_ui.py +0 -0
@@ -0,0 +1,104 @@
1
+ name: Public hygiene
2
+
3
+ # Veta termos internos (planos, decisões, repositórios privados, infraestrutura)
4
+ # em CHANGELOG.md, README e nas mensagens de commit de PRs. O repositório é
5
+ # público: o que entra aqui fica no histórico para sempre.
6
+ # Regra e lista de termos: docs/normas/changelog.md, seção 5.1.
7
+ # Falso positivo legítimo: termine a linha com `<!-- hygiene-ok -->`.
8
+
9
+ on:
10
+ push:
11
+ branches: [main]
12
+ pull_request:
13
+ branches: [main]
14
+ workflow_dispatch:
15
+
16
+ permissions:
17
+ contents: read
18
+
19
+ jobs:
20
+ hygiene:
21
+ name: Termos internos
22
+ runs-on: ubuntu-latest
23
+ steps:
24
+ - uses: actions/checkout@v4
25
+ with:
26
+ fetch-depth: 0
27
+
28
+ - name: Escrever lista de termos
29
+ run: |
30
+ cat > "$RUNNER_TEMP/termos-comuns.txt" <<'EOF'
31
+ \bOnda\b
32
+ \bADR\b
33
+ \bplanning/
34
+ \bplano (`|[a-z0-9-]+-[a-z0-9-]+|§)
35
+ \bPlano:
36
+ uploader
37
+ \bCAS\b
38
+ \bVPS\b
39
+ crontab
40
+ \bcrons?\b
41
+ systemd
42
+ runs\.csv
43
+ quantilica-(workers|cloud|web|events|portal|manifests-db)
44
+ bcb-sgs-app
45
+ rtn-app
46
+ crons-dashboard
47
+ datasus-analytics
48
+ [a-z-]+-metadata-db
49
+ tddata-db
50
+ dev-plugins
51
+ \bOKF\b
52
+ Flamingo
53
+ Alpaca
54
+ Hedgehog
55
+ Sloth
56
+ \bFish\b
57
+ Telegram
58
+ Umami
59
+ Cloudflare
60
+ (^|[^[:alnum:].])/home/[a-z]+
61
+ \.agents/
62
+ CLAUDE\.md
63
+ AGENTS\.md
64
+ EOF
65
+ cat > "$RUNNER_TEMP/termos-arquivos.txt" <<'EOF'
66
+ \bworkspace\b
67
+ ingestão efêmera
68
+ retenção efêmera
69
+ pipeline de ingestão
70
+ EOF
71
+ cat "$RUNNER_TEMP/termos-comuns.txt" "$RUNNER_TEMP/termos-arquivos.txt" \
72
+ > "$RUNNER_TEMP/termos-todos.txt"
73
+
74
+ - name: CHANGELOG e README
75
+ run: |
76
+ files=$(ls CHANGELOG.md README*.md docs/changelog.md 2>/dev/null || true)
77
+ if [ -z "$files" ]; then
78
+ echo "Nenhum CHANGELOG/README para verificar."
79
+ exit 0
80
+ fi
81
+ # shellcheck disable=SC2086
82
+ hits=$(grep -nIiE -f "$RUNNER_TEMP/termos-todos.txt" $files /dev/null \
83
+ | grep -v 'hygiene-ok' || true)
84
+ if [ -n "$hits" ]; then
85
+ echo "$hits"
86
+ echo "::error::Termos internos em changelog/README. Reescreva em termos públicos (docs/normas/changelog.md, seção 5.1)."
87
+ exit 1
88
+ fi
89
+ echo "Limpo."
90
+
91
+ - name: Mensagens de commit do PR
92
+ if: github.event_name == 'pull_request'
93
+ run: |
94
+ range="${{ github.event.pull_request.base.sha }}..${{ github.event.pull_request.head.sha }}"
95
+ msgs=$(git log --format='%h %s%n%b' "$range")
96
+ hits=$(printf '%s\n' "$msgs" \
97
+ | grep -iE -f "$RUNNER_TEMP/termos-comuns.txt" \
98
+ | grep -v 'hygiene-ok' || true)
99
+ if [ -n "$hits" ]; then
100
+ echo "$hits"
101
+ echo "::error::Termos internos em mensagem de commit. Reescreva o commit (docs/normas/changelog.md, seção 5.1)."
102
+ exit 1
103
+ fi
104
+ echo "Limpo."
@@ -9,12 +9,16 @@ on:
9
9
 
10
10
  jobs:
11
11
  test:
12
- name: Test (Python ${{ matrix.python-version }})
13
- runs-on: ubuntu-latest
12
+ name: Test (${{ matrix.os }}, Python ${{ matrix.python-version }})
13
+ runs-on: ${{ matrix.os }}
14
14
  strategy:
15
15
  fail-fast: false
16
16
  matrix:
17
+ os: [ubuntu-latest]
17
18
  python-version: ["3.12", "3.13"]
19
+ include:
20
+ - os: windows-latest
21
+ python-version: "3.12"
18
22
 
19
23
  steps:
20
24
  - uses: actions/checkout@v4
@@ -31,6 +35,7 @@ jobs:
31
35
  # (2026-08-23: rtn e inmet). Três tentativas removem o flake sem
32
36
  # esconder erro real de resolução.
33
37
  - name: Install dependencies
38
+ shell: bash
34
39
  run: |
35
40
  for i in 1 2 3; do
36
41
  if uv sync --group dev --python ${{ matrix.python-version }} \
@@ -5,6 +5,27 @@ Todas as mudanças notáveis deste projeto serão documentadas neste arquivo.
5
5
  O formato segue [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/),
6
6
  e este projeto adere ao [Semantic Versioning](https://semver.org/lang/pt-BR/).
7
7
 
8
+ ## [0.14.0] - 2026-10-30
9
+
10
+ ### Adicionado
11
+
12
+ - `quantilica lake select|build|audit`: monta e audita o lake a partir de um bruto local. `select` cria a visão com a versão vigente de cada arquivo (`--mode hardlink|symlink|copy`, `--exclude ARQ` com `sha256` ou caminhos); `build` converte a visão em Parquet por fonte e dataset, em processos separados e com retomada (`--sources`, `--workers`, `--memory`, `--threads`, `--scratch`, `--force`, `--retry-errors`, `--no-disk-check`, `--allow-sleep`), e sai com código 1 se houver erro e 130 se for interrompido; `audit` confere rodapés, proveniência, cobertura, estrutura e leitores (`--input`, `--ledger`, `--sources`, `--no-readers`, `--no-integrity`, `--exceptions`, `--rehash`, `--workers`, `--json`, `--json-file`) e sai com código 1 se houver achados. O ledger é opcional.
13
+ - Extra `lake` (`pip install "quantilica-cli[lake]"`): traz o `quantilica-analytics`, que `build` e `audit` carregam só quando rodam; sem ele, avisam o que instalar e saem com código 1. `select` só precisa do `quantilica-core` (a partir da versão que traz `materialize_view`).
14
+ - CI: o job de testes também roda no Windows (Python 3.12).
15
+
16
+ ## [0.13.0] - 2026-10-27
17
+
18
+ ### Adicionado
19
+
20
+ - `convert`: novas opções `--lake` (raiz do lake de destino; padrão `lake_root()` de `quantilica.core.lake`, ou `default_output` se o core não tiver o módulo), `--dataset` (repetível) e `--force`. `-o/--output` continua aceito como alias de `--lake`. O conversor é chamado como `func(input, lake)` e recebe `dataset=` e `force=` por keyword só quando a assinatura os aceita (ou tem `**kwargs`); pedir `--dataset`/`--force` a um conversor que não os aceita sai com código 2.
21
+ - `convert` e `pipeline`: se o conversor devolver um objeto (ou dicionário) com `converted`, `skipped` e `errors`, o sumário é exibido, e `errors > 0` sai com código 1.
22
+ - `pipeline --lake` (com `--parquet-dir` mantido como alias), repassado ao conversor.
23
+ - `quantilica doctor`: informa, por fonte, se há conversor do lake registrado no entry point `quantilica.lake`.
24
+
25
+ ### Alterado
26
+
27
+ - `pipeline`: o destino da conversão passa a ser `lake_root()` por padrão, em vez de igual a `--output`.
28
+
8
29
  ## [0.12.0] - 2026-10-19
9
30
 
10
31
  ### Adicionado
@@ -46,7 +67,7 @@ e este projeto adere ao [Semantic Versioning](https://semver.org/lang/pt-BR/).
46
67
  ### Corrigido
47
68
 
48
69
  - `sdk`: `check_entry` considera `local.exists() or sidecar.exists()`, preservando
49
- o status de `manifest-fresh` em ambientes de ingestão efêmera sem forçar
70
+ o status de `manifest-fresh` em ambientes sem retenção local dos arquivos sem forçar
50
71
  re-download redundante quando o dado bruto já foi espelhado.
51
72
 
52
73
  ## [0.10.0] - 2026-10-07
@@ -71,7 +92,7 @@ e este projeto adere ao [Semantic Versioning](https://semver.org/lang/pt-BR/).
71
92
 
72
93
  ## [0.9.1] - 2026-10-04
73
94
 
74
- Correção de escape inválido introduzido na v0.8.0 (Onda A.2 do SDK).
95
+ Correção de escape inválido introduzido na v0.8.0 (extensões do SDK).
75
96
 
76
97
  ### Corrigido
77
98
  - `SyntaxWarning: invalid escape sequence '\['` nas mensagens de `convert`,
@@ -95,7 +116,7 @@ fetcher (wheel no GitHub Releases, entrada no índice PEP 503 do ecossistema).
95
116
 
96
117
  ## [0.8.0] - 2026-10-03
97
118
 
98
- Onda A.2 do plano `2026-10-03-padronizacao-core-e-consolidacao-fetchers` —
119
+ Padronização do SDK e consolidação dos fetchers —
99
120
  decorators de ciclo de vida no SDK (`quantilica.cli.sdk`) e abstração de
100
121
  pré-visualização tabular de sincronização.
101
122
 
@@ -126,7 +147,7 @@ pré-visualização tabular de sincronização.
126
147
 
127
148
  ## [0.7.0] - 2026-10-02
128
149
 
129
- Onda 2 — extensões do SDK (`quantilica.cli.sdk`) para eliminação de
150
+ Extensões do SDK (`quantilica.cli.sdk`) para eliminação de
130
151
  boilerplate nos fetchers (decisão
131
152
  `2026-10-02-padronizacao-e-deduplicacao-fetchers`).
132
153
 
@@ -160,7 +181,7 @@ boilerplate nos fetchers (decisão
160
181
  ## [0.3.1] - 2026-08-22
161
182
 
162
183
  ### Corrigido
163
- - `DEFAULT_INDEX_URL` apontado para `https://index.quantilica.com/simple/` — a URL anterior (`quantilica.com/quantilica-index/`) parou de ser servida quando o domínio passou ao portal, quebrando o `quantilica install` para fetchers fora do PyPI legado (detalhes no ADR de distribuição de 2026-08-22).
184
+ - `DEFAULT_INDEX_URL` apontado para `https://index.quantilica.com/simple/` — a URL anterior (`quantilica.com/quantilica-index/`) parou de ser servida quando o domínio passou ao portal, quebrando o `quantilica install` para fetchers fora do PyPI legado (detalhes na decisão de distribuição de 2026-08-22).
164
185
  - `install`/`uninstall` agora mesclam o registro remoto (`sources.json`) com o registro local, resolvendo também nomes canônicos do índice (ex.: `tesouro-direto`, além de `td`).
165
186
 
166
187
  ## [0.3.0] - 2026-08-10
@@ -0,0 +1,83 @@
1
+ Metadata-Version: 2.5
2
+ Name: quantilica-cli
3
+ Version: 0.14.0
4
+ Summary: Unified CLI for Quantilica open data fetchers
5
+ Author-email: "Komesu, D.K." <daniel@dkko.me>
6
+ License-Expression: MIT
7
+ License-File: LICENSE
8
+ Keywords: brazil,cli,open-data,quantilica
9
+ Classifier: Development Status :: 3 - Alpha
10
+ Classifier: Environment :: Console
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Intended Audience :: Science/Research
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Typing :: Typed
18
+ Requires-Python: >=3.12
19
+ Requires-Dist: quantilica-core>=0.15.0
20
+ Requires-Dist: rich>=13.0.0
21
+ Requires-Dist: typer>=0.15.0
22
+ Provides-Extra: lake
23
+ Requires-Dist: quantilica-analytics>=0.8.0; extra == 'lake'
24
+ Description-Content-Type: text/markdown
25
+
26
+ # quantilica-cli
27
+
28
+ CLI unificada para o ecossistema Quantilica de dados abertos brasileiros.
29
+ For full documentation, please visit [https://docs.quantilica.com](https://docs.quantilica.com).
30
+
31
+ ## Instalação
32
+
33
+ ```bash
34
+ pip install quantilica-cli
35
+ ```
36
+
37
+ Instale os fetchers desejados separadamente:
38
+
39
+ ```bash
40
+ pip install comex-fetcher inmet-fetcher rtn-fetcher
41
+ ```
42
+
43
+ ## Uso
44
+
45
+ ```bash
46
+ quantilica --help
47
+ quantilica list-sources
48
+ quantilica comex sync 2024
49
+ quantilica inmet sync 2020 2021
50
+ quantilica td sync --dataset prices
51
+ ```
52
+
53
+ ## Lake
54
+
55
+ `quantilica lake` monta e audita o lake de Parquet a partir de um bruto local, sem
56
+ depender de banco de dados nem do ledger do acervo (ele é opcional). O fluxo é
57
+ bruto local → `select` → `build` → `audit`:
58
+
59
+ ```bash
60
+ # 1. visão só com a versão vigente de cada arquivo (hardlink; cai em symlink e em cópia)
61
+ quantilica lake select --raw /dados/bruto --out /dados/vigente --exclude excluir.txt
62
+
63
+ # 2. conversão em Parquet, por fonte e dataset, em processos separados; retoma de onde parou
64
+ quantilica lake build --input /dados/vigente --lake /dados/lake --workers 4 --memory 12GB
65
+
66
+ # 3. auditoria: rodapés, proveniência (sha256), cobertura, estrutura e leitores
67
+ quantilica lake audit --lake /dados/lake --input /dados/vigente --json-file auditoria.json
68
+ ```
69
+
70
+ - `select` só precisa do `quantilica-core`. `build` e `audit` usam o
71
+ `quantilica-analytics`, que entra com `pip install "quantilica-cli[lake]"`; sem ele
72
+ esses dois comandos avisam o que instalar e saem com código 1.
73
+ - `--exclude` e `--exceptions` aceitam um arquivo texto com um item por linha (linhas
74
+ vazias e iniciadas por `#` são ignoradas): `sha256` ou caminho relativo no `select`,
75
+ caminho relativo ou padrão `fnmatch` no `audit`.
76
+ - `build` sai com código 1 se alguma tarefa falhar, e com 130 se for interrompido
77
+ (Ctrl+C); rodar de novo retoma e `--retry-errors` refaz só o que falhou. O andamento
78
+ sai em stderr.
79
+ - `audit` sai com 0 se o lake for aprovado e com 1 se houver achados. `--json` imprime
80
+ o relatório em JSON no stdout (o andamento fica em stderr); `--json-file ARQ` o grava.
81
+ - `--ledger ARQ` (opcional, só em `audit`) confere a proveniência também contra uma
82
+ exportação do ledger; sem ele, a conferência usa o `sha256` dos manifestos ou do
83
+ próprio arquivo.
@@ -0,0 +1,58 @@
1
+ # quantilica-cli
2
+
3
+ CLI unificada para o ecossistema Quantilica de dados abertos brasileiros.
4
+ For full documentation, please visit [https://docs.quantilica.com](https://docs.quantilica.com).
5
+
6
+ ## Instalação
7
+
8
+ ```bash
9
+ pip install quantilica-cli
10
+ ```
11
+
12
+ Instale os fetchers desejados separadamente:
13
+
14
+ ```bash
15
+ pip install comex-fetcher inmet-fetcher rtn-fetcher
16
+ ```
17
+
18
+ ## Uso
19
+
20
+ ```bash
21
+ quantilica --help
22
+ quantilica list-sources
23
+ quantilica comex sync 2024
24
+ quantilica inmet sync 2020 2021
25
+ quantilica td sync --dataset prices
26
+ ```
27
+
28
+ ## Lake
29
+
30
+ `quantilica lake` monta e audita o lake de Parquet a partir de um bruto local, sem
31
+ depender de banco de dados nem do ledger do acervo (ele é opcional). O fluxo é
32
+ bruto local → `select` → `build` → `audit`:
33
+
34
+ ```bash
35
+ # 1. visão só com a versão vigente de cada arquivo (hardlink; cai em symlink e em cópia)
36
+ quantilica lake select --raw /dados/bruto --out /dados/vigente --exclude excluir.txt
37
+
38
+ # 2. conversão em Parquet, por fonte e dataset, em processos separados; retoma de onde parou
39
+ quantilica lake build --input /dados/vigente --lake /dados/lake --workers 4 --memory 12GB
40
+
41
+ # 3. auditoria: rodapés, proveniência (sha256), cobertura, estrutura e leitores
42
+ quantilica lake audit --lake /dados/lake --input /dados/vigente --json-file auditoria.json
43
+ ```
44
+
45
+ - `select` só precisa do `quantilica-core`. `build` e `audit` usam o
46
+ `quantilica-analytics`, que entra com `pip install "quantilica-cli[lake]"`; sem ele
47
+ esses dois comandos avisam o que instalar e saem com código 1.
48
+ - `--exclude` e `--exceptions` aceitam um arquivo texto com um item por linha (linhas
49
+ vazias e iniciadas por `#` são ignoradas): `sha256` ou caminho relativo no `select`,
50
+ caminho relativo ou padrão `fnmatch` no `audit`.
51
+ - `build` sai com código 1 se alguma tarefa falhar, e com 130 se for interrompido
52
+ (Ctrl+C); rodar de novo retoma e `--retry-errors` refaz só o que falhou. O andamento
53
+ sai em stderr.
54
+ - `audit` sai com 0 se o lake for aprovado e com 1 se houver achados. `--json` imprime
55
+ o relatório em JSON no stdout (o andamento fica em stderr); `--json-file ARQ` o grava.
56
+ - `--ledger ARQ` (opcional, só em `audit`) confere a proveniência também contra uma
57
+ exportação do ledger; sem ele, a conferência usa o `sha256` dos manifestos ou do
58
+ próprio arquivo.
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "quantilica-cli"
3
- version = "0.12.0"
3
+ version = "0.14.0"
4
4
  description = "Unified CLI for Quantilica open data fetchers"
5
5
  readme = "README.md"
6
6
  authors = [{ name = "Komesu, D.K.", email = "daniel@dkko.me" }]
@@ -20,11 +20,15 @@ classifiers = [
20
20
  "Programming Language :: Python :: 3.13",
21
21
  ]
22
22
  dependencies = [
23
- "quantilica-core>=0.11.0",
23
+ "quantilica-core>=0.15.0",
24
24
  "rich>=13.0.0",
25
25
  "typer>=0.15.0",
26
26
  ]
27
27
 
28
+ [project.optional-dependencies]
29
+ # Motor de `quantilica lake build` e `quantilica lake audit`.
30
+ lake = ["quantilica-analytics>=0.8.0"]
31
+
28
32
  [project.scripts]
29
33
  quantilica = "quantilica.cli.cli:main"
30
34
 
@@ -14,6 +14,7 @@ from rich.table import Table
14
14
 
15
15
  from quantilica.cli import __version__
16
16
  from quantilica.cli.health import cmd_health
17
+ from quantilica.cli.lake import app as lake_app
17
18
  from quantilica.cli.manifests import app as manifests_app
18
19
  from quantilica.cli.sources import (
19
20
  app as sources_app,
@@ -33,6 +34,7 @@ app = typer.Typer(
33
34
  help="Quantilica — ferramentas de dados abertos brasileiros.",
34
35
  no_args_is_help=True,
35
36
  )
37
+ app.add_typer(lake_app, name="lake")
36
38
  app.add_typer(manifests_app, name="manifests")
37
39
  app.add_typer(sources_app, name="sources")
38
40