quantilica-cli 0.24.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.
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/.github/workflows/public-hygiene.yml +2 -1
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/.github/workflows/publish.yml +14 -7
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/.github/workflows/test.yml +29 -2
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/CHANGELOG.md +24 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/PKG-INFO +37 -4
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/README.md +33 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/pyproject.toml +12 -5
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/src/quantilica/cli/catalog.py +65 -2
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/src/quantilica/cli/docs.py +21 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/src/quantilica/cli/lake.py +78 -3
- quantilica_cli-0.26.0/src/quantilica/cli/lake_estado.py +211 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/src/quantilica/cli/sdk.py +53 -22
- quantilica_cli-0.26.0/tests/fake_http_server.py +80 -0
- quantilica_cli-0.26.0/tests/test_lake_publicacao_cli.py +553 -0
- quantilica_cli-0.26.0/tests/test_sdk_politica_por_host.py +158 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/.githooks/pre-commit +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/.githooks/pre-push +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/.github/dependabot.yml +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/.gitignore +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/LICENSE +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/src/quantilica/cli/__init__.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/src/quantilica/cli/cli.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/src/quantilica/cli/health.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/src/quantilica/cli/manifests.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/src/quantilica/cli/registry.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/src/quantilica/cli/sources.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/src/quantilica/cli/ui.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/src/quantilica/py.typed +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/tests/__init__.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/tests/conftest.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/tests/lake_build_fakes.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/tests/lake_fixtures.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/tests/renomes.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/tests/test_catalog_cli.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/tests/test_catalog_perfil.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/tests/test_catalog_registro.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/tests/test_catalog_sigla.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/tests/test_cli_apelidos.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/tests/test_docs_cli.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/tests/test_health.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/tests/test_lake_cli.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/tests/test_manifests.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/tests/test_package_hygiene.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/tests/test_registry_cli.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/tests/test_registry_v2.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/tests/test_sdk.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/tests/test_sdk_backfill.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/tests/test_sdk_force_probe.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/tests/test_sdk_mes_string.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/tests/test_sdk_onda_a2.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/tests/test_sdk_sync_exit.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/tests/test_sources.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/tests/test_sources_registro.py +0 -0
- {quantilica_cli-0.24.0 → quantilica_cli-0.26.0}/tests/test_sources_registro_publico.py +0 -0
- {quantilica_cli-0.24.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@
|
|
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@
|
|
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,30 @@ 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`.
|
|
23
|
+
|
|
24
|
+
## [0.25.0] - 2026-11-16
|
|
25
|
+
### Alterado
|
|
26
|
+
|
|
27
|
+
- Piso de `quantilica-core` sobe para `>=0.25.0` (`HttpClient.share_host_state` e `max_concurrency` em `stream()`, de que o `download_datasets` depende para compartilhar a política por host entre as threads).
|
|
28
|
+
|
|
29
|
+
### Corrigido
|
|
30
|
+
|
|
31
|
+
- `FetcherApp.download_datasets` respeita a política por host do client do app (`HttpClient.host_policies`): os clients das threads passam a compartilhar as políticas e o estado do limitador (`min_interval`, pausa de `429` com `Retry-After`, `max_concurrency`) com o client do app, com `HttpClient.share_host_state`. Antes cada thread criava um client sem política e com limitador próprio, e o host recebia N vezes o ritmo configurado com N `--workers`; o fetcher precisava sobrescrever `download_datasets` para contornar. Sem política por host nada muda (clients independentes, mesmo paralelismo). Com a política, o teto de simultâneas vale também no `GET` do arquivo (`stream` do core), então quem declara só `min_interval` fica, pelo padrão `max_concurrency=4`, com no máximo 4 downloads simultâneos por host.
|
|
32
|
+
- Ao fim de `download_datasets` o `self.client` volta sempre ao client do app. Antes, com threads concorrentes, podia ficar um client de thread (já fechado) no lugar dele.
|
|
33
|
+
|
|
10
34
|
|
|
11
35
|
## [0.24.0] - 2026-11-15
|
|
12
36
|
### Alterado
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: quantilica-cli
|
|
3
|
-
Version: 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
|
|
@@ -16,14 +16,14 @@ 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.
|
|
19
|
+
Requires-Dist: quantilica-core>=0.25.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.
|
|
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.
|
|
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.
|
|
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" }]
|
|
@@ -20,22 +20,22 @@ classifiers = [
|
|
|
20
20
|
"Programming Language :: Python :: 3.13",
|
|
21
21
|
]
|
|
22
22
|
dependencies = [
|
|
23
|
-
"quantilica-core>=0.
|
|
23
|
+
"quantilica-core>=0.25.0",
|
|
24
24
|
"rich>=13.0.0",
|
|
25
25
|
"typer>=0.15.0",
|
|
26
26
|
]
|
|
27
27
|
|
|
28
28
|
[project.optional-dependencies]
|
|
29
29
|
# Motor de `quantilica lake build` e `quantilica lake audit`.
|
|
30
|
-
lake = ["quantilica-analytics>=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
|
-
docs = ["quantilica-core[docs]>=0.
|
|
32
|
+
docs = ["quantilica-core[docs]>=0.25.0"]
|
|
33
33
|
|
|
34
34
|
[project.scripts]
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|