econchile 0.1.0__tar.gz

econchile-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cristóbal Almendra
+
+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.

econchile-0.1.0/MANIFEST.in

@@ -0,0 +1,25 @@
+# MANIFEST.in — controls what goes in the sdist (source distribution)
+# The wheel is governed by pyproject.toml [tool.setuptools.packages.find].
+#
+# Goal: ship source + tests + specs, but EXCLUDE the 8MB API fixture
+# (tests need it in the repo, but it should not bloat the sdist) and
+# exclude any leftover build artifacts / private study notes.
+
+# Include the real test fixture only if explicitly wanted — for v0.1 we
+# exclude it from the sdist to keep the download small. Tests that depend
+# on it are skipped/guarded in CI when the file is absent.
+exclude sample_response.json
+exclude multi_series_sample.json
+
+# Private annotated learning notes never ship
+recursive-exclude econchile/study *
+
+# Build artifacts
+recursive-exclude dist *
+recursive-exclude build *
+recursive-exclude *.egg-info *
+
+# Python caches
+recursive-exclude **/__pycache__ *
+global-exclude *.py[cod]
+global-exclude *.db

econchile-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: econchile
+Version: 0.1.0
+Summary: Python library to retrieve Chilean macroeconomic data
+Author: Cristóbal Almendra
+License-Expression: MIT
+Keywords: chile,economics,macro,banco-central,bde
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Dynamic: license-file
+
+# econchile
+
+Chilean macroeconomic data (Banco Central de Chile) for Python.
+
+`econchile` is a thin, practical client for the BCCh SIE REST web service. It downloads official series (UF, USD, TPM, IPC_VAR, IPC_INDEX, IMACEC, PIB), parses them into clean, typed data, and keeps a local SQLite cache so repeat queries are instant and your scripts survive API outages.
+
+## Install
+
+Once v0.1 is on PyPI: `pip install econchile`. Until then, install from source:
+
+```bash
+git clone <repo-url> econchile
+cd econchile
+pip install -e .
+```
+
+Requires Python 3.10+.
+
+## Authentication
+
+Request a free API token from the BCCh statistics database (SIE), see the official API documentation.
+
+```bash
+export BCCH_TOKEN="your-token-here"
+```
+
+The library reads `BCCH_TOKEN` from the environment — it does not load `.env` files itself. The token is required for v0.1.
+
+## Quickstart
+
+```python
+from econchile import BcchClient, Series
+
+client = BcchClient()
+
+# Last 3 months of the UF (daily)
+result = client.get(Series.UF, "2024-01-01", "2024-03-31")
+
+for obs in result.observations:
+    print(obs.date, obs.value)
+```
+
+Dates are always `YYYY-MM-DD`. Missing observations have `value=None`.
+
+## The two clients
+
+| Client | Strategy | Best for |
+|--------|----------|----------|
+| `BcchClient` | **Cache-first** — serves from the local cache when fresh, hits the API only on a miss | Interactive use, repeated queries |
+| `OfflineClient` | **API-first** — always tries the API, falls back to the cache when it fails | Cron jobs and scripts that must not crash |
+
+```python
+from econchile.offline import OfflineClient
+
+client = OfflineClient()
+result = client.get(Series.USD, "2024-01-01", "2024-03-31")  # survives API outages
+```
+
+## Available series (v0.1)
+
+| Series | BCCh code | Frequency | Meaning |
+|--------|-----------|-----------|---------|
+| `Series.UF` | `F073.UFF.PRE.Z.D` | daily | Unidad de Fomento |
+| `Series.USD` | `F073.TCO.PRE.Z.D` | daily | Nominal exchange rate (CLP/USD) |
+| `Series.TPM` | `F022.TPM.TIN.D001.NO.Z.D` | daily | Monetary policy rate |
+| `Series.IPC_VAR` | `F074.IPC.VAR.Z.Z.C.M` | monthly | CPI, month-over-month change |
+| `Series.IPC_INDEX` | `F074.IPC.IND.Z.2023.C.M` | monthly | CPI general index (base 2023=100) |
+| `Series.IMACEC` | `F032.IMC.IND.Z.Z.EP18.Z.Z.0.M` | monthly | Economic activity index (base 2018=100) |
+| `Series.PIB` | `F032.PIB.FLU.R.CLP.EP18.Z.Z.0.T` | quarterly | GDP, chained volumes (base 2018) |
+
+More series are planned. Use `client.list_series()` for the full catalog and `client.search("ipc")` to find series by keyword:
+
+```python
+hits = client.search("ipc")     # matches name, code, Spanish and English titles
+for meta in hits:
+    print(meta.series_id, meta.spanish_title)
+```
+
+## Gotchas
+
+- **Date format**: pass `YYYY-MM-DD` to `get()`; the library converts the API's native `DD-MM-YYYY` for you.
+- **Missing data**: the BCCh API marks gaps as "ND". These become `value=None`, not zeros or exceptions, check for `None` before using a value.
+- **Representations**: `IPC_VAR` is a monthly % change, `IPC_INDEX` is a base-2023 index. Same variable, different meaning.
+- **Cache freshness**: cached results are reused for 24 hours by default; configure via `ttl_seconds` on `BcchClient(...)` or `OfflineClient(...)` (the cache lives at `~/.econchile/cache.db`).
+- **Errors**: unknown series raise `KeyError`, malformed dates raise `ValueError`, API failures raise `BcchApiError` and `BcchOfflineError` when the offline fallback is also exhausted.
+
+## API
+
+- `BcchClient.get(series, desde, hasta, use_cache=True)` — fetch a series over a date range; returns a `SeriesResult`.
+- `OfflineClient.get(series, desde, hasta)` — same, but API-first with cache fallback.
+- `BcchClient.search(keyword)` — case- and accent-insensitive catalog search → `list[SeriesMeta]`.
+- `BcchClient.list_series()` — all series metadata → `list[SeriesMeta]`.
+- `BcchClient.clear_cache()` — empty the local cache (returns the number of rows removed).
+
+A `SeriesResult` has:
+
+- `series` — the `Series` member
+- `observations` — list of `Observation(date: str, value: float | None)`
+- `fetched_at` — timestamp (UTC)
+- `source` — `"api"`, `"cache"`, or `"partial"`
+- `metadata` — series info (titles, frequency, representation)
+
+## Development
+
+```bash
+pip install -e . && pip install pytest
+python -m pytest tests/
+```
+
+## License
+
+MIT

econchile-0.1.0/README.md

@@ -0,0 +1,112 @@
+# econchile
+
+Chilean macroeconomic data (Banco Central de Chile) for Python.
+
+`econchile` is a thin, practical client for the BCCh SIE REST web service. It downloads official series (UF, USD, TPM, IPC_VAR, IPC_INDEX, IMACEC, PIB), parses them into clean, typed data, and keeps a local SQLite cache so repeat queries are instant and your scripts survive API outages.
+
+## Install
+
+Once v0.1 is on PyPI: `pip install econchile`. Until then, install from source:
+
+```bash
+git clone <repo-url> econchile
+cd econchile
+pip install -e .
+```
+
+Requires Python 3.10+.
+
+## Authentication
+
+Request a free API token from the BCCh statistics database (SIE), see the official API documentation.
+
+```bash
+export BCCH_TOKEN="your-token-here"
+```
+
+The library reads `BCCH_TOKEN` from the environment — it does not load `.env` files itself. The token is required for v0.1.
+
+## Quickstart
+
+```python
+from econchile import BcchClient, Series
+
+client = BcchClient()
+
+# Last 3 months of the UF (daily)
+result = client.get(Series.UF, "2024-01-01", "2024-03-31")
+
+for obs in result.observations:
+    print(obs.date, obs.value)
+```
+
+Dates are always `YYYY-MM-DD`. Missing observations have `value=None`.
+
+## The two clients
+
+| Client | Strategy | Best for |
+|--------|----------|----------|
+| `BcchClient` | **Cache-first** — serves from the local cache when fresh, hits the API only on a miss | Interactive use, repeated queries |
+| `OfflineClient` | **API-first** — always tries the API, falls back to the cache when it fails | Cron jobs and scripts that must not crash |
+
+```python
+from econchile.offline import OfflineClient
+
+client = OfflineClient()
+result = client.get(Series.USD, "2024-01-01", "2024-03-31")  # survives API outages
+```
+
+## Available series (v0.1)
+
+| Series | BCCh code | Frequency | Meaning |
+|--------|-----------|-----------|---------|
+| `Series.UF` | `F073.UFF.PRE.Z.D` | daily | Unidad de Fomento |
+| `Series.USD` | `F073.TCO.PRE.Z.D` | daily | Nominal exchange rate (CLP/USD) |
+| `Series.TPM` | `F022.TPM.TIN.D001.NO.Z.D` | daily | Monetary policy rate |
+| `Series.IPC_VAR` | `F074.IPC.VAR.Z.Z.C.M` | monthly | CPI, month-over-month change |
+| `Series.IPC_INDEX` | `F074.IPC.IND.Z.2023.C.M` | monthly | CPI general index (base 2023=100) |
+| `Series.IMACEC` | `F032.IMC.IND.Z.Z.EP18.Z.Z.0.M` | monthly | Economic activity index (base 2018=100) |
+| `Series.PIB` | `F032.PIB.FLU.R.CLP.EP18.Z.Z.0.T` | quarterly | GDP, chained volumes (base 2018) |
+
+More series are planned. Use `client.list_series()` for the full catalog and `client.search("ipc")` to find series by keyword:
+
+```python
+hits = client.search("ipc")     # matches name, code, Spanish and English titles
+for meta in hits:
+    print(meta.series_id, meta.spanish_title)
+```
+
+## Gotchas
+
+- **Date format**: pass `YYYY-MM-DD` to `get()`; the library converts the API's native `DD-MM-YYYY` for you.
+- **Missing data**: the BCCh API marks gaps as "ND". These become `value=None`, not zeros or exceptions, check for `None` before using a value.
+- **Representations**: `IPC_VAR` is a monthly % change, `IPC_INDEX` is a base-2023 index. Same variable, different meaning.
+- **Cache freshness**: cached results are reused for 24 hours by default; configure via `ttl_seconds` on `BcchClient(...)` or `OfflineClient(...)` (the cache lives at `~/.econchile/cache.db`).
+- **Errors**: unknown series raise `KeyError`, malformed dates raise `ValueError`, API failures raise `BcchApiError` and `BcchOfflineError` when the offline fallback is also exhausted.
+
+## API
+
+- `BcchClient.get(series, desde, hasta, use_cache=True)` — fetch a series over a date range; returns a `SeriesResult`.
+- `OfflineClient.get(series, desde, hasta)` — same, but API-first with cache fallback.
+- `BcchClient.search(keyword)` — case- and accent-insensitive catalog search → `list[SeriesMeta]`.
+- `BcchClient.list_series()` — all series metadata → `list[SeriesMeta]`.
+- `BcchClient.clear_cache()` — empty the local cache (returns the number of rows removed).
+
+A `SeriesResult` has:
+
+- `series` — the `Series` member
+- `observations` — list of `Observation(date: str, value: float | None)`
+- `fetched_at` — timestamp (UTC)
+- `source` — `"api"`, `"cache"`, or `"partial"`
+- `metadata` — series info (titles, frequency, representation)
+
+## Development
+
+```bash
+pip install -e . && pip install pytest
+python -m pytest tests/
+```
+
+## License
+
+MIT

econchile-0.1.0/econchile/__init__.py

@@ -0,0 +1,9 @@
+"""econchile — Chilean macroeconomic data, made simple."""
+
+__version__ = "0.1.0"
+
+from econchile.client import BcchClient
+from econchile.series_map import Series
+from econchile.types import SeriesMeta, SeriesResult
+
+__all__ = ["BcchClient", "Series", "SeriesMeta", "SeriesResult", "__version__"]

econchile-0.1.0/econchile/cache.py

@@ -0,0 +1,303 @@
+"""
+SQLite-backed cache for BCCh API responses.
+
+Stores :class:`~econchile.types.SeriesResult` objects with a 24-hour TTL,
+keyed by ``{series}|{desde}|{hasta}``.  The fetcher checks the cache
+before hitting the network; ``offline`` falls back to it when the API is
+down.  Second layer of the fallback chain: API → cache → error.
+
+Stdlib only: ``sqlite3``, ``json``, ``datetime``, ``pathlib``.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+from econchile.series_map import Series
+from econchile.types import BcchCacheError, Observation, SeriesResult
+
+# ─── Defaults ──────────────────────────────────────────────────────────
+
+DEFAULT_DB_PATH: Path = Path.home() / ".econchile" / "cache.db"
+"""Default SQLite database location (created on first use)."""
+
+DEFAULT_TTL_SECONDS: int = 86400
+"""Default time-to-live: 24 hours (BCCh daily series change at most once/day)."""
+
+
+def make_key(series: str, desde: str, hasta: str) -> str:
+    """Build the cache key encoding exactly which query produced the data.
+
+    Different date ranges of the same series are DIFFERENT entries —
+    a cached full-history response must never be served when the user
+    asked for last week.
+
+    Args:
+        series: BCCh series code (e.g. ``"F073.TCO.PRE.Z.D"``) or a
+            :class:`~econchile.series_map.Series` enum member.
+        desde: Start date, ``YYYY-MM-DD``.
+        hasta: End date, ``YYYY-MM-DD``.
+
+    Returns:
+        The cache key ``f"{code}|{desde}|{hasta}"`` where ``code`` is the
+        series' BCCh code (enum members normalised to their ``.value``).
+    """
+    return f"{_series_code(series)}|{desde}|{hasta}"
+
+
+def _series_code(series: str | Series) -> str:
+    """Normalise a series identifier to its BCCh code string."""
+    if isinstance(series, Series):
+        return series.value
+    return str(series)
+
+
+def _observation_to_dict(obs: Observation | dict[str, Any]) -> dict[str, Any]:
+    """Serialise one observation, accepting Observation objects or dicts."""
+    if isinstance(obs, Observation):
+        return {"date": obs.date, "value": obs.value}
+    return {"date": obs["date"], "value": obs["value"]}
+
+
+class Cache:
+    """SQLite-backed cache for :class:`~econchile.types.SeriesResult`.
+
+    Args:
+        db_path: Path to the SQLite database file.  Defaults to
+            ``~/.econchile/cache.db`` (parent directory auto-created).
+        ttl_seconds: How long entries stay fresh.  Default 86400 (24h).
+
+    Raises:
+        BcchCacheError: If the database cannot be opened or created.
+    """
+
+    def __init__(
+        self,
+        db_path: str | Path | None = None,
+        ttl_seconds: int = DEFAULT_TTL_SECONDS,
+    ) -> None:
+        self._db_path = Path(db_path) if db_path is not None else DEFAULT_DB_PATH
+        self._ttl_seconds = ttl_seconds
+        self._memory_conn: sqlite3.Connection | None = None
+        if str(self._db_path) == ":memory:":
+            # :memory: databases live INSIDE a connection — keep one open
+            # for the lifetime of the Cache so the schema survives.
+            self._memory_conn = sqlite3.connect(":memory:")
+        self._init_db()
+
+    # ── Setup ─────────────────────────────────────────────────────────
+
+    def _init_db(self) -> None:
+        """Create the database file and the ``cache`` table if missing."""
+        try:
+            if self._memory_conn is None:
+                self._db_path.parent.mkdir(parents=True, exist_ok=True)
+            conn = self._connect()
+            try:
+                conn.execute(
+                    """
+                    CREATE TABLE IF NOT EXISTS cache (
+                        key        TEXT PRIMARY KEY,
+                        payload    TEXT NOT NULL,
+                        fetched_at TEXT NOT NULL,
+                        expires_at TEXT NOT NULL
+                    )
+                    """
+                )
+            finally:
+                # The old `with self._connect() as conn:` committed the
+                # transaction on exit — replicate that explicitly so file
+                # DBs persist writes before the connection closes.
+                conn.commit()
+                if self._memory_conn is None:
+                    conn.close()
+        except (sqlite3.Error, OSError) as exc:
+            raise BcchCacheError(
+                f"cannot open cache database {self._db_path}: {exc}"
+            ) from exc
+
+    def _connect(self) -> sqlite3.Connection:
+        """Return a connection to the cache database.
+
+        For ``db_path=":memory:"`` this is the one persistent connection
+        held for the life of the Cache (the schema lives inside it); for
+        file-backed caches a fresh connection is opened per call.
+        """
+        if self._memory_conn is not None:
+            return self._memory_conn
+        return sqlite3.connect(str(self._db_path))
+
+    # ── Core API ──────────────────────────────────────────────────────
+
+    def get(self, key: str) -> SeriesResult | None:
+        """Return the cached result for ``key``, or None if missing/expired.
+
+        Expired rows are treated as a miss AND deleted — stale data is
+        never served.
+
+        Raises:
+            BcchCacheError: On SQLite I/O failure.
+        """
+        try:
+            conn = self._connect()
+            try:
+                row = conn.execute(
+                    "SELECT payload, expires_at FROM cache WHERE key = ?",
+                    (key,),
+                ).fetchone()
+                if row is None:
+                    # Not in the cache at all — a plain miss, not an error.
+                    return None
+                payload, expires_at_str = row
+                if datetime.fromisoformat(expires_at_str) < datetime.now():
+                    # Expired: never serve stale data, and delete the row
+                    # so the cache sweeps itself clean on read.
+                    conn.execute("DELETE FROM cache WHERE key = ?", (key,))
+                    return None
+            finally:
+                # The old `with self._connect() as conn:` committed the
+                # transaction on exit — replicate that explicitly so file
+                # DBs persist writes before the connection closes.
+                conn.commit()
+                if self._memory_conn is None:
+                    conn.close()
+        except sqlite3.Error as exc:
+            raise BcchCacheError(f"cache read failed for {key!r}: {exc}") from exc
+        return self._reconstruct(payload)
+
+    def set(self, key: str, result: SeriesResult) -> None:
+        """Store ``result`` under ``key`` (upsert).
+
+        Sets ``fetched_at`` = now and ``expires_at`` = now + TTL.
+
+        Raises:
+            BcchCacheError: On SQLite I/O failure.
+        """
+        payload = self._serialize(result)
+        now = datetime.now()
+        expires_at = now + timedelta(seconds=self._ttl_seconds)
+        try:
+            conn = self._connect()
+            try:
+                conn.execute(
+                    """
+                    INSERT OR REPLACE INTO cache (key, payload, fetched_at, expires_at)
+                    VALUES (?, ?, ?, ?)
+                    """,
+                    (key, payload, now.isoformat(), expires_at.isoformat()),
+                )
+            finally:
+                # The old `with self._connect() as conn:` committed the
+                # transaction on exit — replicate that explicitly so file
+                # DBs persist writes before the connection closes.
+                conn.commit()
+                if self._memory_conn is None:
+                    conn.close()
+        except sqlite3.Error as exc:
+            raise BcchCacheError(f"cache write failed for {key!r}: {exc}") from exc
+
+    # ── Convenience: series + date range ──────────────────────────────
+
+    def get_series(
+        self, series: str | Series, desde: str, hasta: str
+    ) -> SeriesResult | None:
+        """Convenience: :meth:`get` with a key built from components."""
+        return self.get(make_key(_series_code(series), desde, hasta))
+
+    def set_series(
+        self, series: str | Series, desde: str, hasta: str, result: SeriesResult
+    ) -> None:
+        """Convenience: :meth:`set` with a key built from components."""
+        self.set(make_key(_series_code(series), desde, hasta), result)
+
+    # ── Cache management ──────────────────────────────────────────────
+
+    def clear(self) -> int:
+        """Delete every row.  Returns the number of rows removed.
+
+        Raises:
+            BcchCacheError: On SQLite I/O failure.
+        """
+        try:
+            conn = self._connect()
+            try:
+                cursor = conn.execute("DELETE FROM cache")
+                return cursor.rowcount
+            finally:
+                # The old `with self._connect() as conn:` committed the
+                # transaction on exit — replicate that explicitly so file
+                # DBs persist writes before the connection closes.
+                conn.commit()
+                if self._memory_conn is None:
+                    conn.close()
+        except sqlite3.Error as exc:
+            raise BcchCacheError(f"cache clear failed: {exc}") from exc
+
+    def size(self) -> int:
+        """Return the number of entries currently stored.
+
+        Raises:
+            BcchCacheError: On SQLite I/O failure.
+        """
+        try:
+            conn = self._connect()
+            try:
+                return conn.execute("SELECT COUNT(*) FROM cache").fetchone()[0]
+            finally:
+                # The old `with self._connect() as conn:` committed the
+                # transaction on exit — replicate that explicitly so file
+                # DBs persist writes before the connection closes.
+                conn.commit()
+                if self._memory_conn is None:
+                    conn.close()
+        except sqlite3.Error as exc:
+            raise BcchCacheError(f"cache size query failed: {exc}") from exc
+
+    # ── Serialisation ─────────────────────────────────────────────────
+
+    @staticmethod
+    def _serialize(result: SeriesResult) -> str:
+        """JSON-serialise a SeriesResult for the ``payload`` column.
+
+        Mirrors ``SeriesResult.to_dict()`` but accepts observations as
+        either ``Observation`` objects or plain dicts.
+        """
+        return json.dumps(
+            {
+                "series": (
+                    result.series.value
+                    if hasattr(result.series, "value")
+                    else str(result.series)
+                ),
+                "observations": [_observation_to_dict(o) for o in result.observations],
+                "fetched_at": result.fetched_at.isoformat(),
+                "source": result.source,
+                "metadata": result.metadata,
+            }
+        )
+
+    @staticmethod
+    def _reconstruct(payload: str) -> SeriesResult:
+        """Rebuild a SeriesResult from a stored JSON payload."""
+        data: dict[str, Any] = json.loads(payload)
+        try:
+            # Recover the enum member when the code is in the v0.1 catalog…
+            series = Series.from_code(data["series"])
+        except KeyError:
+            # …otherwise keep the raw code string (graceful degradation).
+            series = data["series"]
+        observations = [
+            Observation(date=obs["date"], value=obs["value"])
+            for obs in data["observations"]
+        ]
+        return SeriesResult(
+            series=series,
+            observations=observations,
+            fetched_at=datetime.fromisoformat(data["fetched_at"]),
+            source=data.get("source", "cache"),
+            metadata=data.get("metadata", {}),
+        )