quantilica-core 0.3.1__tar.gz

quantilica_core-0.3.1/.github/workflows/publish.yml

@@ -0,0 +1,66 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/quantilica-core
+    permissions:
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/quantilica-core
+    permissions:
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

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

@@ -0,0 +1,38 @@
+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_core-0.3.1/.gitignore

@@ -0,0 +1,38 @@
+# Build / packaging
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# Virtual envs e caches do uv
+.venv/
+.uv-cache/
+
+# Lockfile — libs não versionam uv.lock
+uv.lock
+
+# Caches de teste / lint / tipos
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Cobertura
+.coverage
+.coverage.*
+htmlcov/
+
+# Editor / IDE / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+*.swp
+
+# Logs e env locais
+*.log
+.env
+.env.local
+
+# Claude
+.claude/

quantilica_core-0.3.1/CHANGELOG.md

@@ -0,0 +1,17 @@
+# 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-07-16
+
+### Corrigido
+
+- Exemplos de import no README (namespace package `quantilica.core.*`, não `quantilica_core.*`)
+- Instrução de instalação no README (`pip install quantilica-core`, em vez de git+https)
+
+### Adicionado
+
+- Primeiro release público no PyPI

quantilica_core-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Quantilica
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

quantilica_core-0.3.1/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: quantilica-core
+Version: 0.3.1
+Summary: Common foundation utilities for Quantilica data projects
+Project-URL: Homepage, https://github.com/Quantilica/quantilica-core
+Project-URL: Repository, https://github.com/Quantilica/quantilica-core
+Project-URL: Issues, https://github.com/Quantilica/quantilica-core/issues
+Author-email: "Komesu, D.K." <daniel@dkko.me>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: brazil,data,open-data,quantilica
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: tqdm>=4.67.1
+Provides-Extra: cli
+Requires-Dist: rich>=13.0.0; extra == 'cli'
+Requires-Dist: typer>=0.15.0; extra == 'cli'
+Description-Content-Type: text/markdown
+
+# quantilica-core: Fundação de infraestrutura para projetos Quantilica
+
+![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square) ![Python](https://img.shields.io/badge/python-3.12+-blue.svg?style=flat-square)
+
+Biblioteca de utilitários domain-neutral que serve como base para todos os coletores e pipelines Quantilica. Centraliza rede resiliente, armazenamento atômico, proveniência de dados e logging estruturado — permitindo que cada pacote de domínio foque exclusivamente na lógica de sua fonte de dados.
+
+## Instalação
+
+```bash
+pip install quantilica-core
+```
+
+Com uv:
+
+```bash
+uv add quantilica-core
+```
+
+## Uso Rápido
+
+```python
+from quantilica.core.http import HttpClient
+from quantilica.core.storage import LocalStorage
+from quantilica.core.manifests import DownloadManifest
+
+# Cliente HTTP com retry automático
+client = HttpClient(attempts=3)
+response = client.get("https://api.ibge.gov.br/...")
+
+# Escrita atômica em disco
+storage = LocalStorage("dados/raw")
+stat = storage.write_bytes("sidra/tabela.csv", response.content)
+
+# Registro de proveniência (SHA-256)
+manifest = DownloadManifest.from_file(
+    source_id="ibge",
+    dataset_id="sidra-1234",
+    url="https://...",
+    file_path=stat.path,
+    producer="sidra-fetcher",
+)
+manifest.write_json(stat.path.with_suffix(".manifest.json"))
+```
+
+## Módulos
+
+| Módulo | Descrição |
+| :--- | :--- |
+| `http` | `HttpClient` e `AsyncHttpClient` com backoff exponencial e jitter |
+| `retry` | Lógica de retry configurável para falhas de rede e erros transientes |
+| `storage` | `LocalStorage` para gerenciar artefatos brutos e processados atomicamente |
+| `manifests` | `DownloadManifest` e `ExecutionManifest` para rastreabilidade completa |
+| `metadata` | Modelos `MetadataCatalog`, `Source`, `Dataset` para interoperabilidade |
+| `logging` | Logging estruturado via `get_logger` e `log_step` |
+| `exceptions` | Hierarquia padrão: `FetchError`, `ParseError`, `StorageError` |
+
+## Princípios de Design
+
+1. **Neutralidade de domínio** — o core nunca sabe o que é IBGE, DATASUS ou INMET.
+2. **Leveza** — dependências mínimas no núcleo; integrações pesadas são extras opcionais.
+3. **Estabilidade** — alta cobertura de testes em todos os componentes de infraestrutura.
+4. **DX** — APIs tipadas e tratamento de erros consistente em toda a organização.
+
+## Desenvolvimento
+
+```bash
+git clone https://github.com/Quantilica/quantilica-core.git
+cd quantilica-core
+uv sync --dev
+uv run pytest
+```
+
+## Licença
+
+MIT — veja [LICENSE](LICENSE).

quantilica_core-0.3.1/README.md

@@ -0,0 +1,75 @@
+# quantilica-core: Fundação de infraestrutura para projetos Quantilica
+
+![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square) ![Python](https://img.shields.io/badge/python-3.12+-blue.svg?style=flat-square)
+
+Biblioteca de utilitários domain-neutral que serve como base para todos os coletores e pipelines Quantilica. Centraliza rede resiliente, armazenamento atômico, proveniência de dados e logging estruturado — permitindo que cada pacote de domínio foque exclusivamente na lógica de sua fonte de dados.
+
+## Instalação
+
+```bash
+pip install quantilica-core
+```
+
+Com uv:
+
+```bash
+uv add quantilica-core
+```
+
+## Uso Rápido
+
+```python
+from quantilica.core.http import HttpClient
+from quantilica.core.storage import LocalStorage
+from quantilica.core.manifests import DownloadManifest
+
+# Cliente HTTP com retry automático
+client = HttpClient(attempts=3)
+response = client.get("https://api.ibge.gov.br/...")
+
+# Escrita atômica em disco
+storage = LocalStorage("dados/raw")
+stat = storage.write_bytes("sidra/tabela.csv", response.content)
+
+# Registro de proveniência (SHA-256)
+manifest = DownloadManifest.from_file(
+    source_id="ibge",
+    dataset_id="sidra-1234",
+    url="https://...",
+    file_path=stat.path,
+    producer="sidra-fetcher",
+)
+manifest.write_json(stat.path.with_suffix(".manifest.json"))
+```
+
+## Módulos
+
+| Módulo | Descrição |
+| :--- | :--- |
+| `http` | `HttpClient` e `AsyncHttpClient` com backoff exponencial e jitter |
+| `retry` | Lógica de retry configurável para falhas de rede e erros transientes |
+| `storage` | `LocalStorage` para gerenciar artefatos brutos e processados atomicamente |
+| `manifests` | `DownloadManifest` e `ExecutionManifest` para rastreabilidade completa |
+| `metadata` | Modelos `MetadataCatalog`, `Source`, `Dataset` para interoperabilidade |
+| `logging` | Logging estruturado via `get_logger` e `log_step` |
+| `exceptions` | Hierarquia padrão: `FetchError`, `ParseError`, `StorageError` |
+
+## Princípios de Design
+
+1. **Neutralidade de domínio** — o core nunca sabe o que é IBGE, DATASUS ou INMET.
+2. **Leveza** — dependências mínimas no núcleo; integrações pesadas são extras opcionais.
+3. **Estabilidade** — alta cobertura de testes em todos os componentes de infraestrutura.
+4. **DX** — APIs tipadas e tratamento de erros consistente em toda a organização.
+
+## Desenvolvimento
+
+```bash
+git clone https://github.com/Quantilica/quantilica-core.git
+cd quantilica-core
+uv sync --dev
+uv run pytest
+```
+
+## Licença
+
+MIT — veja [LICENSE](LICENSE).

quantilica_core-0.3.1/pyproject.toml

@@ -0,0 +1,67 @@
+[project]
+name = "quantilica-core"
+version = "0.3.1"
+description = "Common foundation utilities for Quantilica data projects"
+readme = "README.md"
+authors = [
+    { name = "Komesu, D.K.", email = "daniel@dkko.me" },
+]
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+keywords = [
+    "data",
+    "open-data",
+    "brazil",
+    "quantilica",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.28.1",
+    "tqdm>=4.67.1",
+]
+
+[project.optional-dependencies]
+cli = [
+    "rich>=13.0.0",
+    "typer>=0.15.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Quantilica/quantilica-core"
+Repository = "https://github.com/Quantilica/quantilica-core"
+Issues = "https://github.com/Quantilica/quantilica-core/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.9.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ["-p", "no:cacheprovider"]
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.hatch.build.targets.wheel]
+sources = ["src"]
+packages = ["src/quantilica"]
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"

quantilica_core-0.3.1/src/quantilica/core/__init__.py

@@ -0,0 +1,10 @@
+"""Common foundation utilities for Quantilica data projects."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("quantilica-core")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

quantilica_core-0.3.1/src/quantilica/core/cache.py

@@ -0,0 +1,124 @@
+"""File-based cache helpers for deterministic data downloads."""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Mapping
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlencode
+
+from .dates import isoformat_utc, parse_iso_datetime, utc_now
+from .exceptions import StorageError
+from .files import ensure_dir, sha256_bytes, write_bytes_atomic, write_text_atomic
+
+
+@dataclass(frozen=True)
+class CacheEntry:
+    """Metadata for one cached object."""
+
+    key: str
+    path: str
+    created_at: str
+    size_bytes: int
+    sha256: str
+    metadata: dict[str, Any]
+
+
+class FileCache:
+    """Simple content cache stored on the local filesystem."""
+
+    def __init__(self, root: str | os.PathLike[str]) -> None:
+        self.root = ensure_dir(root)
+
+    def key_for_url(
+        self,
+        url: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> str:
+        """Return a deterministic key for a URL request."""
+        parts = [url]
+        if params:
+            parts.append(urlencode(sorted(params.items()), doseq=True))
+        if headers:
+            normalized_headers = {
+                key.lower(): value for key, value in sorted(headers.items())
+            }
+            parts.append(json.dumps(normalized_headers, sort_keys=True))
+        return sha256_bytes("\n".join(parts).encode("utf-8"))
+
+    def content_path(self, key: str) -> Path:
+        """Return the content path for a cache key."""
+        return self.root / key[:2] / key[2:]
+
+    def metadata_path(self, key: str) -> Path:
+        """Return the metadata path for a cache key."""
+        return self.root / key[:2] / f"{key[2:]}.json"
+
+    def exists(self, key: str) -> bool:
+        """Return True when content and metadata exist for a key."""
+        return self.content_path(key).exists() and self.metadata_path(key).exists()
+
+    def read_bytes(self, key: str) -> bytes:
+        """Read cached bytes."""
+        path = self.content_path(key)
+        try:
+            return path.read_bytes()
+        except OSError as exc:
+            raise StorageError(f"Could not read cache entry: {key}") from exc
+
+    def read_metadata(self, key: str) -> CacheEntry:
+        """Read cache metadata."""
+        path = self.metadata_path(key)
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            raise StorageError(f"Could not read cache metadata: {key}") from exc
+        return CacheEntry(**payload)
+
+    def write_bytes(
+        self,
+        key: str,
+        content: bytes,
+        *,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> CacheEntry:
+        """Write content and metadata for a cache key."""
+        content_path = self.content_path(key)
+        metadata_path = self.metadata_path(key)
+        write_bytes_atomic(content_path, content)
+
+        entry = CacheEntry(
+            key=key,
+            path=str(content_path.relative_to(self.root)),
+            created_at=isoformat_utc(),
+            size_bytes=len(content),
+            sha256=sha256_bytes(content),
+            metadata=dict(metadata or {}),
+        )
+        write_text_atomic(
+            metadata_path,
+            json.dumps(asdict(entry), ensure_ascii=False, indent=2, sort_keys=True),
+        )
+        return entry
+
+    def is_fresh(self, key: str, *, ttl_seconds: int | None = None) -> bool:
+        """Return True if a cache entry exists and is within TTL."""
+        if not self.exists(key):
+            return False
+        if ttl_seconds is None:
+            return True
+        entry = self.read_metadata(key)
+        created_at = parse_iso_datetime(entry.created_at)
+        age = (utc_now() - created_at).total_seconds()
+        return age <= ttl_seconds
+
+    def get_bytes(self, key: str, *, ttl_seconds: int | None = None) -> bytes | None:
+        """Return cached bytes when present and fresh, otherwise None."""
+        if not self.is_fresh(key, ttl_seconds=ttl_seconds):
+            return None
+        return self.read_bytes(key)

quantilica_core-0.3.1/src/quantilica/core/cli.py

@@ -0,0 +1,109 @@
+"""Shared Rich-based helpers for quantilica fetcher CLI plugins.
+
+These helpers are host-only: ``plugin.py`` modules run inside the
+``quantilica-cli`` host, which pulls in ``rich`` via the ``cli`` extra
+(``quantilica-core[cli]``). Standalone argparse CLIs should keep using
+:func:`quantilica.core.logging.configure_cli_logging` instead.
+"""
+
+from __future__ import annotations
+
+import logging
+
+try:
+    from rich.console import Console
+    from rich.logging import RichHandler
+    from rich.progress import (
+        BarColumn,
+        DownloadColumn,
+        MofNCompleteColumn,
+        Progress,
+        SpinnerColumn,
+        TextColumn,
+        TimeElapsedColumn,
+        TimeRemainingColumn,
+        TransferSpeedColumn,
+    )
+except ModuleNotFoundError as exc:  # pragma: no cover
+    raise ModuleNotFoundError(
+        "quantilica.core.cli requires the 'cli' extra; install quantilica-core[cli]"
+    ) from exc
+
+
+_console: Console | None = None
+
+
+def get_console() -> Console:
+    """Return a process-wide shared Rich console."""
+    global _console
+    if _console is None:
+        _console = Console()
+    return _console
+
+
+def setup_rich_logging(
+    verbose: bool,
+    *,
+    console: Console | None = None,
+) -> None:
+    """Configure logging via ``RichHandler`` without breaking progress bars.
+
+    ``verbose=False`` → WARNING only; ``verbose=True`` → DEBUG.
+    """
+    level = logging.DEBUG if verbose else logging.WARNING
+    logging.basicConfig(
+        level=level,
+        format="%(message)s",
+        datefmt="[%X]",
+        handlers=[RichHandler(console=console or get_console(), show_path=False)],
+        force=True,
+    )
+
+
+def make_batch_progress(console: Console | None = None) -> Progress:
+    """Build a Progress for overall/batch tracking (file counts)."""
+    return Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(),
+        MofNCompleteColumn(),
+        TimeElapsedColumn(),
+        TimeRemainingColumn(),
+        console=console or get_console(),
+    )
+
+
+def make_download_progress(console: Console | None = None) -> Progress:
+    """Build a Progress for individual file downloads (bytes/speed)."""
+    return Progress(
+        SpinnerColumn(),
+        TextColumn("[dim]{task.description}[/dim]"),
+        BarColumn(),
+        DownloadColumn(),
+        TransferSpeedColumn(),
+        TimeRemainingColumn(),
+        console=console or get_console(),
+    )
+
+
+def expand_years_cli(
+    years: list[str] | None,
+    default_range: str | None = None,
+    console: Console | None = None,
+) -> list[int]:
+    """Expand CLI year/range arguments (e.g. ``["2020:2022", "2024"]``).
+
+    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.
+    """
+    from quantilica.core.dates import expand_year_range
+
+    con = console or get_console()
+    specs = years if years else ([default_range] if default_range else [])
+    result: list[int] = []
+    for arg in specs:
+        try:
+            result.extend(expand_year_range(arg))
+        except ValueError:
+            con.print(f"[yellow]Aviso:[/yellow] ano/intervalo inválido '{arg}'")
+    return result