quantilica-cli 0.25.0__tar.gz → 0.26.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 (55) hide show
  1. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/.github/workflows/public-hygiene.yml +2 -1
  2. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/.github/workflows/publish.yml +14 -7
  3. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/.github/workflows/test.yml +29 -2
  4. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/CHANGELOG.md +13 -0
  5. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/PKG-INFO +35 -2
  6. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/README.md +33 -0
  7. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/pyproject.toml +10 -3
  8. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/src/quantilica/cli/catalog.py +65 -2
  9. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/src/quantilica/cli/docs.py +21 -0
  10. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/src/quantilica/cli/lake.py +78 -3
  11. quantilica_cli-0.26.0/src/quantilica/cli/lake_estado.py +211 -0
  12. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/src/quantilica/cli/sdk.py +12 -9
  13. quantilica_cli-0.26.0/tests/test_lake_publicacao_cli.py +553 -0
  14. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/.githooks/pre-commit +0 -0
  15. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/.githooks/pre-push +0 -0
  16. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/.github/dependabot.yml +0 -0
  17. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/.gitignore +0 -0
  18. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/LICENSE +0 -0
  19. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/src/quantilica/cli/__init__.py +0 -0
  20. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/src/quantilica/cli/cli.py +0 -0
  21. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/src/quantilica/cli/health.py +0 -0
  22. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/src/quantilica/cli/manifests.py +0 -0
  23. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/src/quantilica/cli/registry.py +0 -0
  24. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/src/quantilica/cli/sources.py +0 -0
  25. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/src/quantilica/cli/ui.py +0 -0
  26. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/src/quantilica/py.typed +0 -0
  27. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/__init__.py +0 -0
  28. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/conftest.py +0 -0
  29. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/fake_http_server.py +0 -0
  30. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/lake_build_fakes.py +0 -0
  31. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/lake_fixtures.py +0 -0
  32. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/renomes.py +0 -0
  33. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/test_catalog_cli.py +0 -0
  34. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/test_catalog_perfil.py +0 -0
  35. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/test_catalog_registro.py +0 -0
  36. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/test_catalog_sigla.py +0 -0
  37. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/test_cli_apelidos.py +0 -0
  38. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/test_docs_cli.py +0 -0
  39. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/test_health.py +0 -0
  40. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/test_lake_cli.py +0 -0
  41. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/test_manifests.py +0 -0
  42. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/test_package_hygiene.py +0 -0
  43. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/test_registry_cli.py +0 -0
  44. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/test_registry_v2.py +0 -0
  45. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/test_sdk.py +0 -0
  46. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/test_sdk_backfill.py +0 -0
  47. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/test_sdk_force_probe.py +0 -0
  48. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/test_sdk_mes_string.py +0 -0
  49. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/test_sdk_onda_a2.py +0 -0
  50. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/test_sdk_politica_por_host.py +0 -0
  51. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/test_sdk_sync_exit.py +0 -0
  52. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/test_sources.py +0 -0
  53. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/test_sources_registro.py +0 -0
  54. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/test_sources_registro_publico.py +0 -0
  55. {quantilica_cli-0.25.0 → quantilica_cli-0.26.0}/tests/test_ui.py +0 -0
@@ -21,9 +21,10 @@ jobs:
21
21
  name: Termos internos
22
22
  runs-on: ubuntu-latest
23
23
  steps:
24
- - uses: actions/checkout@v4
24
+ - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
25
25
  with:
26
26
  fetch-depth: 0
27
+ persist-credentials: false
27
28
 
28
29
  - name: Escrever lista de termos
29
30
  run: |
@@ -5,21 +5,28 @@ on:
5
5
  tags:
6
6
  - "v*"
7
7
 
8
+ permissions:
9
+ contents: read
10
+
8
11
  jobs:
9
12
  build:
10
13
  name: Build distribution
11
14
  runs-on: ubuntu-latest
12
15
  steps:
13
- - uses: actions/checkout@v4
16
+ - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
17
+ with:
18
+ persist-credentials: false
14
19
 
15
20
  - name: Install uv
16
- uses: astral-sh/setup-uv@v5
21
+ uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
22
+ with:
23
+ enable-cache: false
17
24
 
18
25
  - name: Build sdist and wheel
19
26
  run: uv build
20
27
 
21
28
  - name: Upload build artifacts
22
- uses: actions/upload-artifact@v4
29
+ uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
23
30
  with:
24
31
  name: dist
25
32
  path: dist/
@@ -35,13 +42,13 @@ jobs:
35
42
  id-token: write
36
43
  steps:
37
44
  - name: Download build artifacts
38
- uses: actions/download-artifact@v4
45
+ uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
39
46
  with:
40
47
  name: dist
41
48
  path: dist/
42
49
 
43
50
  - name: Publish to TestPyPI
44
- uses: pypa/gh-action-pypi-publish@release/v1
51
+ uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
45
52
  with:
46
53
  repository-url: https://test.pypi.org/legacy/
47
54
  skip-existing: true
@@ -57,10 +64,10 @@ jobs:
57
64
  id-token: write
58
65
  steps:
59
66
  - name: Download build artifacts
60
- uses: actions/download-artifact@v4
67
+ uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
61
68
  with:
62
69
  name: dist
63
70
  path: dist/
64
71
 
65
72
  - name: Publish to PyPI
66
- uses: pypa/gh-action-pypi-publish@release/v1
73
+ uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
@@ -7,6 +7,9 @@ on:
7
7
  branches: [main]
8
8
  workflow_dispatch:
9
9
 
10
+ permissions:
11
+ contents: read
12
+
10
13
  jobs:
11
14
  test:
12
15
  name: Test (${{ matrix.os }}, Python ${{ matrix.python-version }})
@@ -21,10 +24,12 @@ jobs:
21
24
  python-version: "3.12"
22
25
 
23
26
  steps:
24
- - uses: actions/checkout@v4
27
+ - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
28
+ with:
29
+ persist-credentials: false
25
30
 
26
31
  - name: Install uv
27
- uses: astral-sh/setup-uv@v5
32
+ uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
28
33
  with:
29
34
  enable-cache: true
30
35
 
@@ -59,3 +64,25 @@ jobs:
59
64
 
60
65
  - name: Run tests
61
66
  run: uv run --no-sync pytest
67
+
68
+ - name: Type check with pyright
69
+ run: uv run --no-sync --with pyright pyright
70
+
71
+ zizmor:
72
+ name: Audit de workflows (zizmor)
73
+ runs-on: ubuntu-latest
74
+ permissions:
75
+ contents: read
76
+
77
+ steps:
78
+ - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
79
+ with:
80
+ persist-credentials: false
81
+
82
+ - name: Install uv
83
+ uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
84
+ with:
85
+ enable-cache: false
86
+
87
+ - name: Audit workflows with zizmor
88
+ run: uvx zizmor --no-online-audits --min-severity high .github/workflows
@@ -7,6 +7,19 @@ e este projeto adere ao [Semantic Versioning](https://semver.org/lang/pt-BR/).
7
7
 
8
8
  ## [Não lançado]
9
9
 
10
+ ## [0.26.0] - 2026-11-16
11
+
12
+ ### Alterado
13
+ - O extra `lake` exige `quantilica-analytics>=0.13.0`.
14
+
15
+ ### Adicionado
16
+ - `lake audit --somente-leitura --estado ARQ.json` (a auditoria de um lake montado só para leitura: não escreve nada nele, fonte com `_em-atualizacao.json` fica "em atualização" e não reprova, o `_build.json` é conferido) e `lake audit --limpar-marcador` (remove o marcador das fontes publicadas). `--estado` e `--json-file` apontando para dentro do lake são recusados com `--somente-leitura`. Exigem o `quantilica-analytics` que traz o marcador e o manifesto do build.
17
+ - `catalog sync` e `docs schema` ganham `--estado ARQ.json` (ou `QUANTILICA_LAKE_ESTADO`): só leem as fontes que o estado dá como `publicado` e cujo `build_id` bate com o `_build.json` atual, e pulam as demais com aviso (`docs schema`, que trata uma fonte só, sai com 1). Sem estado, as fontes com `_em-atualizacao.json` são puladas com aviso e o resto segue como antes, inclusive um lake sem `_build.json`. O `catalog sync` deixa de descer nas pastas das fontes puladas. Estado inexistente ou inválido é erro.
18
+ - Com estado, a leitura também confere o disco com o `_build.json` na hora de ler: cada Parquet listado existe com o mesmo tamanho e não há Parquet fora da lista; divergência pula a fonte com aviso. Isso cobre a janela em que a sincronização entrega arquivos de um build novo antes do marcador, ou tira o marcador antes dos Parquets. Quem lê deve sempre usar o estado (`QUANTILICA_LAKE_ESTADO`). Limitação: a conferência é por nome e tamanho, não pelo conteúdo.
19
+ - `lake audit --estado` exige `--somente-leitura` (exit 2). Com um `quantilica-analytics` que não conhece as opções novas, o comando diz para atualizá-lo (exit 2), sem traceback. A auditoria comum não passa nada novo ao analytics.
20
+
21
+ ### Alterado
22
+ - Verificação de tipos com `pyright` (`[tool.pyright]`, modo `basic`) zerada em `src`.
10
23
 
11
24
  ## [0.25.0] - 2026-11-16
12
25
  ### Alterado
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: quantilica-cli
3
- Version: 0.25.0
3
+ Version: 0.26.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
@@ -23,7 +23,7 @@ Provides-Extra: docs
23
23
  Requires-Dist: quantilica-core[docs]>=0.25.0; extra == 'docs'
24
24
  Provides-Extra: lake
25
25
  Requires-Dist: pyarrow>=15.0.0; extra == 'lake'
26
- Requires-Dist: quantilica-analytics>=0.11.0; extra == 'lake'
26
+ Requires-Dist: quantilica-analytics>=0.13.0; extra == 'lake'
27
27
  Description-Content-Type: text/markdown
28
28
 
29
29
  # quantilica-cli
@@ -84,3 +84,36 @@ quantilica lake audit --lake /dados/lake --input /dados/vigente --json-file audi
84
84
  - `--ledger ARQ` (opcional, só em `audit`) confere a proveniência também contra uma
85
85
  exportação do ledger; sem ele, a conferência usa o `sha256` dos manifestos ou do
86
86
  próprio arquivo.
87
+
88
+ ### Lake numa pasta sincronizada
89
+
90
+ Quando o lake mora numa pasta sincronizada por um cliente de nuvem, uma máquina
91
+ constrói e audita ali, e outra lê a mesma pasta sem nunca escrever nela. O cliente
92
+ envia os arquivos em ordem qualquer, então quem lê precisa de um critério próprio de
93
+ "publicado":
94
+
95
+ - `build` grava `<lake>/<fonte>/_em-atualizacao.json` antes de escrever a fonte, e
96
+ `<lake>/<fonte>/_build.json` (o manifesto: `build_id` e o tamanho de todos os
97
+ Parquets da fonte) ao fim de um build bem-sucedido. Um build que falha na fonte não
98
+ grava o manifesto e mantém o marcador.
99
+ - Na máquina que constrói, `audit --limpar-marcador` remove o marcador das fontes cuja
100
+ auditoria passa.
101
+ - Na máquina que lê, `audit --somente-leitura --estado ESTADO.json` não escreve nada
102
+ no lake e confere o manifesto (todo arquivo listado existe com o mesmo tamanho, e
103
+ não há Parquet fora dele). Por fonte, o `ESTADO.json` (fora do lake) recebe o
104
+ `build_id` auditado e o resultado: `publicado`, `em_atualizacao` (há marcador; não
105
+ reprova), `incompleto` (faltou arquivo, tamanho diferente, Parquet extra ou sem
106
+ `_build.json`) ou `falhou` (outro achado).
107
+ - `catalog sync` e `docs schema` aceitam `--estado ESTADO.json` (ou a variável
108
+ `QUANTILICA_LAKE_ESTADO`): só leem as fontes `publicado` cujo `build_id` é o do
109
+ `_build.json` atual **e** cujo disco bate com esse manifesto na hora da leitura (cada
110
+ Parquet listado existe com o mesmo tamanho e não há Parquet fora da lista; o cliente
111
+ de sincronização pode ter entregue arquivos de um build novo depois da auditoria).
112
+ As demais são puladas com aviso. Quem lê deve sempre usar o estado (de preferência
113
+ pela variável de ambiente): sem ele só o marcador protege a leitura, e um lake sem
114
+ `_build.json` segue como antes.
115
+ - `--estado` do `audit` só vale com `--somente-leitura` (exit 2 sem ele). O manifesto
116
+ só vale para o que o `build` escreveu: Parquets gravados por outros caminhos (os
117
+ `convert` dos fetchers) não o têm, e a auditoria `--somente-leitura` chama essa fonte
118
+ de `incompleto`. O manifesto compara nomes e tamanhos, não o conteúdo: um arquivo
119
+ reescrito com o mesmo tamanho passa despercebido.
@@ -56,3 +56,36 @@ quantilica lake audit --lake /dados/lake --input /dados/vigente --json-file audi
56
56
  - `--ledger ARQ` (opcional, só em `audit`) confere a proveniência também contra uma
57
57
  exportação do ledger; sem ele, a conferência usa o `sha256` dos manifestos ou do
58
58
  próprio arquivo.
59
+
60
+ ### Lake numa pasta sincronizada
61
+
62
+ Quando o lake mora numa pasta sincronizada por um cliente de nuvem, uma máquina
63
+ constrói e audita ali, e outra lê a mesma pasta sem nunca escrever nela. O cliente
64
+ envia os arquivos em ordem qualquer, então quem lê precisa de um critério próprio de
65
+ "publicado":
66
+
67
+ - `build` grava `<lake>/<fonte>/_em-atualizacao.json` antes de escrever a fonte, e
68
+ `<lake>/<fonte>/_build.json` (o manifesto: `build_id` e o tamanho de todos os
69
+ Parquets da fonte) ao fim de um build bem-sucedido. Um build que falha na fonte não
70
+ grava o manifesto e mantém o marcador.
71
+ - Na máquina que constrói, `audit --limpar-marcador` remove o marcador das fontes cuja
72
+ auditoria passa.
73
+ - Na máquina que lê, `audit --somente-leitura --estado ESTADO.json` não escreve nada
74
+ no lake e confere o manifesto (todo arquivo listado existe com o mesmo tamanho, e
75
+ não há Parquet fora dele). Por fonte, o `ESTADO.json` (fora do lake) recebe o
76
+ `build_id` auditado e o resultado: `publicado`, `em_atualizacao` (há marcador; não
77
+ reprova), `incompleto` (faltou arquivo, tamanho diferente, Parquet extra ou sem
78
+ `_build.json`) ou `falhou` (outro achado).
79
+ - `catalog sync` e `docs schema` aceitam `--estado ESTADO.json` (ou a variável
80
+ `QUANTILICA_LAKE_ESTADO`): só leem as fontes `publicado` cujo `build_id` é o do
81
+ `_build.json` atual **e** cujo disco bate com esse manifesto na hora da leitura (cada
82
+ Parquet listado existe com o mesmo tamanho e não há Parquet fora da lista; o cliente
83
+ de sincronização pode ter entregue arquivos de um build novo depois da auditoria).
84
+ As demais são puladas com aviso. Quem lê deve sempre usar o estado (de preferência
85
+ pela variável de ambiente): sem ele só o marcador protege a leitura, e um lake sem
86
+ `_build.json` segue como antes.
87
+ - `--estado` do `audit` só vale com `--somente-leitura` (exit 2 sem ele). O manifesto
88
+ só vale para o que o `build` escreveu: Parquets gravados por outros caminhos (os
89
+ `convert` dos fetchers) não o têm, e a auditoria `--somente-leitura` chama essa fonte
90
+ de `incompleto`. O manifesto compara nomes e tamanhos, não o conteúdo: um arquivo
91
+ reescrito com o mesmo tamanho passa despercebido.
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "quantilica-cli"
3
- version = "0.25.0"
3
+ version = "0.26.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" }]
@@ -27,7 +27,7 @@ dependencies = [
27
27
 
28
28
  [project.optional-dependencies]
29
29
  # Motor de `quantilica lake build` e `quantilica lake audit`.
30
- lake = ["quantilica-analytics>=0.11.0", "pyarrow>=15.0.0"]
30
+ lake = ["quantilica-analytics>=0.13.0", "pyarrow>=15.0.0"]
31
31
  # `quantilica docs`: verificação da documentação dos dados dos fetchers.
32
32
  docs = ["quantilica-core[docs]>=0.25.0"]
33
33
 
@@ -35,7 +35,7 @@ docs = ["quantilica-core[docs]>=0.25.0"]
35
35
  quantilica = "quantilica.cli.cli:main"
36
36
 
37
37
  [dependency-groups]
38
- dev = ["ruff>=0.9.0", "pytest>=8.0.0", "pyarrow>=15.0.0", "pyyaml>=6.0", "polars>=1.0"]
38
+ dev = ["ruff>=0.9.0", "pyright>=1.1.380", "pytest>=8.0.0", "pyarrow>=15.0.0", "pyyaml>=6.0", "polars>=1.0"]
39
39
 
40
40
  # Os fetchers são instalados independentemente pelo usuário — quantilica-cli
41
41
  # os descobre via entry points (grupo "quantilica.fetchers") sem dependência direta.
@@ -57,6 +57,9 @@ packages = ["src/quantilica"]
57
57
  requires = ["hatchling>=1.27"]
58
58
  build-backend = "hatchling.build"
59
59
 
60
+ [tool.uv]
61
+ required-version = ">=0.9"
62
+
60
63
  # Índices: o uv procura em ordem e para no primeiro que tem o pacote
61
64
  # (index-strategy padrão first-index). O PyPI vem antes, então o índice
62
65
  # Quantilica (GitHub Pages, que responde 503 intermitente a pacote que não
@@ -79,6 +82,10 @@ markers = [
79
82
  "registro_real: o teste exercita registro_publico (download e cache) em vez de isolá-lo",
80
83
  ]
81
84
 
85
+ [tool.pyright]
86
+ typeCheckingMode = "basic"
87
+ include = ["src"]
88
+
82
89
  [tool.ruff]
83
90
  line-length = 88
84
91
 
@@ -29,6 +29,11 @@ from rich.markup import escape
29
29
  from rich.table import Table
30
30
 
31
31
  from quantilica.cli import __version__
32
+ from quantilica.cli.lake_estado import (
33
+ ESTADO_ENV,
34
+ EstadoInvalido,
35
+ PoliticaDePublicacao,
36
+ )
32
37
 
33
38
  logger = logging.getLogger("quantilica.cli.catalog")
34
39
  console = Console()
@@ -199,6 +204,9 @@ class CatalogBuild:
199
204
  sem_perfil: dict[str, str] = field(default_factory=dict)
200
205
  #: O ``quantilica-core`` instalado não tem ``lake_profile``: nenhum perfil.
201
206
  perfil_indisponivel: bool = False
207
+ #: Fontes do lake que não foram lidas (em atualização, ou sem publicação
208
+ #: confirmada pelo estado), com o motivo.
209
+ puladas: dict[str, str] = field(default_factory=dict)
202
210
 
203
211
 
204
212
  def _sigla(orgao: str | None) -> str | None:
@@ -528,16 +536,50 @@ def _extract_dataset_metadata(
528
536
  }
529
537
 
530
538
 
539
+ def _descritores(
540
+ lake_dir: Path, politica: PoliticaDePublicacao, puladas: dict[str, str]
541
+ ) -> list[Path]:
542
+ """Os ``_dataset.json`` do lake, sem entrar nas fontes que a política recusa.
543
+
544
+ Só a pasta da raiz que é uma fonte (tem marcador de atualização ou um
545
+ ``<dataset>/_dataset.json``) entra em ``puladas``; ``ledger/`` e afins não.
546
+ """
547
+ achados: list[Path] = []
548
+ for dirpath, dirnames, filenames in os.walk(lake_dir):
549
+ aqui = Path(dirpath)
550
+ if aqui == lake_dir:
551
+ if "_dataset.json" in filenames:
552
+ achados.append(aqui / "_dataset.json")
553
+ for nome in sorted(dirnames):
554
+ motivo = politica.motivo(nome)
555
+ if motivo is None:
556
+ continue
557
+ dirnames.remove(nome)
558
+ pasta = lake_dir / nome
559
+ if (pasta / "_em-atualizacao.json").exists() or any(
560
+ pasta.glob("*/_dataset.json")
561
+ ):
562
+ puladas[nome] = motivo
563
+ continue
564
+ if "_dataset.json" in filenames:
565
+ achados.append(aqui / "_dataset.json")
566
+ return sorted(achados)
567
+
568
+
531
569
  def build_catalog(
532
570
  lake_dir: Path,
533
571
  source_filter: str | None = None,
534
572
  sample_size: int = 20,
535
573
  registry: Registry | None = None,
574
+ politica: PoliticaDePublicacao | None = None,
536
575
  ) -> CatalogBuild:
537
576
  """Varre o Lake e monta o payload, o que ficou de fora e o que é desconhecido.
538
577
 
539
578
  ``registry`` ausente carrega os fetchers instalados. Fontes de
540
- redistribuição restrita não entram no payload.
579
+ redistribuição restrita não entram no payload. ``politica`` decide quais
580
+ fontes podem ser lidas (marcador de atualização e arquivo de estado, ver
581
+ :mod:`quantilica.cli.lake_estado`); sem ela, só as com marcador ficam de fora.
582
+ As puladas vão em ``CatalogBuild.puladas``.
541
583
  """
542
584
  if registry is None:
543
585
  registry = load_registry()
@@ -573,8 +615,9 @@ def build_catalog(
573
615
  wanted = found.id if found else source_filter
574
616
 
575
617
  seen_ids: set[str] = set()
618
+ politica = politica or PoliticaDePublicacao(lake_dir)
576
619
  # Busca todos os descritores _dataset.json
577
- for desc_path in sorted(lake_dir.rglob("_dataset.json")):
620
+ for desc_path in _descritores(lake_dir, politica, build.puladas):
578
621
  meta = _extract_dataset_metadata(
579
622
  desc_path,
580
623
  sample_size=sample_size,
@@ -925,9 +968,26 @@ def cmd_catalog_sync(
925
968
  help="Exibe o payload JSON extraído sem enviar HTTP para o Portal.",
926
969
  ),
927
970
  ] = False,
971
+ estado: Annotated[
972
+ Path | None,
973
+ typer.Option(
974
+ "--estado",
975
+ envvar=ESTADO_ENV,
976
+ help="Arquivo de estado gravado por 'lake audit --somente-leitura "
977
+ "--estado': só lê as fontes publicadas e no mesmo build do "
978
+ "_build.json atual. Sem ele, só as fontes com _em-atualizacao.json "
979
+ "ficam de fora.",
980
+ dir_okay=False,
981
+ ),
982
+ ] = None,
928
983
  ) -> None:
929
984
  """Sincroniza os metadados do Universal Hive Parquet Lake com o Portal."""
930
985
  target_lake = (lake_dir or _default_lake_dir()).expanduser().resolve()
986
+ try:
987
+ politica = PoliticaDePublicacao.de(target_lake, estado)
988
+ except EstadoInvalido as exc:
989
+ err_console.print(f"[red]Erro:[/red] {escape(str(exc))}", highlight=False)
990
+ raise typer.Exit(1) from None
931
991
  console.print(
932
992
  f"[cyan]Varrendo Universal Hive Parquet Lake em:[/cyan] {target_lake}"
933
993
  )
@@ -949,6 +1009,7 @@ def cmd_catalog_sync(
949
1009
  source_filter=source,
950
1010
  sample_size=safe_sample_size,
951
1011
  registry=(registry := load_registry(registry_file)),
1012
+ politica=politica,
952
1013
  )
953
1014
  payload = build.payload
954
1015
  if not registry and not dry_run:
@@ -981,6 +1042,8 @@ def cmd_catalog_sync(
981
1042
  )
982
1043
  table.add_row("Fontes desconhecidas do registro", str(len(build.unknown)))
983
1044
  console.print(table)
1045
+ for aviso in politica.avisos(build.puladas):
1046
+ console.print(f"[yellow]Aviso:[/yellow] {escape(aviso)}", highlight=False)
984
1047
  if build.restricted:
985
1048
  console.print(
986
1049
  "[yellow]Fora do payload (restrita):[/yellow] "
@@ -27,6 +27,8 @@ import typer
27
27
  from rich.console import Console
28
28
  from rich.markup import escape
29
29
 
30
+ from quantilica.cli.lake_estado import ESTADO_ENV, EstadoInvalido, PoliticaDePublicacao
31
+
30
32
  app = typer.Typer(
31
33
  help="Documentação dos dados dos fetchers: verificar, gerar esquemas e fichas.",
32
34
  no_args_is_help=True,
@@ -200,12 +202,31 @@ def schema(
200
202
  help="Dataset a atualizar (repetível); padrão: todos os da fonte no lake",
201
203
  ),
202
204
  ] = None,
205
+ estado: Annotated[
206
+ Path | None,
207
+ typer.Option(
208
+ "--estado",
209
+ envvar=ESTADO_ENV,
210
+ help="Arquivo de estado gravado por 'lake audit --somente-leitura "
211
+ "--estado': a fonte só é lida se estiver publicada e no mesmo build do "
212
+ "_build.json atual. Sem ele, só a fonte com _em-atualizacao.json é "
213
+ "recusada.",
214
+ dir_okay=False,
215
+ ),
216
+ ] = None,
203
217
  ) -> None:
204
218
  """Grava os esquemas de referência (<id>.schema.json) lendo o lake."""
205
219
  docs = _import_docs()
206
220
  source_dir = lake / source_id
207
221
  if not source_dir.is_dir():
208
222
  raise _fail(f"a fonte '{source_id}' não está no lake: {source_dir} não existe.")
223
+ try:
224
+ motivo = PoliticaDePublicacao.de(lake, estado).motivo(source_id)
225
+ except EstadoInvalido as exc:
226
+ raise _fail(str(exc)) from None
227
+ if motivo is not None:
228
+ # Uma fonte só: pulá-la e sair com 0 pareceria sucesso sem ter gravado nada.
229
+ raise _fail(f"fonte {source_id} pulada, nada gravado: {motivo}.")
209
230
  wanted = dataset or sorted(
210
231
  p.name
211
232
  for p in source_dir.iterdir()
@@ -12,11 +12,12 @@ de modo que ``--help`` funciona sem ele.
12
12
  from __future__ import annotations
13
13
 
14
14
  import logging
15
+ import os
15
16
  from collections.abc import Iterator
16
17
  from contextlib import contextmanager
17
18
  from enum import StrEnum
18
19
  from pathlib import Path
19
- from typing import Annotated
20
+ from typing import Annotated, Any
20
21
 
21
22
  import typer
22
23
  from rich.console import Console
@@ -72,6 +73,11 @@ def _split_sources(value: str | None) -> list[str] | None:
72
73
  return sources
73
74
 
74
75
 
76
+ def _is_inside(path: Path, folder: Path) -> bool:
77
+ """Se ``path`` (existente ou não) fica dentro de ``folder``, links resolvidos."""
78
+ return Path(os.path.realpath(path)).is_relative_to(os.path.realpath(folder))
79
+
80
+
75
81
  def _read_list(path: Path) -> list[str]:
76
82
  """Lê um arquivo texto com um item por linha (vazias e ``#`` ignoradas)."""
77
83
  try:
@@ -271,7 +277,8 @@ def build(
271
277
  ) -> None:
272
278
  """Converte a visão vigente em Parquet; retoma uma execução interrompida."""
273
279
  try:
274
- from quantilica.analytics.lake_build import (
280
+ # extra opcional `lake`: ausente do ambiente de dev padrão
281
+ from quantilica.analytics.lake_build import ( # pyright: ignore[reportMissingImports]
275
282
  InsufficientDiskError,
276
283
  LakeBuildError,
277
284
  lake_build,
@@ -406,15 +413,72 @@ def audit(
406
413
  dir_okay=False,
407
414
  ),
408
415
  ] = None,
416
+ read_only: Annotated[
417
+ bool,
418
+ typer.Option(
419
+ "--somente-leitura",
420
+ help="Não escreve nada no lake (para um lake montado só para "
421
+ "leitura): fonte com _em-atualizacao.json fica 'em atualização' e "
422
+ "não reprova; fonte sem _build.json fica 'incompleta'",
423
+ ),
424
+ ] = False,
425
+ state: Annotated[
426
+ Path | None,
427
+ typer.Option(
428
+ "--estado",
429
+ help="Arquivo JSON (fora do lake) que recebe, por fonte, o build_id "
430
+ "auditado, o resultado (publicado, em_atualizacao, incompleto, "
431
+ "falhou) e a data; é o que os comandos de leitura consultam",
432
+ dir_okay=False,
433
+ ),
434
+ ] = None,
435
+ clear_marker: Annotated[
436
+ bool,
437
+ typer.Option(
438
+ "--limpar-marcador",
439
+ help="Remove o _em-atualizacao.json das fontes publicadas (única "
440
+ "escrita que a auditoria faz no lake; não vale com --somente-leitura)",
441
+ ),
442
+ ] = False,
409
443
  ) -> None:
410
444
  """Audita o lake; sai com 0 se aprovado e com 1 se houver achados."""
445
+ if state is not None and not read_only:
446
+ raise _fail(
447
+ "--estado só vale com --somente-leitura: o estado descreve o que a "
448
+ "máquina que lê enxerga, e a que constrói não o grava.",
449
+ EXIT_USAGE,
450
+ )
451
+ if read_only and clear_marker:
452
+ raise _fail(
453
+ "--limpar-marcador escreve no lake e não vale com --somente-leitura.",
454
+ EXIT_USAGE,
455
+ )
456
+ if read_only:
457
+ for flag, target in (("--estado", state), ("--json-file", json_file)):
458
+ if target is not None and _is_inside(target, lake):
459
+ raise _fail(
460
+ f"{flag} aponta para dentro do lake ({target}); com "
461
+ "--somente-leitura nada pode ser gravado ali.",
462
+ EXIT_USAGE,
463
+ )
411
464
  try:
412
- from quantilica.analytics.lake_audit import lake_audit
465
+ # extra opcional `lake`: ausente do ambiente de dev padrão
466
+ from quantilica.analytics.lake_audit import ( # pyright: ignore[reportMissingImports]
467
+ lake_audit,
468
+ )
413
469
  except ImportError as exc:
414
470
  raise _missing_analytics("audit", exc) from None
415
471
 
416
472
  wanted = _split_sources(sources)
417
473
  known = _read_list(exceptions) if exceptions is not None else ()
474
+ # Só o que foi pedido: a auditoria comum segue valendo com um analytics anterior.
475
+ publicacao: dict[str, Any] = {}
476
+ if read_only:
477
+ publicacao["read_only"] = True
478
+ if clear_marker:
479
+ publicacao["clear_marker"] = True
480
+ if state is not None:
481
+ publicacao["state"] = state
418
482
  try:
419
483
  with _log_to_stderr():
420
484
  report = lake_audit(
@@ -427,10 +491,21 @@ def audit(
427
491
  known_exceptions=known,
428
492
  rehash=rehash,
429
493
  workers=workers,
494
+ **publicacao,
430
495
  )
431
496
  except KeyboardInterrupt:
432
497
  err_console.print("[yellow]Interrompido.[/yellow]")
433
498
  raise typer.Exit(EXIT_INTERRUPTED) from None
499
+ except TypeError as exc:
500
+ # Um quantilica-analytics anterior não conhece as opções novas.
501
+ if publicacao and any(f"'{k}'" in str(exc) for k in publicacao):
502
+ raise _fail(
503
+ "o quantilica-analytics instalado não conhece "
504
+ "--somente-leitura/--estado/--limpar-marcador. Atualize-o: "
505
+ f"{ANALYTICS_HINT}",
506
+ EXIT_USAGE,
507
+ ) from None
508
+ raise
434
509
  except (OSError, ValueError) as exc:
435
510
  raise _fail(str(exc)) from exc
436
511