quantilica-cli 0.3.2__tar.gz → 0.8.0__tar.gz

quantilica_cli-0.8.0/.githooks/pre-push

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Barra o push se a árvore inteira não passar em lint/format.
+#
+# Complementa o pre-commit (que só vê .py staged): pega dívida de lint
+# pré-existente e commits que não tocam Python — foi assim que E501 dos
+# sweeps de 2026-08-14 ficou vermelho no CI por semanas e um commit de
+# pyproject re-ativou CI vermelho no inmet (2026-08-31).
+#
+# Instalação (uma vez por clone): git config core.hooksPath .githooks
+# (o bootstrap.sh faz isso automaticamente).
+set -euo pipefail
+
+cd "$(git rev-parse --show-toplevel)"
+
+[ -d src ] || exit 0
+if [ -d tests ]; then
+    TARGETS="src/ tests/"
+else
+    TARGETS="src/"
+fi
+
+if ! uv run --no-sync ruff --version >/dev/null 2>&1; then
+    echo "pre-push: ruff indisponível no ambiente — rodando uv sync --group dev" >&2
+    uv sync --group dev
+fi
+
+uv run --no-sync ruff check ${TARGETS}
+uv run --no-sync ruff format --check ${TARGETS}
+
+echo "pre-push: lint/format da árvore OK."

quantilica_cli-0.8.0/.github/workflows/test.yml

@@ -0,0 +1,55 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      # O índice Quantilica (GitHub Pages) já deu flake de DNS no runner
+      # (2026-08-23: rtn e inmet). Três tentativas removem o flake sem
+      # esconder erro real de resolução.
+      - name: Install dependencies
+        run: |
+          for i in 1 2 3; do
+            if uv sync --group dev --python ${{ matrix.python-version }} \
+                --index https://index.quantilica.com/simple/ \
+                --index-strategy unsafe-best-match; then
+              exit 0
+            fi
+            echo "::warning::uv sync falhou (tentativa $i/3); nova tentativa em 10s"
+            sleep 10
+          done
+          exit 1
+
+      # Cada `uv run` sem --no-sync re-resolve o lockfile virtual e REMOVE os
+      # extras instalados no passo de sync acima (polars/openpyxl já caíram
+      # assim: anp 2026-08-29). Todos os passos usam --no-sync.
+      - name: Lint with ruff
+        run: |
+          uv run --no-sync ruff check src/ tests/
+          uv run --no-sync ruff format --check src/ tests/
+
+      - name: Run tests
+        run: uv run --no-sync pytest

quantilica_cli-0.8.0/CHANGELOG.md

@@ -0,0 +1,105 @@
+# Changelog
+
+Todas as mudanças notáveis deste projeto serão documentadas neste arquivo.
+
+O formato segue [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/),
+e este projeto adere ao [Semantic Versioning](https://semver.org/lang/pt-BR/).
+
+## [0.8.0] - 2026-10-03
+
+Onda A.2 do plano `2026-10-03-padronizacao-core-e-consolidacao-fetchers` —
+decorators de ciclo de vida no SDK (`quantilica.cli.sdk`) e abstração de
+pré-visualização tabular de sincronização.
+
+### Adicionado
+- `FetcherApp.command_convert(func)`: decorator que registra o subcomando
+  `convert` com flags canônicas (`-i/--input`, `-o/--output`, `--verbose`,
+  padrões derivados de `default_output`). Configura logging Rich, trata
+  `ImportError` graciosamente (sugerindo `pip install {nome}[analysis]`,
+  saída com código 1) e exibe confirmação com check verde.
+- `FetcherApp.command_pipeline(func)`: decorator que registra o subcomando
+  `pipeline` encadeando sincronização (passo 1/2, via `sync`) e conversão
+  analítica (passo 2/2, via `func`). Opções: grupos, `--output`,
+  `--parquet-dir`, `--workers`, `--dry-run` (interrompe antes do passo 2) e
+  `--verbose`.
+- `FetcherApp.command_archive(func)`: decorator que registra o subcomando
+  `archive` para arquivamento histórico, com o mesmo padrão de flags e
+  tratamento gracioso de `ImportError`.
+- `SyncPlanItem`/`SyncPlan`: dataclasses (imutáveis) para planejamento de
+  sincronização, com `SyncPlan.render_table(console=None)` que renderiza uma
+  tabela Rich (`Dataset | Partição | Arquivo | URL`) e o sumário `Total: X
+  arquivos planejados. Y ignorados fora de cobertura.` Importados do
+  `quantilica.cli.sdk`.
+- `quantilica health`: subcomando de diagnóstico que faz sondas HTTP leves
+  (HEAD com fallback para GET, timeout padrão 5s) contra as fontes canônicas
+  do ecossistema — BCB SGS, SIDRA, Tesouro Direto, Comex e INMET — em
+  paralelo, com saída em tabela Rich (`Fonte | Estado | Latência | HTTP`) ou
+  em JSON estruturado via `--json`. Usa `quantilica.core.http` para o probe.
+
+## [0.7.0] - 2026-10-02
+
+Onda 2 — extensões do SDK (`quantilica.cli.sdk`) para eliminação de
+boilerplate nos fetchers (decisão
+`2026-10-02-padronizacao-e-deduplicacao-fetchers`).
+
+### Adicionado
+- `DataRepository` canônico no SDK (baseado em `StampedDataRepository` do core)
+  com `path_for_entry(entry, last_modified=...)`, estabelecendo a convenção
+  única de layout: `{dataset_id}/{slug}[@{partition}]@{YYYYMMDD}.{ext}`.
+- `default_path_builder(output_dir, entry, last_modified)`: path builder
+  canônico para fetchers que não fornecem um próprio.
+- `FetcherApp.attach_command(cmd_func, name=None, **kwargs)`: registro limpo de
+  subcomandos customizados (`convert`, `pipeline`, `archive`) sem subclassificar
+  e sobrescrever `_build_commands`.
+- `FetcherApp(build_default_commands=False)`: instancie o app sem os comandos
+  padrão `sync`/`list` (fim do padrão `def _build_commands(): pass`).
+- `make_resolve_groups(groups_dict, aliases_dict)`: helper que constrói
+  resolver de grupos/aliases para comandos customizados (dedup, ordem
+  declarada, erro em grupos desconhecidos); o comando `sync` padrão agora o
+  usa.
+- Commit `feat(sdk)`: `default_client()` já com `emulate_browser` e pooling
+  keep-alive por worker em `download_datasets` (anteriomente não documentado).
+
+### Alterado
+- `path_builder` no `FetcherApp` é agora opcional (default:
+  `default_path_builder`).
+
+## [0.3.2] - 2026-08-22
+
+### Corrigido
+- **Crítico:** wheels publicados desde a 0.3.0 vinham **sem os módulos do pacote** — o diretório `quantilica/cli/` não era incluído no build por configuração incorreta do hatchling (`sources` na seção global e `packages` apontando para o subpacote). Instalações via pip/uv reportavam sucesso, mas `import quantilica.cli` falhava em qualquer ambiente não-editable. Configuração realinhada ao padrão dos pacotes irmãos (`packages = ["src/quantilica"]` dentro de `[tool.hatch.build.targets.wheel]`).
+
+## [0.3.1] - 2026-08-22
+
+### Corrigido
+- `DEFAULT_INDEX_URL` apontado para `https://index.quantilica.com/simple/` — a URL anterior (`quantilica.com/quantilica-index/`) parou de ser servida quando o domínio passou ao portal, quebrando o `quantilica install` para fetchers fora do PyPI legado (detalhes no ADR de distribuição de 2026-08-22).
+- `install`/`uninstall` agora mesclam o registro remoto (`sources.json`) com o registro local, resolvendo também nomes canônicos do índice (ex.: `tesouro-direto`, além de `td`).
+
+## [0.3.0] - 2026-08-10
+
+### Adicionado
+- Extensão da `FetcherApp` (`sdk.py`) com suporte opcional para `FtpClient`.
+- Exposição do método `download_datasets` na `FetcherApp` para uso por comandos Typer customizados nos plugins.
+- Aceitação e passagem do parâmetro `aliases_dict` para personalização total dos subcomandos por fetcher.
+
+### Alterado
+- Padrão de metadados do pacote portado integralmente para a PEP 639 (licença) e PEP 561 (tipagem estática).
+
+## [0.2.2] - 2026-07-28
+*(Release retroativo não documentado)*
+
+## [0.2.0] - 2026-07-15
+*(Release retroativo não documentado)*
+
+## [0.1.0] - 2026-06-04
+
+Primeira entrada em formato Keep a Changelog; documenta o estado do pacote nesta
+versão.
+
+### Adicionado
+
+- CLI unificada `quantilica` que descobre e monta os fetchers instalados via
+  entry points `quantilica.fetchers`, sem depender diretamente dos pacotes de
+  fetcher.
+- Comando `list-sources` e montagem automática dos sub-apps Typer de cada fetcher
+  instalado (`quantilica <fonte> ...`).

{quantilica_cli-0.3.2 → quantilica_cli-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quantilica-cli
-Version: 0.3.2
+Version: 0.8.0
 Summary: Unified CLI for Quantilica open data fetchers
 Author-email: "Komesu, D.K." <daniel@dkko.me>
 License-Expression: MIT
@@ -16,7 +16,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
-Requires-Dist: quantilica-core>=0.4.0
+Requires-Dist: quantilica-core>=0.7.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: typer>=0.15.0
 Description-Content-Type: text/markdown

{quantilica_cli-0.3.2 → quantilica_cli-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "quantilica-cli"
-version = "0.3.2"
+version = "0.8.0"
 description = "Unified CLI for Quantilica open data fetchers"
 readme = "README.md"
 authors = [{ name = "Komesu, D.K.", email = "daniel@dkko.me" }]
@@ -20,7 +20,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "quantilica-core>=0.4.0",
+    "quantilica-core>=0.7.0",
     "rich>=13.0.0",
     "typer>=0.15.0",
 ]

{quantilica_cli-0.3.2 → quantilica_cli-0.8.0}/src/quantilica/cli/cli.py

@@ -13,6 +13,7 @@ from rich.logging import RichHandler
 from rich.table import Table
 
 from quantilica.cli import __version__
+from quantilica.cli.health import cmd_health
 from quantilica.cli.manifests import app as manifests_app
 from quantilica.cli.sources import (
     app as sources_app,
@@ -35,10 +36,11 @@ app = typer.Typer(
 app.add_typer(manifests_app, name="manifests")
 app.add_typer(sources_app, name="sources")
 
-# Adiciona comandos top-level install, uninstall e doctor
+# Adiciona comandos top-level install, uninstall, doctor e health
 app.command("install")(cmd_install)
 app.command("uninstall")(cmd_uninstall)
 app.command("doctor")(cmd_doctor)
+app.command("health")(cmd_health)
 
 console = Console()
 

quantilica_cli-0.8.0/src/quantilica/cli/health.py

@@ -0,0 +1,188 @@
+"""Comando `quantilica health` — sondas de disponibilidade das fontes.
+
+Realiza sondas HTTP leves (HEAD com fallback para GET) contra as fontes
+canônicas de dados do ecossistema Quantilica e reporta o resultado em
+tabela Rich ou JSON estruturado.
+"""
+
+from __future__ import annotations
+
+import concurrent.futures
+import json
+import time
+from typing import Annotated
+
+import httpx2
+import typer
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+DEFAULT_TIMEOUT = 5.0
+USER_AGENT = "quantilica-cli (health)"
+
+# Lista canônica de fontes sondadas (nome, URL de sonda leve).
+HEALTH_SOURCES: list[tuple[str, str]] = [
+    ("bcb", "https://api.bcb.gov.br/dados/serie/bcdata.sgs.1/dados?formato=json"),
+    ("sidra", "https://servicodados.ibge.gov.br/api/v3/calendario"),
+    (
+        "tesouro_direto",
+        "https://www.tesourotransparente.gov.br/ckan/api/3/action/package_search?rows=1",
+    ),
+    ("comex", "https://balanca.economia.gov.br"),
+    ("inmet", "https://apitempo.inmet.gov.br/estacoes"),
+]
+
+
+def _make_client(timeout: float) -> httpx2.Client:
+    """Cria o cliente HTTP usado pelas sondas.
+
+    Args:
+        timeout: Timeout (segundos) aplicado a cada requisição.
+
+    Returns:
+        Um httpx2.Client configurado com redirects e User-Agent da CLI.
+    """
+    return httpx2.Client(
+        timeout=timeout,
+        follow_redirects=True,
+        headers={"User-Agent": USER_AGENT},
+    )
+
+
+def _probe(client: httpx2.Client, name: str, url: str) -> dict[str, object]:
+    """Executa uma sonda HEAD (com fallback GET) contra uma fonte.
+
+    Args:
+        client: O cliente HTTP a ser usado.
+        name: Nome canônico da fonte.
+        url: URL alvo da sonda.
+
+    Returns:
+        Dicioário com name, url, status, http_status, latency_ms e error.
+    """
+    start = time.perf_counter()
+    try:
+        response = client.head(url)
+        # Muitos endpoints não implementam HEAD — fallback para GET leve.
+        if response.status_code >= 400:
+            response = client.get(url)
+        latency_ms = (time.perf_counter() - start) * 1000.0
+        if response.status_code < 400:
+            return {
+                "name": name,
+                "url": url,
+                "status": "ok",
+                "http_status": response.status_code,
+                "latency_ms": round(latency_ms, 1),
+                "error": None,
+            }
+        return {
+            "name": name,
+            "url": url,
+            "status": "falha",
+            "http_status": response.status_code,
+            "latency_ms": round(latency_ms, 1),
+            "error": f"HTTP {response.status_code}",
+        }
+    except Exception as exc:
+        latency_ms = (time.perf_counter() - start) * 1000.0
+        return {
+            "name": name,
+            "url": url,
+            "status": "falha",
+            "http_status": None,
+            "latency_ms": round(latency_ms, 1),
+            "error": f"{type(exc).__name__}: {exc}",
+        }
+
+
+def _run_probes(timeout: float, fail_fast: bool) -> list[dict[str, object]]:
+    """Sonda todas as fontes, em sequência (fail-fast) ou em paralelo.
+
+    Args:
+        timeout: Timeout por requisição, em segundos.
+        fail_fast: Se True, interrompe as sondas na primeira falha.
+
+    Returns:
+        A lista de resultados por fonte.
+    """
+    with _make_client(timeout=timeout) as client:
+        if fail_fast:
+            results = []
+            for name, url in HEALTH_SOURCES:
+                result = _probe(client, name, url)
+                results.append(result)
+                if result["status"] != "ok":
+                    break
+            return results
+
+        with concurrent.futures.ThreadPoolExecutor(
+            max_workers=len(HEALTH_SOURCES)
+        ) as pool:
+            futures = [
+                (name, pool.submit(_probe, client, name, url))
+                for name, url in HEALTH_SOURCES
+            ]
+            return [future.result() for _, future in futures]
+
+
+def _render_table(results: list[dict[str, object]]) -> None:
+    """Renderiza o relatório de health como tabela Rich.
+
+    Args:
+        results: Resultados das sondas.
+    """
+    table = Table(title="Health — fontes de dados", show_header=True)
+    table.add_column("Fonte", style="cyan")
+    table.add_column("Status")
+    table.add_column("Código", justify="right")
+    table.add_column("Latência (ms)", justify="right")
+
+    for r in results:
+        if r["status"] == "ok":
+            status = "[green]OK[/green]"
+        else:
+            status = "[red]FALHA[/red]"
+        code = str(r["http_status"]) if r["http_status"] is not None else "-"
+        latency = str(r["latency_ms"]) if r["latency_ms"] is not None else "-"
+        table.add_row(str(r["name"]), status, code, latency)
+
+    console.print(table)
+
+
+def cmd_health(
+    json_output: Annotated[
+        bool,
+        typer.Option(
+            "--json",
+            help="Saída em JSON estruturado em vez de tabela.",
+        ),
+    ] = False,
+    fail_fast: Annotated[
+        bool,
+        typer.Option(
+            "--fail-fast",
+            help="Interrompe as sondas na primeira falha e encerra com código 1.",
+        ),
+    ] = False,
+    timeout: Annotated[
+        float,
+        typer.Option(
+            "--timeout",
+            help="Timeout (s) aplicado a cada sonda HTTP.",
+        ),
+    ] = DEFAULT_TIMEOUT,
+) -> None:
+    """Verifica a disponibilidade das fontes de dados (sondas HTTP leves)."""
+    results = _run_probes(timeout, fail_fast)
+
+    if json_output:
+        status = "ok" if all(r["status"] == "ok" for r in results) else "degraded"
+        print(json.dumps({"status": status, "sources": results}))
+    else:
+        _render_table(results)
+
+    if fail_fast and any(r["status"] != "ok" for r in results):
+        raise typer.Exit(code=1)