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

{quantilica_cli-0.3.0 → quantilica_cli-0.3.2}/CHANGELOG.md

@@ -5,6 +5,17 @@ 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.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

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: quantilica-cli
-Version: 0.3.0
+Version: 0.3.2
 Summary: Unified CLI for Quantilica open data fetchers
 Author-email: "Komesu, D.K." <daniel@dkko.me>
 License-Expression: MIT
@@ -24,6 +24,7 @@ Description-Content-Type: text/markdown
 # quantilica-cli
 
 CLI unificada para o ecossistema Quantilica de dados abertos brasileiros.
+For full documentation, please visit [https://docs.quantilica.com](https://docs.quantilica.com).
 
 ## Instalação
 

{quantilica_cli-0.3.0 → quantilica_cli-0.3.2}/README.md

@@ -1,6 +1,7 @@
 # quantilica-cli
 
 CLI unificada para o ecossistema Quantilica de dados abertos brasileiros.
+For full documentation, please visit [https://docs.quantilica.com](https://docs.quantilica.com).
 
 ## Instalação
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "quantilica-cli"
-version = "0.3.0"
+version = "0.3.2"
 description = "Unified CLI for Quantilica open data fetchers"
 readme = "README.md"
 authors = [{ name = "Komesu, D.K.", email = "daniel@dkko.me" }]
@@ -38,16 +38,14 @@ dev = ["ruff>=0.9.0", "pytest>=8.0.0"]
 
 # Para desenvolvimento local do quantilica-core em conjunto com o CLI:
 # cd quantilica-cli && uv pip install -e ../quantilica-core (sem [tool.uv.sources])
-# Em produção, quantilica-core é instalado via git+https (declarado em dependencies).
+# Em produção, quantilica-core resolve pelo PyPI (pin de registro em dependencies).
 
 # [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.0 → quantilica_cli-0.3.2/src}/quantilica/cli/cli.py

@@ -138,6 +138,7 @@ def list_sources(
 
 
 def main() -> None:
+    """Main entry point for the quantilica CLI."""
     if hasattr(sys.stdout, "reconfigure"):
         sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # type: ignore
     logging.basicConfig(

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

@@ -47,7 +47,17 @@ _STALE_GRACE = 1.5
 
 
 def parse_since(value: str) -> datetime:
-    """Parse a relative duration ('7d', '24h') or ISO date into a UTC cutoff."""
+    """Parse a relative duration ('7d', '24h') or ISO date into a UTC cutoff.
+
+    Args:
+        value: The string duration or ISO date to parse.
+
+    Returns:
+        The computed UTC cutoff datetime.
+
+    Raises:
+        typer.BadParameter: If the value is neither a valid duration nor an ISO date.
+    """
     match = _DURATION_RE.match(value.strip().lower())
     if match:
         amount, unit = int(match.group(1)), match.group(2)
@@ -101,6 +111,12 @@ def iter_manifests(root: Path) -> Iterator[tuple[Path, dict[str, Any]]]:
     """Yield ``(manifest_path, data)`` for every manifest found under ``root``.
 
     Malformed JSON files are skipped with a warning rather than aborting.
+
+    Args:
+        root: The root directory to search for manifests.
+
+    Yields:
+        A tuple containing the path to the manifest and its parsed JSON data.
     """
     for path in sorted(root.glob(MANIFEST_GLOB)):
         if not path.is_file():

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

@@ -21,6 +21,14 @@ def file_progress(
 
     Designed for use with HttpClient.download_with_manifest(progress=...).
     ``total`` is the expected file size in bytes; pass 0 when unknown.
+
+    Args:
+        description: The text description to show on the progress bar.
+        total: Expected file size in bytes. Defaults to 0.
+        leave: Whether to leave the progress bar upon completion. Defaults to False.
+
+    Yields:
+        A callback function to update progress.
     """
     pbar: tqdm[int] = tqdm(
         total=total or None,
@@ -56,6 +64,14 @@ def batch_progress(
     *,
     total: int,
 ) -> Generator[tqdm[int], None, None]:
-    """Context manager for tracking overall batch progress (file count)."""
+    """Context manager for tracking overall batch progress (file count).
+
+    Args:
+        description: The text description for the batch progress.
+        total: Total number of files/items to track.
+
+    Yields:
+        A tqdm progress bar instance.
+    """
     with tqdm(total=total, desc=description, unit="arquivo", leave=True) as pbar:
         yield pbar

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

@@ -34,6 +34,11 @@ logger = get_logger(__name__)
 
 
 def default_client() -> HttpClient:
+    """Create a default HttpClient with standard configuration.
+
+    Returns:
+        A pre-configured HttpClient instance.
+    """
     return HttpClient(
         timeout=180.0,
         verify=True,
@@ -50,7 +55,18 @@ def default_client() -> HttpClient:
 
 
 class FetcherApp:
-    """Standard orchestrator for Quantilica fetchers."""
+    """Standard orchestrator for Quantilica fetchers.
+
+    Args:
+        name: Name of the fetcher (e.g., 'comex-fetcher').
+        help: Help text for the CLI.
+        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.
+        default_output: Default output directory path.
+        client: HTTP or FTP client instance. Defaults to default_client().
+    """
 
     def __init__(
         self,
@@ -108,7 +124,21 @@ class FetcherApp:
         dry_run: bool = False,
         progress: ProgressCallback | None = None,
     ) -> Path:
-        """Download one dataset entry and return the destination path."""
+        """Download one dataset entry and return the destination path.
+
+        Args:
+            entry: Dictionary containing dataset metadata (url, id, etc).
+            output_dir: Destination directory.
+            dry_run: If True, computes the destination path without downloading.
+            progress: Optional callback to track download progress.
+
+        Returns:
+            The local path where the file was (or would be) saved.
+
+        Raises:
+            FetchError: If no valid URLs could be downloaded.
+            HttpStatusError: On non-404 HTTP errors.
+        """
         urls_to_try = [entry["url"]]
         if "fallback_urls" in entry and entry["fallback_urls"]:
             urls_to_try.extend(entry["fallback_urls"])
@@ -155,9 +185,18 @@ class FetcherApp:
         output_dir: Path,
         workers: int = 4,
     ) -> tuple[int, int, list[tuple[str, str]]]:
-        """
-        Executes parallel download for a list of dataset entries.
-        Returns a tuple: (downloaded_count, total_count, errors_list).
+        """Executes parallel download for a list of dataset entries.
+
+        Args:
+            entries: List of dataset entries to download.
+            output_dir: The target base directory for downloads.
+            workers: Maximum number of parallel downloads.
+
+        Returns:
+            A tuple containing:
+            - downloaded_count: Number of successfully downloaded files.
+            - total_count: Total number of files attempted.
+            - errors_list: A list of tuples containing the dataset ID and the error message.
         """
         console = get_console()
         total = len(entries)

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

@@ -22,7 +22,7 @@ app = typer.Typer(
 console = Console()
 
 FETCHER_GROUP = "quantilica.fetchers"
-DEFAULT_INDEX_URL = "https://quantilica.com/quantilica-index/simple/"
+DEFAULT_INDEX_URL = "https://index.quantilica.com/simple/"
 
 # Mapeamento estático padrão de comandos CLI para nome das distribuições
 SOURCES_REGISTRY: dict[str, str] = {
@@ -40,7 +40,11 @@ SOURCES_REGISTRY: dict[str, str] = {
 
 
 def get_config_dir() -> Path:
-    """Retorna o diretório de configuração do quantilica-cli."""
+    """Retorna o diretório de configuração do quantilica-cli.
+
+    Returns:
+        O caminho do diretório de configuração.
+    """
     custom = os.environ.get("QUANTILICA_CONFIG_DIR")
     if custom:
         return Path(custom)
@@ -48,12 +52,20 @@ def get_config_dir() -> Path:
 
 
 def get_state_file() -> Path:
-    """Retorna o caminho para o arquivo de estado local."""
+    """Retorna o caminho para o arquivo de estado local.
+
+    Returns:
+        O caminho para o arquivo de estado `state.toml`.
+    """
     return get_config_dir() / "state.toml"
 
 
 def load_state() -> dict[str, Any]:
-    """Lê o arquivo de estado em ~/.config/quantilica/state.toml."""
+    """Lê o arquivo de estado em ~/.config/quantilica/state.toml.
+
+    Returns:
+        Um dicionário contendo o estado carregado.
+    """
     state_file = get_state_file()
     if not state_file.exists():
         return {"installed": {}}
@@ -71,7 +83,11 @@ def load_state() -> dict[str, Any]:
 
 
 def save_state(state: dict[str, Any]) -> None:
-    """Salva o arquivo de estado em ~/.config/quantilica/state.toml."""
+    """Salva o arquivo de estado em ~/.config/quantilica/state.toml.
+
+    Args:
+        state: O dicionário de estado a ser salvo.
+    """
     config_dir = get_config_dir()
     config_dir.mkdir(parents=True, exist_ok=True)
     state_file = get_state_file()
@@ -85,18 +101,34 @@ def save_state(state: dict[str, Any]) -> None:
 
 
 def get_installed_entry_points() -> set[str]:
-    """Retorna o conjunto de nomes de entry points de fetchers atualmente instalados."""
+    """Retorna o conjunto de nomes de entry points de fetchers atualmente instalados.
+
+    Returns:
+        Um conjunto de nomes de entry points.
+    """
     eps = entry_points(group=FETCHER_GROUP)
     return {ep.name for ep in eps}
 
 
 def get_index_url() -> str:
-    """Retorna a URL do índice pip customizado ou default."""
+    """Retorna a URL do índice pip customizado ou default.
+
+    Returns:
+        A URL do índice pip.
+    """
     return os.environ.get("QUANTILICA_INDEX_URL", DEFAULT_INDEX_URL)
 
 
 def install_package(dist_name: str, index_url: str | None = None) -> None:
-    """Instala um pacote Python usando uv pip install se disponível, ou pip."""
+    """Instala um pacote Python usando uv pip install se disponível, ou pip.
+
+    Args:
+        dist_name: Nome do pacote a instalar.
+        index_url: URL do índice pip. Padrão para a URL do índice global se não especificada.
+
+    Raises:
+        RuntimeError: Se a instalação falhar.
+    """
     idx = index_url or get_index_url()
 
     # Prepara o ambiente garantindo que VIRTUAL_ENV aponte para o ambiente atual
@@ -135,7 +167,14 @@ def install_package(dist_name: str, index_url: str | None = None) -> None:
 
 
 def uninstall_package(dist_name: str) -> None:
-    """Desinstala um pacote Python usando uv pip uninstall se disponível, ou pip."""
+    """Desinstala um pacote Python usando uv pip uninstall se disponível, ou pip.
+
+    Args:
+        dist_name: Nome do pacote a desinstalar.
+
+    Raises:
+        RuntimeError: Se a desinstalação falhar.
+    """
     env = os.environ.copy()
     venv_dir = str(Path(sys.executable).parent.parent)
     env["VIRTUAL_ENV"] = venv_dir
@@ -154,7 +193,11 @@ def uninstall_package(dist_name: str) -> None:
 
 
 def fetch_remote_sources() -> dict[str, str]:
-    """Obtém a lista remota de fontes disponíveis do arquivo sources.json do índice."""
+    """Obtém a lista remota de fontes disponíveis do arquivo sources.json do índice.
+
+    Returns:
+        Um dicionário mapeando os nomes das fontes para os nomes das distribuições.
+    """
     index_url = get_index_url()
     # Converte simple/ index url para URL base de sources.json
     base_url = index_url.rstrip("/")
@@ -178,7 +221,11 @@ def fetch_remote_sources() -> dict[str, str]:
 
 
 def reexec_cli(args: list[str]) -> None:
-    """Recarrega o processo CLI com os novos entry points instalados."""
+    """Recarrega o processo CLI com os novos entry points instalados.
+
+    Args:
+        args: Argumentos a serem passados para a nova execução da CLI.
+    """
     if sys.platform == "win32":
         code = subprocess.call([sys.executable, "-m", "quantilica.cli.cli", *args])
         sys.exit(code)
@@ -186,6 +233,11 @@ def reexec_cli(args: list[str]) -> None:
         os.execv(sys.executable, [sys.executable, "-m", "quantilica.cli.cli", *args])
 
 
+def _merged_registry() -> dict[str, str]:
+    """Combina o registro remoto (sources.json) com o local; o local tem precedência."""
+    return {**fetch_remote_sources(), **SOURCES_REGISTRY}
+
+
 @app.command("install")
 def cmd_install(
     source: str = typer.Argument(
@@ -196,7 +248,7 @@ def cmd_install(
     ),
 ) -> None:
     """Instala uma fonte de dados (fetcher) sob demanda."""
-    registry = SOURCES_REGISTRY
+    registry = _merged_registry()
     dist_name = registry.get(source, source)
 
     installed_eps = get_installed_entry_points()
@@ -242,7 +294,7 @@ def cmd_uninstall(
     ),
 ) -> None:
     """Desinstala uma fonte de dados (fetcher)."""
-    registry = SOURCES_REGISTRY
+    registry = _merged_registry()
     dist_name = registry.get(source, source)
 
     try:

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

@@ -38,7 +38,11 @@ _console: Console | None = None
 
 
 def get_console() -> Console:
-    """Return a process-wide shared Rich console."""
+    """Return a process-wide shared Rich console.
+
+    Returns:
+        The shared Rich Console instance.
+    """
     global _console
     if _console is None:
         _console = Console()
@@ -53,6 +57,10 @@ def setup_rich_logging(
     """Configure logging via ``RichHandler`` without breaking progress bars.
 
     ``verbose=False`` → WARNING only; ``verbose=True`` → DEBUG.
+
+    Args:
+        verbose: Whether to enable verbose logging.
+        console: Optional Rich Console to use for logging.
     """
     level = logging.DEBUG if verbose else logging.WARNING
     logging.basicConfig(
@@ -65,7 +73,14 @@ def setup_rich_logging(
 
 
 def make_batch_progress(console: Console | None = None) -> Progress:
-    """Build a Progress for overall/batch tracking (file counts)."""
+    """Build a Progress for overall/batch tracking (file counts).
+
+    Args:
+        console: Optional Rich Console to use.
+
+    Returns:
+        A Rich Progress instance configured for batch tracking.
+    """
     return Progress(
         SpinnerColumn(),
         TextColumn("[progress.description]{task.description}"),
@@ -78,7 +93,14 @@ def make_batch_progress(console: Console | None = None) -> Progress:
 
 
 def make_download_progress(console: Console | None = None) -> Progress:
-    """Build a Progress for individual file downloads (bytes/speed)."""
+    """Build a Progress for individual file downloads (bytes/speed).
+
+    Args:
+        console: Optional Rich Console to use.
+
+    Returns:
+        A Rich Progress instance configured for individual file downloads.
+    """
     return Progress(
         SpinnerColumn(),
         TextColumn("[dim]{task.description}[/dim]"),
@@ -99,6 +121,14 @@ def expand_years_cli(
 
     If ``years`` is empty and ``default_range`` is provided, it expands the
     default range. Prints a warning to the console/stderr for any invalid specs.
+
+    Args:
+        years: List of year strings or ranges to expand.
+        default_range: A default range to use if years is empty.
+        console: Optional Rich Console for printing warnings.
+
+    Returns:
+        A list of expanded year integers.
     """
     from quantilica.core.dates import expand_year_range
 
@@ -114,7 +144,12 @@ def expand_years_cli(
 
 
 class ProgressPool:
-    """Manages a fixed pool of rich progress bars for concurrent workers."""
+    """Manages a fixed pool of rich progress bars for concurrent workers.
+
+    Args:
+        workers: The number of progress bar tasks to initialize.
+        file_prog: The Rich Progress instance to add tasks to.
+    """
 
     def __init__(self, workers: int, file_prog: Progress):
         self.lock = threading.Lock()
@@ -127,6 +162,14 @@ class ProgressPool:
     def acquire(
         self, description: str
     ) -> Generator[Callable[[int, int], None], None, None]:
+        """Acquires a progress bar task and returns an update callback.
+
+        Args:
+            description: The description to show for this task.
+
+        Yields:
+            A callback function to update progress with downloaded and total bytes.
+        """
         with self.lock:
             task_id = self.available.pop(0)
         self.file_prog.update(task_id, description=description, completed=0, total=None)
@@ -154,7 +197,14 @@ class ProgressPool:
 def graceful_executor(
     max_workers: int,
 ) -> Generator[concurrent.futures.ThreadPoolExecutor, None, None]:
-    """ThreadPoolExecutor that cancels futures and shuts down on KeyboardInterrupt."""
+    """ThreadPoolExecutor that cancels futures and shuts down on KeyboardInterrupt.
+
+    Args:
+        max_workers: Maximum number of threads in the pool.
+
+    Yields:
+        A thread pool executor instance.
+    """
     executor = concurrent.futures.ThreadPoolExecutor(max_workers=max_workers)
     # Python 3.9+ supports cancel_futures=True, which automatically
     # cancels pending futures during shutdown.