quantilica-cli 0.3.1__tar.gz → 0.7.0__tar.gz

quantilica_cli-0.7.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.7.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.7.0/CHANGELOG.md

@@ -0,0 +1,74 @@
+# 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.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.1 → quantilica_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quantilica-cli
-Version: 0.3.1
+Version: 0.7.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.1 → quantilica_cli-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "quantilica-cli"
-version = "0.3.1"
+version = "0.7.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",
 ]
@@ -43,11 +43,9 @@ dev = ["ruff>=0.9.0", "pytest>=8.0.0"]
 # [tool.hatch.metadata]
 # allow-direct-references = true
 
-[tool.hatch.build]
-sources = ["src"]
-
 [tool.hatch.build.targets.wheel]
-packages = ["src/quantilica/cli"]
+sources = ["src"]
+packages = ["src/quantilica"]
 
 [build-system]
 requires = ["hatchling>=1.27"]

{quantilica_cli-0.3.1 → quantilica_cli-0.7.0/src}/quantilica/cli/sdk.py

@@ -8,7 +8,8 @@ from __future__ import annotations
 import concurrent.futures
 import contextlib
 import datetime as dt
-from collections.abc import Callable
+import threading
+from collections.abc import Callable, Iterable
 from pathlib import Path
 from typing import Annotated, Any
 
@@ -17,6 +18,11 @@ from quantilica.core.exceptions import FetchError
 from quantilica.core.ftp import FtpClient
 from quantilica.core.http import HttpClient, HttpStatusError, ProgressCallback
 from quantilica.core.logging import get_logger
+from quantilica.core.storage import (
+    StampedDataRepository,
+    build_stamped_filename,
+    stamp_filename,
+)
 from rich.console import Group
 from rich.live import Live
 from rich.table import Table
@@ -37,23 +43,134 @@ def default_client() -> HttpClient:
     """Create a default HttpClient with standard configuration.
 
     Returns:
-        A pre-configured HttpClient instance.
+        A pre-configured HttpClient instance (browser-like WAF headers + pooling).
     """
     return HttpClient(
         timeout=180.0,
         verify=True,
         attempts=5,
         retry_base_delay=2.0,
-        headers={
-            "User-Agent": (
-                "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
-                "AppleWebKit/537.36 (KHTML, like Gecko) "
-                "Chrome/142.0.0.0 Safari/537.36"
-            ),
-        },
+        emulate_browser=True,
     )
 
 
+class DataRepository(StampedDataRepository):
+    """Canonical data repository layout shared by Quantilica fetchers.
+
+    Files are stored under ``{dataset_id}/`` directly, with stamped filenames
+    following the ecosystem convention ``{slug}[@{partition}]@{YYYYMMDD}.{ext}``
+    (see :func:`stamp_filename`). Entries follow the canonical SDK schema:
+    ``group``, ``id``, ``ext``, ``url``, and optional ``year``/``month``/
+    ``semester`` partition fields.
+    """
+
+    def path_for_entry(
+        self,
+        entry: dict[str, Any],
+        *,
+        last_modified: dt.date | None = None,
+    ) -> Path:
+        """Compute the local path for a dataset entry.
+
+        Args:
+            entry: Dataset entry dictionary (canonical SDK schema).
+            last_modified: The last modified date to stamp, or None.
+
+        Returns:
+            Path: The destination path for the entry.
+
+        Raises:
+            StorageError: If a required bucket key is empty or invalid.
+        """
+        dataset_id = str(entry.get("group") or entry.get("id") or "datasets")
+        ext = entry.get("ext")
+        if not ext:
+            tail = str(entry.get("url", "")).split("?")[0].rsplit("/", 1)[-1]
+            ext = tail.rsplit(".", 1)[-1] if "." in tail else "bin"
+
+        year = entry.get("year")
+        month = entry.get("month")
+        semester = entry.get("semester")
+        slug = str(entry.get("id") or dataset_id)
+
+        if year is not None and semester is not None:
+            filename = build_stamped_filename(
+                slug,
+                f"{year}-{semester:02d}",
+                ext=ext,
+                timestamp=last_modified,
+            )
+        elif year is not None and month is not None:
+            filename = build_stamped_filename(
+                slug,
+                f"{year}-{month:02d}",
+                ext=ext,
+                timestamp=last_modified,
+            )
+        elif year is not None:
+            filename = build_stamped_filename(
+                slug, year, ext=ext, timestamp=last_modified
+            )
+        else:
+            filename = stamp_filename(slug, ext, last_modified)
+
+        return self.dataset_path(dataset_id, filename)
+
+
+def default_path_builder(
+    output_dir: Path,
+    entry: dict[str, Any],
+    last_modified: dt.date | None = None,
+) -> Path:
+    """Canonical path builder used when a fetcher does not provide one.
+
+    Args:
+        output_dir: The root output directory.
+        entry: The dataset entry dictionary.
+        last_modified: The last modified date of the dataset.
+
+    Returns:
+        Path: The destination path for the entry.
+    """
+    return DataRepository(output_dir).path_for_entry(entry, last_modified=last_modified)
+
+
+def make_resolve_groups(
+    groups_dict: dict[str, dict[str, Any]],
+    aliases_dict: dict[str, list[str]],
+) -> Callable[[Iterable[str] | None], list[str]]:
+    """Build a resolver mapping group keys/aliases to canonical group IDs.
+
+    Args:
+        groups_dict: Dictionary of dataset groups and their metadata.
+        aliases_dict: Dictionary of alias mappings to dataset groups.
+
+    Returns:
+        Callable: A function receiving group keys and/or aliases (or None for
+        all groups) and returning the deduplicated canonical group IDs in
+        declaration order. Raises ValueError on unknown keys.
+    """
+    groups = list(groups_dict)
+    aliases = dict(aliases_dict)
+
+    def resolve(keys: Iterable[str] | None = None) -> list[str]:
+        resolved: list[str] = []
+        for key in groups if keys is None else keys:
+            expanded = (
+                list(aliases[key])
+                if key in aliases
+                else ([key] if key in groups_dict else [])
+            )
+            if not expanded:
+                raise ValueError(f"Grupo desconhecido: {key!r}")
+            for canon in expanded:
+                if canon not in resolved:
+                    resolved.append(canon)
+        return resolved
+
+    return resolve
+
+
 class FetcherApp:
     """Standard orchestrator for Quantilica fetchers.
 
@@ -63,9 +180,14 @@ class FetcherApp:
         groups_dict: Dictionary of dataset groups and their metadata.
         aliases_dict: Dictionary of alias mappings to dataset groups.
         list_datasets: Callback to list datasets given a group ID.
-        path_builder: Callback to build the destination path.
+        path_builder: Callback to build the destination path. If None, uses
+            :func:`default_path_builder` (canonical ``DataRepository`` layout).
         default_output: Default output directory path.
         client: HTTP or FTP client instance. Defaults to default_client().
+        build_default_commands: If True (default), registers the built-in
+            ``sync`` and ``list`` commands. Set to False to register only
+            custom commands via :meth:`attach_command`.
+        client: HTTP or FTP client instance. Defaults to default_client().
     """
 
     def __init__(
@@ -76,16 +198,18 @@ class FetcherApp:
         groups_dict: dict[str, dict[str, Any]],
         aliases_dict: dict[str, list[str]],
         list_datasets: Callable[[str], list[dict[str, Any]]],
-        path_builder: Callable[[Path, dict[str, Any], dt.date | None], Path],
+        path_builder: Callable[[Path, dict[str, Any], dt.date | None], Path]
+        | None = None,
         default_output: Path | None = None,
         client: HttpClient | FtpClient | None = None,
+        build_default_commands: bool = True,
     ):
         self.name = name
         self.help = help
         self.groups = groups_dict
         self.aliases = aliases_dict
         self.list_datasets = list_datasets
-        self.path_builder = path_builder
+        self.path_builder = path_builder or default_path_builder
         self.default_output = default_output or Path(
             f"/data/{name.replace('-fetcher', '')}"
         )
@@ -93,10 +217,31 @@ class FetcherApp:
 
         self.all_group_keys = list(self.groups.keys())
         self.all_keys = self.all_group_keys + list(self.aliases.keys())
+        self.resolve_groups = make_resolve_groups(groups_dict, aliases_dict)
 
         # O objeto typer principal
         self.app = typer.Typer(help=help)
-        self._build_commands()
+        if build_default_commands:
+            self._build_commands()
+
+    def attach_command(
+        self,
+        cmd_func: Callable[..., Any],
+        name: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Register a custom subcommand on the app.
+
+        Lets fetchers add subcommands (e.g. ``convert``, ``pipeline``,
+        ``archive``) cleanly, without subclassing and overriding
+        ``_build_commands``.
+
+        Args:
+            cmd_func: The Typer command function to register.
+            name: The command name. Defaults to the function name.
+            **kwargs: Extra options forwarded to ``typer.Typer.command()``.
+        """
+        self.app.command(name=name, **kwargs)(cmd_func)
 
     def _safe_head_date(self, url: str) -> dt.date | None:
         with contextlib.suppress(Exception):
@@ -208,7 +353,35 @@ class FetcherApp:
         errors: list[tuple[str, str]] = []
         pool = ProgressPool(workers=workers, file_prog=file_prog)
 
+        # Pooling por worker: cada thread mantém seu HttpClient com keep-alive.
+        thread_local = threading.local()
+        _worker_clients: list[HttpClient] = []
+
+        def _get_worker_client() -> HttpClient | FtpClient:
+            if isinstance(self.client, FtpClient):
+                return self.client
+            if not hasattr(thread_local, "client"):
+                # Reusa config do client canônico, mas com sessão persistente.
+                c = HttpClient(
+                    timeout=self.client.timeout,
+                    headers=dict(self.client.headers),
+                    follow_redirects=self.client.follow_redirects,
+                    attempts=self.client.attempts,
+                    retry_base_delay=self.client.retry_base_delay,
+                    verify=self.client.verify,
+                    limits=self.client.limits,
+                    emulate_browser=True,
+                )
+                c.__enter__()
+                thread_local.client = c
+                _worker_clients.append(c)
+            return thread_local.client  # type: ignore[return-value]
+
         def _worker(entry: dict[str, Any]) -> bool:
+            # Troca temporária do client para o da thread (com pooling).
+            worker_client = _get_worker_client()
+            prev = self.client
+            self.client = worker_client  # type: ignore[assignment]
             try:
                 eid = entry.get("id", "unknown")
                 with pool.acquire(description=f"[cyan]{eid}[/cyan]") as cb:
@@ -217,6 +390,8 @@ class FetcherApp:
             except Exception as exc:
                 errors.append((entry.get("id", "unknown"), str(exc)))
                 return False
+            finally:
+                self.client = prev
 
         with graceful_executor(max_workers=workers) as executor:
             try:
@@ -235,6 +410,10 @@ class FetcherApp:
             except KeyboardInterrupt:
                 console.print("\n[yellow]Interrompido.[/yellow]")
                 raise typer.Exit(130) from None
+            finally:
+                for c in _worker_clients:
+                    with contextlib.suppress(Exception):
+                        c.close()
 
         return downloaded, total, errors
 
@@ -265,16 +444,12 @@ class FetcherApp:
             setup_rich_logging(verbose, console=console)
             actual_output = output or self.default_output
 
-            target_groups: list[str] = []
-            for g in groups or self.all_group_keys:
-                expanded = self._expand_group(g)
-                if not expanded:
-                    console.print(f"[red]Grupo desconhecido: {g!r}[/red]")
-                    console.print(f"Grupos válidos: {', '.join(self.all_keys)}")
-                    raise typer.Exit(1)
-                for canon in expanded:
-                    if canon not in target_groups:
-                        target_groups.append(canon)
+            try:
+                target_groups = self.resolve_groups(groups)
+            except ValueError as exc:
+                console.print(f"[red]{exc}[/red]")
+                console.print(f"Grupos válidos: {', '.join(self.all_keys)}")
+                raise typer.Exit(1) from None
 
             entries = [e for g in target_groups for e in self.list_datasets(g)]
 

quantilica_cli-0.7.0/tests/test_sdk.py

@@ -0,0 +1,277 @@
+"""Testes unitários para quantilica.cli.sdk (Onda 2: FetcherApp melhorias)."""
+
+from __future__ import annotations
+
+import datetime as dt
+from pathlib import Path
+from typing import Annotated
+
+import pytest
+import typer
+from typer.testing import CliRunner
+
+from quantilica.cli.sdk import (
+    DataRepository,
+    FetcherApp,
+    default_path_builder,
+    make_resolve_groups,
+)
+
+runner = CliRunner()
+
+
+def _grouped(app: typer.Typer, name: str = "fd") -> typer.Typer:
+    """Emita o sub-app como um grupo nomeado.
+
+    Um `Typer` com apenas um comando é executado de forma plana; agrupar
+    garante uma invocação consistente nos testes.
+    """
+    root = typer.Typer()
+    root.add_typer(app, name=name)
+    return root
+
+
+GROUPS = {"exp": {"name": "Exportações"}, "imp": {"name": "Importações"}}
+ALIASES = {"trade": ["exp", "imp"], "empty": []}
+
+
+def sample_list_datasets(group: str) -> list[dict]:
+    return [
+        {
+            "group": group,
+            "id": f"{group}-monthly",
+            "ext": "csv",
+            "year": 2023,
+            "month": 5,
+            "url": f"https://example.test/{group}-monthly.csv",
+        }
+    ]
+
+
+def make_app(**overrides) -> FetcherApp:
+    kwargs: dict = {
+        "name": "comex-fetcher",
+        "groups_dict": GROUPS,
+        "aliases_dict": ALIASES,
+        "list_datasets": sample_list_datasets,
+    }
+    kwargs.update(overrides)
+    return FetcherApp(**kwargs)  # type: ignore[arg-type]
+
+
+# ---------------------------------------------------------------
+# default_path_builder / DataRepository
+# ---------------------------------------------------------------
+
+
+def test_default_path_builder_monthly_partition(tmp_path: Path):
+    entry = {
+        "group": "exp",
+        "id": "exp-mun",
+        "ext": "csv",
+        "year": 2023,
+        "month": 5,
+    }
+    path = default_path_builder(tmp_path, entry, dt.date(2024, 3, 15))
+    assert path == tmp_path / "exp" / "exp-mun_2023-05@20240315.csv"
+
+
+def test_default_path_builder_semester_partition(tmp_path: Path):
+    entry = {
+        "group": "exp",
+        "id": "exp-sem",
+        "ext": "csv",
+        "year": 2023,
+        "semester": 2,
+    }
+    path = default_path_builder(tmp_path, entry, dt.date(2024, 3, 15))
+    assert path == tmp_path / "exp" / "exp-sem_2023-02@20240315.csv"
+
+
+def test_default_path_builder_year_only(tmp_path: Path):
+    entry = {"group": "exp", "id": "exp", "ext": "csv", "year": 2023}
+    path = default_path_builder(tmp_path, entry, dt.date(2024, 3, 15))
+    assert path == tmp_path / "exp" / "exp_2023@20240315.csv"
+
+
+def test_default_path_builder_no_stamp_without_date(tmp_path: Path):
+    entry = {"group": "exp", "id": "exp", "ext": "csv", "year": 2023}
+    path = default_path_builder(tmp_path, entry, None)
+    assert path == tmp_path / "exp" / "exp_2023.csv"
+
+
+def test_default_path_builder_derives_ext_from_url(tmp_path: Path):
+    entry = {"group": "exp", "id": "exp", "url": "https://x.test/file.xlsx?a=b"}
+    path = default_path_builder(tmp_path, entry, None)
+    assert path.suffix == ".xlsx"
+
+
+def test_default_path_builder_ext_fallback(tmp_path: Path):
+    entry = {"group": "exp", "id": "exp", "url": "https://x.test/download"}
+    path = default_path_builder(tmp_path, entry, None)
+    assert path.suffix == ".bin"
+
+
+def test_default_path_builder_no_group_uses_id(tmp_path: Path):
+    entry = {"id": "lonely", "ext": "csv"}
+    path = default_path_builder(tmp_path, entry, None)
+    assert path == tmp_path / "lonely" / "lonely.csv"
+
+
+def test_data_repository_is_stamped(tmp_path: Path):
+    repo = DataRepository(tmp_path)
+    entry = {"group": "imp", "id": "imp", "ext": "csv", "year": 2024}
+    path = repo.path_for_entry(entry, last_modified=dt.date(2025, 1, 2))
+    assert path == tmp_path / "imp" / "imp_2024@20250102.csv"
+
+
+# ---------------------------------------------------------------
+# FetcherApp: path_builder opcional
+# ---------------------------------------------------------------
+
+
+def test_fetcher_app_defaults_to_default_path_builder():
+    app = make_app()
+    assert app.path_builder is default_path_builder
+
+
+def test_fetcher_app_accepts_custom_path_builder(tmp_path: Path):
+    def custom(output_dir, entry, last_modified):
+        return output_dir / "custom.csv"
+
+    app = make_app(path_builder=custom)
+    assert app.path_builder is custom
+
+
+def test_fetcher_app_default_output():
+    app = make_app()
+    assert app.default_output == Path("/data/comex")
+
+
+def test_fetcher_app_default_output_from_name(tmp_path: Path):
+    app = make_app(name="foo-fetcher")
+    assert app.default_output == Path("/data/foo")
+
+
+# ---------------------------------------------------------------
+# FetcherApp: attach_command e build_default_commands
+# ---------------------------------------------------------------
+
+
+def test_attach_command_inherits_default_commands():
+    def ping() -> None:
+        return None
+
+    app = make_app()
+    app.attach_command(ping)
+    result = runner.invoke(app.app, ["ping"])
+    assert result.exit_code == 0, result.output
+    names = [cmd.name for cmd in app.app.registered_commands]
+    assert {"sync", "list"} <= set(names)
+
+
+def test_attach_command_with_custom_name_and_kwargs(tmp_path: Path):
+    def convert(
+        input: Annotated[Path, typer.Argument(help="Arquivo de entrada")],
+    ) -> None:
+        typer.echo(f"converted {input.name}")
+
+    app = make_app(build_default_commands=False)
+    app.attach_command(convert, name="conv", no_args_is_help=True)
+    names = [cmd.name for cmd in app.app.registered_commands]
+    assert names == ["conv"]
+
+    # run the attached command through the CliRunner
+    dummy = tmp_path / "in.csv"
+    dummy.write_text("x,y\n1,2\n")
+    assert runner.invoke(_grouped(app.app), ["fd", "conv", str(dummy)]).exit_code == 0
+
+
+def test_build_default_commands_false_removes_sync_and_list():
+    app = make_app(build_default_commands=False)
+    names = [cmd.name for cmd in app.app.registered_commands]
+    assert "sync" not in names
+    assert "list" not in names
+
+
+def test_attach_command_invocation_output(tmp_path: Path):
+    fetcher = make_app(build_default_commands=False)
+
+    def hello(
+        verbose: Annotated[
+            bool, typer.Option("--verbose", help="Logs detalhados")
+        ] = False,
+    ) -> None:
+        if verbose:
+            typer.echo("verbose")
+        typer.echo("hello")
+
+    fetcher.attach_command(hello)
+    result = runner.invoke(_grouped(fetcher.app), ["fd", "hello", "--verbose"])
+    assert result.exit_code == 0, result.output
+    assert "verbose" in result.output
+
+
+# ---------------------------------------------------------------
+# make_resolve_groups
+# ---------------------------------------------------------------
+
+
+def test_make_resolve_groups_expands_aliases():
+    resolve = make_resolve_groups(GROUPS, ALIASES)
+    assert resolve(["trade"]) == ["exp", "imp"]
+
+
+def test_make_resolve_groups_dedups_and_preserves_order():
+    resolve = make_resolve_groups(GROUPS, ALIASES)
+    assert resolve(["imp", "trade", "exp"]) == ["imp", "exp"]
+
+
+def test_make_resolve_groups_none_returns_all_groups():
+    resolve = make_resolve_groups(GROUPS, ALIASES)
+    assert resolve(None) == ["exp", "imp"]
+
+
+def test_make_resolve_groups_unknown_raises():
+    resolve = make_resolve_groups(GROUPS, ALIASES)
+    with pytest.raises(ValueError, match="Grupo desconhecido: 'zzz'"):
+        resolve(["zzz"])
+
+
+def test_make_resolve_groups_alias_to_empty_raises():
+    resolve = make_resolve_groups(GROUPS, ALIASES)
+    with pytest.raises(ValueError, match="Grupo desconhecido: 'empty'"):
+        resolve(["empty"])
+
+
+def test_resolver_shared_between_instances():
+    app_a = make_app()
+    app_b = make_app()
+    assert app_a.resolve_groups(["trade"]) == ["exp", "imp"]
+    assert app_b.resolve_groups(["exp"]) == ["exp"]
+
+
+# ---------------------------------------------------------------
+# Integração: sync command com resolver (dry-run)
+# ---------------------------------------------------------------
+
+
+def test_builtin_sync_dry_run_with_alias():
+    app = make_app()
+    result = runner.invoke(app.app, ["sync", "trade", "--dry-run"])
+    assert result.exit_code == 0, result.output
+    assert "2 arquivo(s) listado(s)" in result.output
+
+
+def test_builtin_sync_unknown_group_exits_1():
+    app = make_app()
+    result = runner.invoke(app.app, ["sync", "zzz", "--dry-run"])
+    assert result.exit_code == 1
+    assert "Grupo desconhecido: 'zzz'" in result.output
+
+
+def test_builtin_list():
+    app = make_app()
+    result = runner.invoke(app.app, ["list"])
+    assert result.exit_code == 0, result.output
+    assert "2 dataset(s) no catálogo." in result.output

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

@@ -1,38 +0,0 @@
-name: Test
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-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 }}
-
-      - name: Install dependencies
-        run: uv sync --group dev
-
-      - name: Lint with ruff
-        run: |
-          uv run ruff check src/ tests/
-          uv run ruff format --check src/ tests/
-
-      - name: Run tests
-        run: uv run pytest

quantilica_cli-0.3.1/CHANGELOG.md

@@ -1,41 +0,0 @@
-# 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.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> ...`).