quantilica-cli 0.21.4__tar.gz → 0.23.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 (51) hide show
  1. quantilica_cli-0.23.0/.github/dependabot.yml +10 -0
  2. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/.github/workflows/test.yml +5 -4
  3. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/CHANGELOG.md +62 -1
  4. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/PKG-INFO +3 -3
  5. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/pyproject.toml +21 -4
  6. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/src/quantilica/cli/catalog.py +263 -10
  7. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/src/quantilica/cli/health.py +27 -5
  8. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/src/quantilica/cli/registry.py +170 -28
  9. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/src/quantilica/cli/sources.py +286 -26
  10. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/tests/conftest.py +19 -0
  11. quantilica_cli-0.23.0/tests/renomes.py +42 -0
  12. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/tests/test_catalog_cli.py +1 -1
  13. quantilica_cli-0.23.0/tests/test_catalog_perfil.py +439 -0
  14. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/tests/test_registry_cli.py +9 -4
  15. quantilica_cli-0.23.0/tests/test_registry_v2.py +275 -0
  16. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/tests/test_sources.py +5 -0
  17. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/tests/test_sources_registro.py +42 -3
  18. quantilica_cli-0.23.0/tests/test_sources_registro_publico.py +336 -0
  19. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/.githooks/pre-commit +0 -0
  20. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/.githooks/pre-push +0 -0
  21. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/.github/workflows/public-hygiene.yml +0 -0
  22. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/.github/workflows/publish.yml +0 -0
  23. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/.gitignore +0 -0
  24. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/LICENSE +0 -0
  25. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/README.md +0 -0
  26. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/src/quantilica/cli/__init__.py +0 -0
  27. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/src/quantilica/cli/cli.py +0 -0
  28. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/src/quantilica/cli/docs.py +0 -0
  29. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/src/quantilica/cli/lake.py +0 -0
  30. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/src/quantilica/cli/manifests.py +0 -0
  31. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/src/quantilica/cli/sdk.py +0 -0
  32. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/src/quantilica/cli/ui.py +0 -0
  33. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/src/quantilica/py.typed +0 -0
  34. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/tests/__init__.py +0 -0
  35. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/tests/lake_build_fakes.py +0 -0
  36. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/tests/lake_fixtures.py +0 -0
  37. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/tests/test_catalog_registro.py +0 -0
  38. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/tests/test_catalog_sigla.py +0 -0
  39. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/tests/test_cli_apelidos.py +0 -0
  40. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/tests/test_docs_cli.py +0 -0
  41. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/tests/test_health.py +0 -0
  42. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/tests/test_lake_cli.py +0 -0
  43. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/tests/test_manifests.py +0 -0
  44. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/tests/test_package_hygiene.py +0 -0
  45. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/tests/test_sdk.py +0 -0
  46. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/tests/test_sdk_backfill.py +0 -0
  47. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/tests/test_sdk_force_probe.py +0 -0
  48. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/tests/test_sdk_mes_string.py +0 -0
  49. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/tests/test_sdk_onda_a2.py +0 -0
  50. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/tests/test_sdk_sync_exit.py +0 -0
  51. {quantilica_cli-0.21.4 → quantilica_cli-0.23.0}/tests/test_ui.py +0 -0
@@ -0,0 +1,10 @@
1
+ version: 2
2
+ updates:
3
+ - package-ecosystem: github-actions
4
+ directory: /
5
+ schedule:
6
+ interval: monthly
7
+ - package-ecosystem: uv
8
+ directory: /
9
+ schedule:
10
+ interval: monthly
@@ -32,15 +32,16 @@ jobs:
32
32
  run: uv python install ${{ matrix.python-version }}
33
33
 
34
34
  # O índice Quantilica (GitHub Pages) já deu flake de DNS no runner
35
- # (2026-08-23: rtn e inmet). Três tentativas removem o flake sem
35
+ # (2026-08-23: rtn e inmet) e responde 503 intermitente a pacote que não
36
+ # hospeda (2026-11-15). O pyproject declara o PyPI antes do índice
37
+ # ([[tool.uv.index]]); com first-index só quantilica-analytics passa por ele.
38
+ # Por isso não há --index aqui. Três tentativas removem o flake sem
36
39
  # esconder erro real de resolução.
37
40
  - name: Install dependencies
38
41
  shell: bash
39
42
  run: |
40
43
  for i in 1 2 3; do
41
- if uv sync --group dev --python ${{ matrix.python-version }} \
42
- --index https://index.quantilica.com/simple/ \
43
- --index-strategy unsafe-best-match; then
44
+ if uv sync --group dev --python ${{ matrix.python-version }}; then
44
45
  exit 0
45
46
  fi
46
47
  echo "::warning::uv sync falhou (tentativa $i/3); nova tentativa em 10s"
@@ -7,6 +7,67 @@ e este projeto adere ao [Semantic Versioning](https://semver.org/lang/pt-BR/).
7
7
 
8
8
  ## [Não lançado]
9
9
 
10
+
11
+ ## [0.23.0] - 2026-11-15
12
+ ### Adicionado
13
+ - `quantilica catalog sync` envia o perfil de colunas de cada dataset do lake na chave `perfis` do payload (`{"dataset_id", "perfil", "perfil_sha256"}`): por período, o total de linhas e os nulos de cada coluna, lidos dos rodapés Parquet por `quantilica.core.lake_profile.profile_from_lake`. O documento segue sem alteração, com o hash do core; só a coluna cujo nome o portal recusa sai do perfil (e do catálogo), com o hash recalculado. O perfil de um dataset nunca é partido entre lotes e viaja com as colunas dele. As colunas enviadas passam a ser a união das do perfil com as do primeiro Parquet, com o `dtype_arrow` do último período em que a coluna existe, porque o portal exige uma linha em `columns` para cada coluna do perfil. **O recurso exige o `quantilica-core` com `lake_profile`** (ainda sem release; o piso de versão não mudou): sem ele, o cli avisa e segue sem perfis. Dataset sem Parquet, sem partição `ano=` ou com perfil acima do limite do envio fica sem perfil, com aviso e o motivo.
14
+ - `quantilica catalog sync --dry-run` imprime, por dataset, o resumo do perfil (intervalo e número de períodos, colunas, eras de esquema e tamanho do documento); o JSON do payload deixa de repetir o perfil.
15
+ - Depois do envio, o cli informa quantos perfis o portal recebeu e quantos mudaram (`profiles` e `profiles_changed`; um segundo sync idêntico altera 0). Se o portal recusar o perfil de algum dataset (`counts.profiles_refused` e a lista `profiles_refused` da resposta), o cli avisa com o dataset e o motivo de cada um e termina com código 0: o resto do catálogo foi gravado. Com vários lotes, as listas de recusas são concatenadas.
16
+
17
+ ### Alterado
18
+ - Piso de `quantilica-core` sobe para `>=0.23.0` (o perfil de colunas usa `quantilica.core.lake_profile`).
19
+ - `quantilica catalog sync` deixa de enviar `percentual_nulos` (o portal calcula do perfil, junto com `periodo_inicio` e `periodo_fim`).
20
+ - O erro HTTP do envio mostra o `detail` do portal em vez do JSON cru (o 400 de perfil traz o dataset e o motivo).
21
+
22
+ ### Corrigido
23
+ - `quantilica catalog sync`: os Parquets de cada dataset são lidos em ordem de caminho. Sem o perfil de colunas, o esquema enviado vinha do primeiro arquivo na ordem do sistema de arquivos, que varia entre máquinas.
24
+ - CI: o pyproject declara o PyPI antes do índice Quantilica (`[[tool.uv.index]]`), e o workflow perde `--index` e `--index-strategy`. Com a estratégia padrão `first-index`, o `uv sync` só consulta o índice para o que não está no PyPI (`quantilica-analytics`) e deixa de receber o 503 intermitente que o GitHub Pages devolve a caminhos inexistentes.
25
+
26
+ ## [0.22.0] - 2026-11-14
27
+
28
+ ### Adicionado
29
+
30
+ - `quantilica registry export` exporta o registro v2: `module` (do entry point),
31
+ `repo` (de `[project.urls] Repository`/`Source`; ausente, assume
32
+ `https://github.com/Quantilica/<distribuição>` e avisa no stderr), `version`
33
+ e `lake_entry_point`, mais o `sha256` do conteúdo. Os campos da v1 seguem com
34
+ o mesmo nome e formato.
35
+ - `registry export --ecossistema registro.toml` junta a camada dos fatos do
36
+ ecossistema (`docs_pasta`, `vitrine`, `ci_integracao`, `json_leve`, `mascote`,
37
+ `health_url`, `historico`), validada por
38
+ `quantilica.core.registry.carrega_registro_ecossistema`.
39
+ - `registry export --strict` também falha com distribuição fora da regra
40
+ `<id>-fetcher` que o `historico` não explica e, com `--ecossistema`, com
41
+ fetcher sem seção no arquivo.
42
+ - `registro_publico()`: baixa `index.quantilica.com/registry.json`, confere o
43
+ `sha256` e guarda em `~/.cache/quantilica/registry.json` (validade de 24 h;
44
+ vencido e sem rede, vale o cache). `--refresh` em `install`, `uninstall` e
45
+ `doctor` ignora o cache. A escrita é atômica (arquivo temporário único e
46
+ `os.replace`). Depois de uma falha de rede, um marcador `registry.fail` ao
47
+ lado do cache evita nova tentativa por 10 min, para que cada processo (em
48
+ especial o `quantilica health`) não espere o timeout de 5 s; `--refresh`
49
+ ignora o marcador.
50
+ - O registro público só é aceito com `version` 1 ou 2; qualquer outra conta como
51
+ "sem registro" (vale o cache e, depois, a reserva offline).
52
+
53
+ ### Alterado
54
+
55
+ - Piso de dependência `quantilica-core>=0.21.0` (e no extra `docs`): o cli importa
56
+ `IdentidadePacote` e o registro v2 do core 0.21.0.
57
+ - `resolve_dist` consulta, nesta ordem, o fetcher instalado, o registro público
58
+ (id, apelidos e ids do `historico`) e a reserva offline. `SOURCES_REGISTRY`
59
+ virou `_RESERVA_OFFLINE` (o nome antigo segue como alias), congelada: não
60
+ recebe entradas novas.
61
+ - `resolve_dist` de um nome antigo de distribuição renomeada (`sidra-fetcher`)
62
+ agora resolve para a nova (`ibge-sidra-fetcher`), com aviso no stderr. Antes
63
+ passava como veio, e `install` e `doctor` discordavam (ambos migram para a
64
+ nova). As wheels congeladas continuam no índice para reprodução.
65
+ - `DISTRIBUICOES_RENOMEADAS` passa a ser a reserva; os renomes vêm do
66
+ `historico` do registro público (`distribuicoes_renomeadas()`).
67
+ - `quantilica health` sonda os `health_url` do registro público (nome da sonda =
68
+ id do fetcher); `HEALTH_SOURCES` é a reserva, usada sem registro ou quando ele
69
+ não declara nenhuma sonda.
70
+
10
71
  ## [0.21.4] - 2026-11-14
11
72
 
12
73
  ### Alterado
@@ -29,7 +90,7 @@ e este projeto adere ao [Semantic Versioning](https://semver.org/lang/pt-BR/).
29
90
 
30
91
  ### Corrigido
31
92
 
32
- - `quantilica catalog sync` envia `User-Agent: quantilica-cli/<versão>`: o Cloudflare do portal barrava o padrão do `urllib` (`Python-urllib`) com 403 (erro 1010).
93
+ - `quantilica catalog sync` envia `User-Agent: quantilica-cli/<versão>`: o portal recusava o padrão do `urllib` (`Python-urllib`) com 403.
33
94
 
34
95
  ## [0.21.0] - 2026-11-13
35
96
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: quantilica-cli
3
- Version: 0.21.4
3
+ Version: 0.23.0
4
4
  Summary: Unified CLI for Quantilica open data fetchers
5
5
  Author-email: "Komesu, D.K." <daniel@dkko.me>
6
6
  License-Expression: MIT
@@ -16,11 +16,11 @@ Classifier: Programming Language :: Python :: 3.12
16
16
  Classifier: Programming Language :: Python :: 3.13
17
17
  Classifier: Typing :: Typed
18
18
  Requires-Python: >=3.12
19
- Requires-Dist: quantilica-core>=0.20.0
19
+ Requires-Dist: quantilica-core>=0.23.0
20
20
  Requires-Dist: rich>=13.0.0
21
21
  Requires-Dist: typer>=0.15.0
22
22
  Provides-Extra: docs
23
- Requires-Dist: quantilica-core[docs]>=0.18.0; extra == 'docs'
23
+ Requires-Dist: quantilica-core[docs]>=0.23.0; extra == 'docs'
24
24
  Provides-Extra: lake
25
25
  Requires-Dist: pyarrow>=15.0.0; extra == 'lake'
26
26
  Requires-Dist: quantilica-analytics>=0.11.0; extra == 'lake'
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "quantilica-cli"
3
- version = "0.21.4"
3
+ version = "0.23.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,7 +20,7 @@ classifiers = [
20
20
  "Programming Language :: Python :: 3.13",
21
21
  ]
22
22
  dependencies = [
23
- "quantilica-core>=0.20.0",
23
+ "quantilica-core>=0.23.0",
24
24
  "rich>=13.0.0",
25
25
  "typer>=0.15.0",
26
26
  ]
@@ -29,7 +29,7 @@ dependencies = [
29
29
  # Motor de `quantilica lake build` e `quantilica lake audit`.
30
30
  lake = ["quantilica-analytics>=0.11.0", "pyarrow>=15.0.0"]
31
31
  # `quantilica docs`: verificação da documentação dos dados dos fetchers.
32
- docs = ["quantilica-core[docs]>=0.18.0"]
32
+ docs = ["quantilica-core[docs]>=0.23.0"]
33
33
 
34
34
  [project.scripts]
35
35
  quantilica = "quantilica.cli.cli:main"
@@ -57,10 +57,27 @@ packages = ["src/quantilica"]
57
57
  requires = ["hatchling>=1.27"]
58
58
  build-backend = "hatchling.build"
59
59
 
60
+ # Índices: o uv procura em ordem e para no primeiro que tem o pacote
61
+ # (index-strategy padrão first-index). O PyPI vem antes, então o índice
62
+ # Quantilica (GitHub Pages, que responde 503 intermitente a pacote que não
63
+ # hospeda) só é consultado para o que não está no PyPI (quantilica-analytics).
64
+ # Sem [tool.uv.sources]: no workspace do monorepo quantilica-analytics é membro
65
+ # e uma fonte de índice aqui quebraria o `uv run` da raiz.
66
+ [[tool.uv.index]]
67
+ name = "pypi"
68
+ url = "https://pypi.org/simple/"
69
+
70
+ [[tool.uv.index]]
71
+ name = "quantilica"
72
+ url = "https://index.quantilica.com/simple/"
73
+
60
74
  [tool.pytest.ini_options]
61
75
  testpaths = ["tests"]
62
76
  addopts = ["-p", "no:cacheprovider"]
63
- markers = ["indice_real: o teste usa a consulta real de publicação no índice"]
77
+ markers = [
78
+ "indice_real: o teste usa a consulta real de publicação no índice",
79
+ "registro_real: o teste exercita registro_publico (download e cache) em vez de isolá-lo",
80
+ ]
64
81
 
65
82
  [tool.ruff]
66
83
  line-length = 88
@@ -25,6 +25,7 @@ from typing import Annotated, Any
25
25
  import typer
26
26
  from quantilica.core.registry import FetcherInfo, RegistryError
27
27
  from rich.console import Console
28
+ from rich.markup import escape
28
29
  from rich.table import Table
29
30
 
30
31
  from quantilica.cli import __version__
@@ -194,6 +195,10 @@ class CatalogBuild:
194
195
  restricted: Counter[str] = field(default_factory=Counter)
195
196
  #: ``source_id`` do lake que o registro não conhece (ficam fora do payload).
196
197
  unknown: set[str] = field(default_factory=set)
198
+ #: Datasets do payload que ficaram sem perfil de colunas, com o motivo.
199
+ sem_perfil: dict[str, str] = field(default_factory=dict)
200
+ #: O ``quantilica-core`` instalado não tem ``lake_profile``: nenhum perfil.
201
+ perfil_indisponivel: bool = False
197
202
 
198
203
 
199
204
  def _sigla(orgao: str | None) -> str | None:
@@ -226,17 +231,102 @@ def _declared_text(desc_data: Mapping[str, Any], key: str) -> str | None:
226
231
  return value.strip() if isinstance(value, str) and value.strip() else None
227
232
 
228
233
 
234
+ def _lake_profile_module() -> Any | None:
235
+ """``quantilica.core.lake_profile``, ou ``None`` se o core instalado não o tem."""
236
+ try:
237
+ from quantilica.core import lake_profile
238
+ except ImportError:
239
+ return None
240
+ return lake_profile
241
+
242
+
243
+ def _nome_fora_do_perfil(nome: str) -> str | None:
244
+ """Por que o nome não pode seguir no perfil (o portal o recusaria).
245
+
246
+ Vale o critério do catálogo (:func:`_motivo_nome_invalido`) e, além dele,
247
+ espaços nas pontas e mais de 128 caracteres brutos: o portal confere o perfil
248
+ contra ``columns`` pelo nome exato.
249
+ """
250
+ motivo = _motivo_nome_invalido(nome)
251
+ if motivo:
252
+ return motivo
253
+ if nome != nome.strip():
254
+ return "espaços nas pontas"
255
+ if len(nome) > NOME_COLUNA_MAX:
256
+ return f"mais de {NOME_COLUNA_MAX} caracteres"
257
+ return None
258
+
259
+
260
+ def _perfil_do_dataset(
261
+ mod: Any, dataset_dir: Path, full_id: str
262
+ ) -> tuple[Any | None, str | None]:
263
+ """Perfil do dataset pelos rodapés Parquet: ``(LakeProfile, motivo_sem_perfil)``.
264
+
265
+ ``dataset_dir`` é ``<lake>/<fonte>/<dataset>``. O documento ``perfil`` segue
266
+ sem alteração, salvo a coluna cujo nome o portal recusa: sai do documento e o
267
+ hash é recalculado (o portal confere o perfil contra ``columns``, onde essa
268
+ coluna também não entra).
269
+ """
270
+ try:
271
+ prof = mod.profile_from_lake(
272
+ dataset_dir.parent.parent, dataset_dir.parent.name, dataset_dir.name
273
+ )
274
+ except FileNotFoundError:
275
+ return None, "sem arquivo Parquet"
276
+ except (ValueError, ImportError) as exc:
277
+ return None, str(exc)
278
+ except Exception as exc: # rodapé ilegível, arquivo corrompido
279
+ return None, f"falha ao ler os rodapés: {exc}"
280
+
281
+ invalidos = {
282
+ nome: motivo
283
+ for nome in prof.perfil["colunas"]
284
+ if (motivo := _nome_fora_do_perfil(nome))
285
+ }
286
+ if invalidos:
287
+ logger.warning(
288
+ "%s: %d coluna(s) fora do perfil por nome inválido (%s).",
289
+ full_id,
290
+ len(invalidos),
291
+ ", ".join(sorted(set(invalidos.values()))),
292
+ )
293
+ perfil = {
294
+ **prof.perfil,
295
+ "colunas": {
296
+ n: c for n, c in prof.perfil["colunas"].items() if n not in invalidos
297
+ },
298
+ }
299
+ prof = mod.LakeProfile(
300
+ perfil,
301
+ [c for c in prof.colunas if c["nome"] not in invalidos],
302
+ mod.perfil_sha256(perfil),
303
+ )
304
+ tamanho = _tamanho_json(prof.perfil)
305
+ if tamanho > LOTE_MAX_BYTES:
306
+ return None, f"perfil de {tamanho} bytes não cabe num envio"
307
+ return prof, None
308
+
309
+
229
310
  def _extract_dataset_metadata(
230
311
  descriptor_path: Path,
231
312
  sample_size: int = 20,
232
313
  lake_root: Path | None = None,
233
314
  registry: Registry | None = None,
315
+ profile_mod: Any | None = None,
234
316
  ) -> dict[str, Any] | None:
235
317
  """Extrai metadados, colunas e amostras de um _dataset.json e seus Parquets.
236
318
 
237
319
  O ``source_id`` do descritor é resolvido contra ``registry`` (apelido vira
238
320
  id canônico). O resultado traz ``restrita`` (fonte de redistribuição
239
321
  restrita) e ``conhecida`` (``source_id`` presente no registro).
322
+
323
+ Com ``profile_mod`` (``quantilica.core.lake_profile``) o resultado traz também
324
+ ``perfil`` (o item de ``perfis`` do payload) ou ``sem_perfil`` (o motivo). As
325
+ colunas passam a ser a união das colunas do perfil com as do primeiro Parquet
326
+ (o portal exige uma linha em ``columns`` para cada coluna do perfil); o
327
+ ``dtype_arrow`` do perfil vale (é o do último período em que a coluna existe).
328
+ ``percentual_nulos`` e o período de cada coluna não são enviados: o portal os
329
+ calcula do perfil.
240
330
  """
241
331
  try:
242
332
  desc_text = descriptor_path.read_text(encoding="utf-8")
@@ -255,7 +345,7 @@ def _extract_dataset_metadata(
255
345
  restricted = info is not None and info.redistribuicao == "restrita"
256
346
 
257
347
  dataset_dir = descriptor_path.parent
258
- parquet_files = list(dataset_dir.rglob("*.parquet"))
348
+ parquet_files = sorted(dataset_dir.rglob("*.parquet"))
259
349
  total_arquivos = len(parquet_files)
260
350
  total_bytes = sum(f.stat().st_size for f in parquet_files)
261
351
  total_rows = _count_rows(parquet_files)
@@ -282,13 +372,21 @@ def _extract_dataset_metadata(
282
372
  "dtype_arrow": partition_types.get(p_key, "Utf8"),
283
373
  "eh_particao_hive": True,
284
374
  "eh_chave_cruzamento": False,
285
- "percentual_nulos": 0.0,
286
375
  "descricao": f"Chave de partição Hive ({p_key})",
287
376
  "display_order": order,
288
377
  }
289
378
  )
290
379
  order += 1
291
380
 
381
+ perfil_item: dict[str, Any] | None = None
382
+ sem_perfil: str | None = None
383
+ prof = None
384
+ if profile_mod is not None:
385
+ prof, sem_perfil = _perfil_do_dataset(profile_mod, dataset_dir, full_id)
386
+ dtype_do_perfil = (
387
+ {c["nome"]: c["dtype_arrow"] for c in prof.colunas} if prof else {}
388
+ )
389
+
292
390
  sample_rows: list[dict[str, Any]] = []
293
391
  schema_arrow_json: dict[str, Any] = {}
294
392
 
@@ -329,10 +427,11 @@ def _extract_dataset_metadata(
329
427
  {
330
428
  "dataset_id": full_id,
331
429
  "nome": field.name,
332
- "dtype_arrow": str(field.type),
430
+ "dtype_arrow": dtype_do_perfil.get(
431
+ field.name, str(field.type)
432
+ ),
333
433
  "eh_particao_hive": False,
334
434
  "eh_chave_cruzamento": False,
335
- "percentual_nulos": 0.0,
336
435
  "descricao": None,
337
436
  "display_order": order,
338
437
  }
@@ -358,6 +457,29 @@ def _extract_dataset_metadata(
358
457
  exc,
359
458
  )
360
459
 
460
+ if prof is not None:
461
+ presentes = {c["nome"] for c in columns}
462
+ for c in prof.colunas:
463
+ if c["nome"] in presentes:
464
+ continue
465
+ columns.append(
466
+ {
467
+ "dataset_id": full_id,
468
+ "nome": c["nome"],
469
+ "dtype_arrow": c["dtype_arrow"],
470
+ "eh_particao_hive": False,
471
+ "eh_chave_cruzamento": False,
472
+ "descricao": None,
473
+ "display_order": order,
474
+ }
475
+ )
476
+ order += 1
477
+ perfil_item = {
478
+ "dataset_id": full_id,
479
+ "perfil": prof.perfil,
480
+ "perfil_sha256": prof.perfil_sha256,
481
+ }
482
+
361
483
  source_obj = _source_object(source_id, info, total_bytes)
362
484
 
363
485
  if lake_root:
@@ -401,6 +523,8 @@ def _extract_dataset_metadata(
401
523
  "sample": sample_obj,
402
524
  "restrita": restricted,
403
525
  "conhecida": info is not None,
526
+ "perfil": perfil_item,
527
+ "sem_perfil": sem_perfil,
404
528
  }
405
529
 
406
530
 
@@ -421,13 +545,28 @@ def build_catalog(
421
545
  datasets_list: list[dict[str, Any]] = []
422
546
  columns_list: list[dict[str, Any]] = []
423
547
  samples_list: list[dict[str, Any]] = []
548
+ perfis_list: list[dict[str, Any]] = []
424
549
  build = CatalogBuild(payload={})
425
550
 
426
551
  if not lake_dir.is_dir():
427
552
  logger.warning("Diretório do Lake %s não existe.", lake_dir)
428
- build.payload = {"sources": [], "datasets": [], "columns": [], "samples": []}
553
+ build.payload = {
554
+ "sources": [],
555
+ "datasets": [],
556
+ "columns": [],
557
+ "samples": [],
558
+ "perfis": [],
559
+ }
429
560
  return build
430
561
 
562
+ profile_mod = _lake_profile_module()
563
+ if profile_mod is None:
564
+ build.perfil_indisponivel = True
565
+ logger.warning(
566
+ "O quantilica-core instalado não tem lake_profile: nenhum perfil de "
567
+ "colunas será enviado. Atualize o quantilica-core."
568
+ )
569
+
431
570
  wanted = None
432
571
  if source_filter:
433
572
  found = registry.get(source_filter)
@@ -437,7 +576,11 @@ def build_catalog(
437
576
  # Busca todos os descritores _dataset.json
438
577
  for desc_path in sorted(lake_dir.rglob("_dataset.json")):
439
578
  meta = _extract_dataset_metadata(
440
- desc_path, sample_size=sample_size, lake_root=lake_dir, registry=registry
579
+ desc_path,
580
+ sample_size=sample_size,
581
+ lake_root=lake_dir,
582
+ registry=registry,
583
+ profile_mod=profile_mod,
441
584
  )
442
585
  if not meta:
443
586
  continue
@@ -465,6 +608,15 @@ def build_catalog(
465
608
  sources_dict.setdefault(src["id"], src)
466
609
  datasets_list.append(meta["dataset"])
467
610
  columns_list.extend(meta["columns"])
611
+ if meta["perfil"]:
612
+ perfis_list.append(meta["perfil"])
613
+ elif meta["sem_perfil"]:
614
+ build.sem_perfil[meta["dataset"]["id"]] = meta["sem_perfil"]
615
+ logger.warning(
616
+ "%s: sem perfil de colunas (%s).",
617
+ meta["dataset"]["id"],
618
+ meta["sem_perfil"],
619
+ )
468
620
  # Com --sample-size 0 a amostra não vai: enviar linhas vazias apagaria
469
621
  # no portal a amostra de um envio anterior.
470
622
  if sample_size > 0 and (
@@ -489,6 +641,7 @@ def build_catalog(
489
641
  "datasets": datasets_list,
490
642
  "columns": columns_list,
491
643
  "samples": samples_list,
644
+ "perfis": perfis_list,
492
645
  }
493
646
  return build
494
647
 
@@ -511,8 +664,8 @@ def send_catalog_payload(
511
664
  """Envia o payload via HTTP POST para o endpoint de sincronização do Portal."""
512
665
  url = f"{portal_url.rstrip('/')}/api/v2/admin/catalog/sync"
513
666
  body = json.dumps(payload, ensure_ascii=False, default=str).encode("utf-8")
514
- # User-Agent próprio: o Cloudflare do portal barra o padrão "Python-urllib/x"
515
- # (erro 1010, assinatura do navegador).
667
+ # User-Agent próprio: o portal recusa o padrão "Python-urllib/x"
668
+ # (assinatura do navegador).
516
669
  headers = {
517
670
  "Content-Type": "application/json",
518
671
  "Accept": "application/json",
@@ -527,6 +680,14 @@ def send_catalog_payload(
527
680
  return json.loads(resp.read().decode("utf-8"))
528
681
  except urllib.error.HTTPError as exc:
529
682
  err_body = exc.read().decode("utf-8", errors="replace")
683
+ # O portal responde {"detail": "..."} (com \\uXXXX no lugar dos acentos):
684
+ # o motivo, com o dataset, sai legível.
685
+ try:
686
+ detalhe = json.loads(err_body).get("detail")
687
+ except (ValueError, AttributeError):
688
+ detalhe = None
689
+ if isinstance(detalhe, str):
690
+ err_body = detalhe
530
691
  raise RuntimeError(
531
692
  f"Falha na sincronização HTTP {exc.code} em {url}: {err_body}"
532
693
  ) from exc
@@ -535,7 +696,7 @@ def send_catalog_payload(
535
696
 
536
697
 
537
698
  # O portal aceita até 100 MiB em /admin/catalog/sync (desde a 1.1.2; antes, 5 MiB)
538
- # e o Cloudflare corta em 100 MB. Lotes de até 90 MB: o lake inteiro (8,5 MB em
699
+ # e o proxy corta em 100 MB. Lotes de até 90 MB: o lake inteiro (8,5 MB em
539
700
  # 13/11/2026) vai num lote só, e a divisão por fonte fica para quando crescer. O
540
701
  # sync do portal é upsert: lotes não apagam nada do que veio nos anteriores.
541
702
  LOTE_MAX_BYTES = 90_000_000
@@ -621,6 +782,9 @@ def _somar_respostas(respostas: list[dict[str, Any]]) -> dict[str, Any]:
621
782
  total[chave] = valor
622
783
  elif isinstance(valor, (int, float)):
623
784
  total[chave] = total.get(chave, 0) + valor
785
+ elif isinstance(valor, list):
786
+ total.setdefault(chave, [])
787
+ total[chave] = [*total[chave], *valor]
624
788
  elif isinstance(valor, dict):
625
789
  sub = total.setdefault(chave, {})
626
790
  for k, v in valor.items():
@@ -633,6 +797,60 @@ def _somar_respostas(respostas: list[dict[str, Any]]) -> dict[str, Any]:
633
797
  return total
634
798
 
635
799
 
800
+ def _avisa_perfis_recusados(res: Any) -> None:
801
+ """Avisa, sem falhar, dos perfis que o portal recusou (o catálogo foi gravado).
802
+
803
+ O portal recusa só o perfil de um dataset (documento inválido, acima do teto de
804
+ células, coluna sem linha em ``columns``) e grava o resto.
805
+ ``counts.profiles_refused`` conta; ``profiles_refused`` traz ``dataset_id`` e
806
+ ``motivo``.
807
+ """
808
+ if not isinstance(res, dict):
809
+ return
810
+ contagem = res.get("counts")
811
+ recusados = res.get("profiles_refused")
812
+ n = contagem.get("profiles_refused", 0) if isinstance(contagem, dict) else 0
813
+ itens = [r for r in recusados if isinstance(r, dict)] if recusados else []
814
+ if not n and not itens:
815
+ return
816
+ console.print(
817
+ f"[yellow]Aviso: o portal recusou {n or len(itens)} perfil(is) de colunas; "
818
+ "o resto do catálogo foi gravado.[/yellow]"
819
+ )
820
+ for r in itens:
821
+ console.print(
822
+ f"[yellow] - Perfil recusado: {escape(str(r.get('dataset_id')))}: "
823
+ f"{escape(str(r.get('motivo')))}[/yellow]"
824
+ )
825
+
826
+
827
+ def _tabela_de_perfis(perfis: list[dict[str, Any]]) -> Table:
828
+ """Resumo por dataset do que seria enviado: períodos, colunas, eras e tamanho."""
829
+ mod = _lake_profile_module()
830
+ tabela = Table(title="Perfis de colunas (--dry-run)", show_header=True)
831
+ tabela.add_column("Dataset", style="cyan")
832
+ tabela.add_column("Períodos")
833
+ tabela.add_column("Colunas", justify="right")
834
+ tabela.add_column("Eras", justify="right")
835
+ tabela.add_column("Tamanho", justify="right")
836
+ for item in perfis:
837
+ doc = item["perfil"]
838
+ periodos = doc["periodos"]
839
+ intervalo = (
840
+ f"{periodos[0]} a {periodos[-1]}" if len(periodos) > 1 else periodos[0]
841
+ )
842
+ unidade = "meses" if doc["granularidade"] == "mensal" else "anos"
843
+ eras = len(mod.derivar_eras(doc)) if mod is not None else 0
844
+ tabela.add_row(
845
+ item["dataset_id"],
846
+ f"{intervalo} ({len(periodos)} {unidade})",
847
+ str(len(doc["colunas"])),
848
+ str(eras),
849
+ f"{_tamanho_json(item) / 1024:.1f} KiB",
850
+ )
851
+ return tabela
852
+
853
+
636
854
  @app.command("sync")
637
855
  def cmd_catalog_sync(
638
856
  lake_dir: Annotated[
@@ -730,6 +948,7 @@ def cmd_catalog_sync(
730
948
  datasets_count = len(payload.get("datasets", []))
731
949
  columns_count = len(payload.get("columns", []))
732
950
  samples_count = len(payload.get("samples", []))
951
+ perfis = payload.get("perfis", [])
733
952
 
734
953
  table = Table(title="Metadados Extraídos para Sincronização", show_header=True)
735
954
  table.add_column("Entidade", style="cyan")
@@ -738,6 +957,8 @@ def cmd_catalog_sync(
738
957
  table.add_row("Datasets Parquet", str(datasets_count))
739
958
  table.add_row("Colunas e Chaves", str(columns_count))
740
959
  table.add_row("Amostras de Dados", str(samples_count))
960
+ table.add_row("Perfis de colunas", str(len(perfis)))
961
+ table.add_row("Datasets sem perfil", str(len(build.sem_perfil)))
741
962
  table.add_row(
742
963
  "Deixados de fora (redistribuição restrita)",
743
964
  str(sum(build.restricted.values())),
@@ -755,12 +976,37 @@ def cmd_catalog_sync(
755
976
  + ", ".join(sorted(build.unknown))
756
977
  )
757
978
 
979
+ if build.perfil_indisponivel:
980
+ console.print(
981
+ "[yellow]O quantilica-core instalado não tem lake_profile:[/yellow] "
982
+ "nenhum perfil de colunas será enviado. Atualize o quantilica-core."
983
+ )
984
+ if build.sem_perfil:
985
+ mostrados = sorted(build.sem_perfil.items())[:20]
986
+ console.print(
987
+ "[yellow]Sem perfil de colunas:[/yellow] "
988
+ + "; ".join(f"{k} ({v})" for k, v in mostrados)
989
+ + (
990
+ f"; e mais {len(build.sem_perfil) - len(mostrados)}"
991
+ if len(build.sem_perfil) > len(mostrados)
992
+ else ""
993
+ )
994
+ )
995
+
758
996
  if dry_run:
759
997
  console.print(
760
998
  "[yellow]Modo --dry-run ativo:[/yellow] nenhum dado enviado para o portal."
761
999
  )
1000
+ if perfis:
1001
+ console.print(_tabela_de_perfis(perfis))
1002
+ # Os perfis saem no resumo acima, não no JSON (podem ter megabytes).
762
1003
  console.print_json(
763
- json.dumps(payload, ensure_ascii=False, indent=2, default=str)
1004
+ json.dumps(
1005
+ {k: v for k, v in payload.items() if k != "perfis"},
1006
+ ensure_ascii=False,
1007
+ indent=2,
1008
+ default=str,
1009
+ )
764
1010
  )
765
1011
  return
766
1012
 
@@ -789,6 +1035,13 @@ def cmd_catalog_sync(
789
1035
  console.print(
790
1036
  f"[green]✓ Catálogo sincronizado com sucesso![/green] Resposta: {res}"
791
1037
  )
1038
+ contagem = res.get("counts") if isinstance(res, dict) else None
1039
+ if isinstance(contagem, dict) and "profiles" in contagem:
1040
+ console.print(
1041
+ f"Perfis de colunas: {contagem['profiles']} recebidos, "
1042
+ f"{contagem.get('profiles_changed', 0)} alterados."
1043
+ )
1044
+ _avisa_perfis_recusados(res)
792
1045
  except Exception as exc:
793
1046
  err_console.print(f"[red]Erro ao sincronizar catálogo:[/red] {exc}")
794
1047
  raise typer.Exit(code=1) from exc