tesorotools-python 0.0.44__tar.gz → 0.0.45__tar.gz

{tesorotools_python-0.0.44 → tesorotools_python-0.0.45}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tesorotools-python
-Version: 0.0.44
+Version: 0.0.45
 Requires-Python: >=3.13
 Requires-Dist: babel>=2.17
 Requires-Dist: matplotlib>=3.10
@@ -16,5 +16,8 @@ Provides-Extra: bde
 Requires-Dist: requests>=2.31; extra == 'bde'
 Provides-Extra: ecb
 Requires-Dist: requests>=2.31; extra == 'ecb'
+Provides-Extra: imf
+Requires-Dist: requests>=2.31; extra == 'imf'
+Requires-Dist: truststore>=0.10; extra == 'imf'
 Provides-Extra: lseg
 Requires-Dist: lseg-data>=2.1; extra == 'lseg'

{tesorotools_python-0.0.44 → tesorotools_python-0.0.45}/pyproject.toml

@@ -27,6 +27,7 @@ dependencies = [
 [project.optional-dependencies]
 bde = ["requests>=2.31"]
 ecb = ["requests>=2.31"]
+imf = ["requests>=2.31", "truststore>=0.10"]
 lseg = ["lseg-data>=2.1"]
 
 [dependency-groups]

{tesorotools_python-0.0.44 → tesorotools_python-0.0.45}/src/tesorotools/providers/__init__.py

@@ -1,9 +1,10 @@
 """Public provider API.
 
-``BdeProvider``, ``EcbProvider`` and ``LSEGProvider`` depend on
-the optional ``[bde]`` / ``[ecb]`` / ``[lseg]`` extras and are
-imported lazily through ``__getattr__``; importing
-``tesorotools.providers`` itself does not require those extras.
+``BdeProvider``, ``EcbProvider``, ``ImfIrfclProvider`` and
+``LSEGProvider`` depend on the optional ``[bde]`` / ``[ecb]`` /
+``[imf]`` / ``[lseg]`` extras and are imported lazily through
+``__getattr__``; importing ``tesorotools.providers`` itself does not
+require those extras.
 """
 
 from typing import TYPE_CHECKING, Any
@@ -17,12 +18,14 @@ from tesorotools.providers.base import (
 if TYPE_CHECKING:
     from tesorotools.providers.bde import BdeProvider
     from tesorotools.providers.ecb import EcbProvider
+    from tesorotools.providers.imf_irfcl import ImfIrfclProvider
     from tesorotools.providers.lseg import LSEGProvider
 
 __all__ = [
     "BdeProvider",
     "DataProvider",
     "EcbProvider",
+    "ImfIrfclProvider",
     "LSEGProvider",
     "RegistryProtocol",
     "bootstrap_providers",
@@ -38,6 +41,10 @@ def __getattr__(name: str) -> Any:
         from tesorotools.providers.ecb import EcbProvider
 
         return EcbProvider
+    if name == "ImfIrfclProvider":
+        from tesorotools.providers.imf_irfcl import ImfIrfclProvider
+
+        return ImfIrfclProvider
     if name == "LSEGProvider":
         from tesorotools.providers.lseg import LSEGProvider
 

tesorotools_python-0.0.45/src/tesorotools/providers/imf_irfcl.py

@@ -0,0 +1,242 @@
+"""IMF IRFCL data provider via the official SDMX 3.0 REST API.
+
+Downloads time series from the IMF's IRFCL dataflow (International
+Reserves and Foreign Currency Liquidity), which publishes official
+reserve assets per country, gold included.  No authentication
+required.
+
+Install with the ``imf`` optional extra::
+
+    uv pip install "tesorotools-python[imf]"
+
+Indicators (verified against the API in jun-2026):
+
+* ``IRFCLDT1_IRFCL56V_FTO`` — gold, VOLUME in fine troy ounces.  This
+  is the **physical stock** (despite the IMF label saying "millions of
+  ounces", the raw value comes in ounces: Spain ≈ 9,053,750 oz ≈
+  281.6 t).
+* ``IRFCLDT1_IRFCL56_USD`` — gold value in USD (approx. market value).
+* ``IRFCLDT1_IRFCL65_USD`` — TOTAL official reserve assets in USD
+  (denominator of the % gold represents over reserves).
+
+API base
+--------
+``https://api.imf.org/external/sdmx/3.0/data/dataflow/IMF.STA/IRFCL/~/{key}``
+
+Code convention (4 dimensions of DSD_IRFCL_PUB)
+-----------------------------------------------
+::
+
+    {COUNTRY}.{INDICATOR}.{SECTOR}.{FREQUENCY}
+
+* COUNTRY    ISO-3 country code (``ESP``, ``USA``, ``DEU`` …).
+* INDICATOR  the IRFCL indicator (``IRFCLDT1_IRFCL56V_FTO`` …).
+* SECTOR     ``*`` (wildcard).  Countries report gold under different
+             sectors (Spain ``S1X``, the US ``S1XS1311`` …); the
+             wildcard captures them all.  When a key returns several
+             series (same gold total under different sectors) they are
+             collapsed by date in :meth:`_fetch_one` (last write wins;
+             values coincide).
+* FREQUENCY  ``M`` (monthly; reserves are published every month).
+
+Keys are passed verbatim to the API; this provider does not parse them.
+
+Date label
+----------
+IRFCL labels the period and the observation is the end-of-period
+balance.  We map to the real end of period:
+
+* ``"2026"``     → 2026-12-31
+* ``"2026-Q1"``  → 2026-03-31
+* ``"2026-M04"`` → 2026-04-30
+
+Corporate TLS
+-------------
+``truststore`` is enabled on import (if installed) so the provider
+works behind MINECO's TLS proxy without ``verify=False``.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import ClassVar
+
+import pandas as pd
+import requests
+
+from tesorotools.providers.base import DataProvider
+
+logger = logging.getLogger(__name__)
+
+
+def _enable_truststore_once() -> bool:
+    """Enable truststore (the OS cert store) if available."""
+    try:
+        import truststore  # type: ignore[import-not-found]
+    except ImportError:
+        return False
+    truststore.inject_into_ssl()  # pyright: ignore[reportUnknownMemberType]
+    return True
+
+
+_TRUSTSTORE_ACTIVE = _enable_truststore_once()
+
+_API_BASE = (
+    "https://api.imf.org/external/sdmx/3.0/data/dataflow/IMF.STA/IRFCL/~"
+)
+_DEFAULT_TIMEOUT = 60
+_DEFAULT_START = "2000"
+_HEADERS = {"Accept": "application/vnd.sdmx.data+json"}
+
+
+class ImfIrfclProvider(DataProvider):
+    """Provider that downloads IMF IRFCL series via SDMX 3.0.
+
+    One HTTP request per key.  Series with no observations (a country
+    that does not report that indicator) are skipped with a warning
+    instead of aborting the whole download.
+
+    Parameters
+    ----------
+    timeout
+        Max seconds per HTTP request.
+    session
+        Optional pre-built ``requests.Session``.  Useful for tests or
+        for custom retry policies.
+    """
+
+    PROVIDER_NAME: ClassVar[str] = "imf_irfcl"
+
+    def __init__(
+        self,
+        *,
+        timeout: int = _DEFAULT_TIMEOUT,
+        session: requests.Session | None = None,
+    ) -> None:
+        self._timeout = timeout
+        self._session = session or requests.Session()
+
+    def fetch(
+        self,
+        codes: list[str],
+        start: str | None = None,
+        end: str | None = None,
+    ) -> pd.DataFrame:
+        """Download a list of IRFCL keys and return a wide DataFrame.
+
+        Parameters
+        ----------
+        codes
+            List of IRFCL keys (``"{COUNTRY}.{INDICATOR}.{SECTOR}.{FREQ}"``).
+        start
+            Start period (e.g. ``"2024"``).  If ``None`` defaults to
+            ``"2000"``.
+        end
+            End date as ISO string.  If ``None`` up to latest.
+
+        Returns
+        -------
+        pd.DataFrame
+            Wide DataFrame. Index = dates (tz-naive), columns = the
+            requested codes. Missing observations are NaN.
+        """
+        if not codes:
+            return pd.DataFrame()
+
+        cols: dict[str, pd.Series[float]] = {}
+        for code in codes:
+            try:
+                series = self._fetch_one(code, start=start)
+            except requests.RequestException as e:
+                logger.warning("IRFCL: failed downloading %s (%s)", code, e)
+                continue
+            if series is not None and not series.empty:
+                cols[code] = series
+
+        if not cols:
+            return pd.DataFrame()
+
+        df = pd.DataFrame(cols).sort_index()
+        df.index.name = "date"
+        if end:
+            df = df.loc[df.index <= pd.Timestamp(end)]
+        return df
+
+    def is_available(self) -> bool:
+        """Check whether the IMF API responds.
+
+        Hits a small ESP gold-volume query.
+        """
+        try:
+            r = self._session.get(
+                f"{_API_BASE}/ESP.IRFCLDT1_IRFCL56V_FTO.*.M?startPeriod=2024",
+                timeout=10,
+                headers=_HEADERS,
+            )
+            return r.status_code == 200
+        except requests.RequestException:
+            return False
+
+    def _fetch_one(
+        self, code: str, start: str | None = None
+    ) -> "pd.Series[float] | None":
+        """Download a single IRFCL series and return it as a Series."""
+        url = f"{_API_BASE}/{code}?startPeriod={start or _DEFAULT_START}"
+        r = self._session.get(url, timeout=self._timeout, headers=_HEADERS)
+        if r.status_code != 200:
+            logger.warning("IRFCL: HTTP %d for %s", r.status_code, code)
+            return None
+        payload = r.json()
+        data_sets = payload.get("data", {}).get("dataSets", [])
+        structures = payload.get("data", {}).get("structures", [])
+        if not data_sets or not structures:
+            return None
+        time_dim = structures[0].get("dimensions", {}).get("observation", [])
+        if not time_dim:
+            return None
+        time_values = [t["value"] for t in time_dim[0].get("values", [])]
+        series_dict = data_sets[0].get("series", {})
+
+        data: dict[pd.Timestamp, float] = {}
+        for _, series in series_dict.items():
+            observations = series.get("observations", {})
+            for idx_str, payload_obs in observations.items():
+                if not payload_obs or payload_obs[0] is None:
+                    continue
+                try:
+                    value = float(payload_obs[0])
+                except (TypeError, ValueError):
+                    continue
+                idx = int(idx_str)
+                if idx >= len(time_values):
+                    continue
+                ts = _parse_period(time_values[idx])
+                if ts is not None:
+                    data[ts] = value
+
+        if not data:
+            return None
+        return pd.Series(data, dtype="float64").sort_index()
+
+
+def _parse_period(label: str) -> pd.Timestamp | None:
+    """Convert an IRFCL label to the **real end of period**.
+
+    * ``"YYYY"``     → December 31 of that year.
+    * ``"YYYY-QN"``  → last day of the quarter.
+    * ``"YYYY-MNN"`` → last day of the month.
+    """
+    try:
+        if "-Q" in label:
+            period = pd.Period(label.replace("-Q", "Q"), freq="Q")
+            return period.end_time.normalize()
+        if "-M" in label:  # "YYYY-MNN"
+            year_str, month_str = label.split("-M")
+            period = pd.Period(
+                freq="M", year=int(year_str), month=int(month_str)
+            )
+            return period.end_time.normalize()
+        year = int(label)
+        return pd.Timestamp(year=year, month=12, day=31)
+    except (ValueError, TypeError):
+        return None