pydeflate 2.1.2__tar.gz → 2.2.0__tar.gz

{pydeflate-2.1.2 → pydeflate-2.2.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021-2024, Jorge Rivera
+Copyright (c) 2021-2025, Jorge Rivera
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

pydeflate-2.1.2/README.md → pydeflate-2.2.0/PKG-INFO

@@ -1,3 +1,28 @@
+Metadata-Version: 2.4
+Name: pydeflate
+Version: 2.2.0
+Summary: Package to convert current prices figures to constant prices and vice versa
+Author: Jorge Rivera
+Author-email: Jorge Rivera <Jorge.Rivera@one.org>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: hdx-python-country>=3.9.8
+Requires-Dist: imf-reader>=1.3.0
+Requires-Dist: oda-reader>=1.2.2
+Requires-Dist: pandas>=2.0
+Requires-Dist: pandera>=0.20.0
+Requires-Dist: pyarrow>=17.0
+Requires-Dist: requests>=2.32.5
+Requires-Dist: wbgapi>=1.0.12
+Requires-Dist: platformdirs>=3.0.0
+Requires-Dist: filelock>=3.15.0
+Maintainer: Jorge Rivera
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/jm-rivera/pydeflate
+Project-URL: Issues, https://github.com/jm-rivera/pydeflate/issues
+Project-URL: Repository, https://github.com/jm-rivera/pydeflate
+Description-Content-Type: text/markdown
+
 # pydeflate
 
 [![pypi](https://img.shields.io/pypi/v/pydeflate.svg)](https://pypi.python.org/pypi/pydeflate)
@@ -257,4 +282,104 @@ Pydeflate relies on data from external sources. If there are missing values in t
 
 Pydeflate periodically updates its underlying data from the World Bank, IMF, and OECD. If the data on your system is older than 50 days, pydeflate will display a warning upon import.
 
+## Advanced Features
+
+### Error Handling
+
+Pydeflate v2.1.3+ provides specific exception types for better error handling:
+
+```python
+from pydeflate import imf_gdp_deflate
+from pydeflate.exceptions import NetworkError, ConfigurationError, MissingDataError
+
+try:
+    result = imf_gdp_deflate(df, base_year=2015, source_currency="USA", target_currency="EUR")
+except NetworkError as e:
+    # Handle network failures (retry, fallback to cached data, etc.)
+    print(f"Network error: {e}")
+    # Implement retry logic
+except ConfigurationError as e:
+    # Handle invalid parameters (wrong currency codes, missing columns, etc.)
+    print(f"Configuration error: {e}")
+    raise
+except MissingDataError as e:
+    # Handle missing deflator/exchange data for specific country-year combinations
+    print(f"Missing data: {e}")
+    # Use alternative source or fill gaps
+```
+
+Available exception types:
+- `PydeflateError`: Base exception for all pydeflate errors
+- `NetworkError`: Network-related failures
+- `ConfigurationError`: Invalid parameters or configuration
+- `DataSourceError`: Issues loading or parsing data from sources
+- `CacheError`: Cache operation failures
+- `MissingDataError`: Required deflator/exchange data unavailable
+- `SchemaValidationError`: Data validation failures
+
+### Custom Data Sources (Plugin System)
+
+You can register custom data sources without modifying pydeflate's code:
+
+```python
+from pydeflate.plugins import register_source, list_sources
+
+# Define your custom source
+@register_source("my_central_bank")
+class MyCentralBankSource:
+    def __init__(self, update: bool = False):
+        self.name = "my_central_bank"
+        self.data = self.load_my_data(update)  # Your data loading logic
+        self._idx = ["pydeflate_year", "pydeflate_entity_code", "pydeflate_iso3"]
+
+    def lcu_usd_exchange(self):
+        # Return exchange rate data
+        return self.data.filter(self._idx + ["pydeflate_EXCHANGE"])
+
+    def price_deflator(self, kind="NGDP_D"):
+        # Return deflator data
+        return self.data.filter(self._idx + [f"pydeflate_{kind}"])
+
+    def validate(self):
+        # Validate data format
+        if self.data.empty:
+            raise ValueError("No data loaded")
+
+# List all available sources
+print(list_sources())  # ['DAC', 'IMF', 'World Bank', 'my_central_bank', ...]
+
+# Your custom source is now available for use with pydeflate
+```
+
+### Advanced Configuration
+
+For advanced use cases, you can use context managers to customize pydeflate's behavior:
+
+```python
+from pydeflate.context import pydeflate_session
+import logging
+
+# Use a custom cache directory and logging level
+with pydeflate_session(data_dir="/tmp/my_cache", log_level=logging.DEBUG) as ctx:
+    result = imf_gdp_deflate(df, base_year=2015, ...)
+    # Data is cached in /tmp/my_cache
+    # Debug logging is enabled
+
+# Or set a default context for your entire application
+from pydeflate.context import PydeflateContext, set_default_context
+
+ctx = PydeflateContext.create(
+    data_dir="/app/data/pydeflate_cache",
+    log_level=logging.INFO
+)
+set_default_context(ctx)
+
+# All subsequent pydeflate operations use this configuration
+```
+
+This is useful for:
+- Using different cache directories for different projects
+- Running multiple pydeflate operations in parallel without cache conflicts
+- Customizing logging verbosity
+- Testing with temporary cache directories
 

pydeflate-2.1.2/PKG-INFO → pydeflate-2.2.0/README.md

@@ -1,26 +1,3 @@
-Metadata-Version: 2.3
-Name: pydeflate
-Version: 2.1.2
-Summary: Package to convert current prices figures to constant prices and vice versa
-License: MIT
-Author: Jorge Rivera
-Author-email: jorge.rivera@one.org
-Requires-Python: >=3.10, <4.0
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: hdx-python-country (>=3.8,<4.0.0)
-Requires-Dist: imf-reader (>=1.2.0,<2.0.0)
-Requires-Dist: oda-reader (>=1.0.5,<2.0.0)
-Requires-Dist: pandas (>=2.2.3,<3.0.0)
-Requires-Dist: pyarrow (>=14.0)
-Requires-Dist: requests (>=2.32.3,<3.0.0)
-Requires-Dist: wbgapi (>=1.0.12,<2.0.0)
-Description-Content-Type: text/markdown
-
 # pydeflate
 
 [![pypi](https://img.shields.io/pypi/v/pydeflate.svg)](https://pypi.python.org/pypi/pydeflate)
@@ -280,5 +257,104 @@ Pydeflate relies on data from external sources. If there are missing values in t
 
 Pydeflate periodically updates its underlying data from the World Bank, IMF, and OECD. If the data on your system is older than 50 days, pydeflate will display a warning upon import.
 
+## Advanced Features
+
+### Error Handling
+
+Pydeflate v2.1.3+ provides specific exception types for better error handling:
+
+```python
+from pydeflate import imf_gdp_deflate
+from pydeflate.exceptions import NetworkError, ConfigurationError, MissingDataError
+
+try:
+    result = imf_gdp_deflate(df, base_year=2015, source_currency="USA", target_currency="EUR")
+except NetworkError as e:
+    # Handle network failures (retry, fallback to cached data, etc.)
+    print(f"Network error: {e}")
+    # Implement retry logic
+except ConfigurationError as e:
+    # Handle invalid parameters (wrong currency codes, missing columns, etc.)
+    print(f"Configuration error: {e}")
+    raise
+except MissingDataError as e:
+    # Handle missing deflator/exchange data for specific country-year combinations
+    print(f"Missing data: {e}")
+    # Use alternative source or fill gaps
+```
+
+Available exception types:
+- `PydeflateError`: Base exception for all pydeflate errors
+- `NetworkError`: Network-related failures
+- `ConfigurationError`: Invalid parameters or configuration
+- `DataSourceError`: Issues loading or parsing data from sources
+- `CacheError`: Cache operation failures
+- `MissingDataError`: Required deflator/exchange data unavailable
+- `SchemaValidationError`: Data validation failures
+
+### Custom Data Sources (Plugin System)
+
+You can register custom data sources without modifying pydeflate's code:
+
+```python
+from pydeflate.plugins import register_source, list_sources
+
+# Define your custom source
+@register_source("my_central_bank")
+class MyCentralBankSource:
+    def __init__(self, update: bool = False):
+        self.name = "my_central_bank"
+        self.data = self.load_my_data(update)  # Your data loading logic
+        self._idx = ["pydeflate_year", "pydeflate_entity_code", "pydeflate_iso3"]
+
+    def lcu_usd_exchange(self):
+        # Return exchange rate data
+        return self.data.filter(self._idx + ["pydeflate_EXCHANGE"])
+
+    def price_deflator(self, kind="NGDP_D"):
+        # Return deflator data
+        return self.data.filter(self._idx + [f"pydeflate_{kind}"])
+
+    def validate(self):
+        # Validate data format
+        if self.data.empty:
+            raise ValueError("No data loaded")
+
+# List all available sources
+print(list_sources())  # ['DAC', 'IMF', 'World Bank', 'my_central_bank', ...]
+
+# Your custom source is now available for use with pydeflate
+```
+
+### Advanced Configuration
+
+For advanced use cases, you can use context managers to customize pydeflate's behavior:
+
+```python
+from pydeflate.context import pydeflate_session
+import logging
+
+# Use a custom cache directory and logging level
+with pydeflate_session(data_dir="/tmp/my_cache", log_level=logging.DEBUG) as ctx:
+    result = imf_gdp_deflate(df, base_year=2015, ...)
+    # Data is cached in /tmp/my_cache
+    # Debug logging is enabled
+
+# Or set a default context for your entire application
+from pydeflate.context import PydeflateContext, set_default_context
+
+ctx = PydeflateContext.create(
+    data_dir="/app/data/pydeflate_cache",
+    log_level=logging.INFO
+)
+set_default_context(ctx)
+
+# All subsequent pydeflate operations use this configuration
+```
 
+This is useful for:
+- Using different cache directories for different projects
+- Running multiple pydeflate operations in parallel without cache conflicts
+- Customizing logging verbosity
+- Testing with temporary cache directories
 

pydeflate-2.2.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "pydeflate"
+version = "2.2.0"
+description = "Package to convert current prices figures to constant prices and vice versa"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "Jorge Rivera", email = "Jorge.Rivera@one.org" }]
+maintainers = [{ name = "Jorge Rivera" }]
+license = "MIT"
+license-files = ["LICENSE*"]
+
+dependencies = [
+    "hdx-python-country>=3.9.8",
+    "imf-reader>=1.3.0",
+    "oda-reader>=1.2.2",
+    "pandas>=2.0",
+    "pandera>=0.20.0",
+    "pyarrow>=17.0",
+    "requests>=2.32.5",
+    "wbgapi>=1.0.12",
+    "platformdirs>=3.0.0",
+    "filelock>=3.15.0",
+]
+
+[dependency-groups]
+dev = [
+    "hypothesis>=6.122.3",
+    "pandas-stubs>=2.3.2.250926",
+    "pytest>=8.4.2",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.13.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/jm-rivera/pydeflate"
+Repository = "https://github.com/jm-rivera/pydeflate"
+Issues = "https://github.com/jm-rivera/pydeflate/issues"
+
+
+[build-system]
+requires = ["uv_build>=0.8.22,<0.9.0"]
+build-backend = "uv_build"

pydeflate-2.2.0/src/pydeflate/__init__.py

@@ -0,0 +1,91 @@
+__author__ = """Jorge Rivera"""
+__version__ = "2.2.0"
+
+from pydeflate.deflate.deflators import (
+    imf_cpi_deflate,
+    imf_cpi_e_deflate,
+    imf_gdp_deflate,
+    oecd_dac_deflate,
+    wb_cpi_deflate,
+    wb_gdp_deflate,
+    wb_gdp_linked_deflate,
+)
+from pydeflate.deflate.legacy_deflate import deflate
+from pydeflate.exchange.exchangers import (
+    imf_exchange,
+    oecd_dac_exchange,
+    wb_exchange,
+    wb_exchange_ppp,
+)
+from pydeflate.pydeflate_config import set_data_dir, setup_logger
+
+from pydeflate.context import (
+    PydeflateContext,
+    get_default_context,
+    pydeflate_session,
+    set_default_context,
+    temporary_context,
+)
+from pydeflate.exceptions import (
+    CacheError,
+    ConfigurationError,
+    DataSourceError,
+    MissingDataError,
+    NetworkError,
+    PluginError,
+    PydeflateError,
+    SchemaValidationError,
+)
+from pydeflate.plugins import (
+    get_source,
+    is_source_registered,
+    list_sources,
+    register_source,
+)
+
+
+def set_pydeflate_path(path):
+    """Set the path to the pydeflate data cache directory."""
+
+    return set_data_dir(path)
+
+
+__all__ = [
+    # Deflation functions
+    "deflate",
+    "imf_cpi_deflate",
+    "imf_cpi_e_deflate",
+    "imf_gdp_deflate",
+    "oecd_dac_deflate",
+    "wb_cpi_deflate",
+    "wb_gdp_deflate",
+    "wb_gdp_linked_deflate",
+    # Exchange functions
+    "imf_exchange",
+    "oecd_dac_exchange",
+    "wb_exchange",
+    "wb_exchange_ppp",
+    # Configuration
+    "set_pydeflate_path",
+    "setup_logger",
+    # Context management
+    "PydeflateContext",
+    "get_default_context",
+    "pydeflate_session",
+    "set_default_context",
+    "temporary_context",
+    # Exceptions
+    "CacheError",
+    "ConfigurationError",
+    "DataSourceError",
+    "MissingDataError",
+    "NetworkError",
+    "PluginError",
+    "PydeflateError",
+    "SchemaValidationError",
+    # Plugin system
+    "get_source",
+    "is_source_registered",
+    "list_sources",
+    "register_source",
+]

pydeflate-2.2.0/src/pydeflate/cache.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Callable, Dict, Iterable, Optional
+
+from filelock import FileLock
+
+from pydeflate.pydeflate_config import get_data_dir
+
+ISO_FORMAT = "%Y-%m-%dT%H:%M:%S.%f%z"
+
+
+@dataclass(frozen=True)
+class CacheEntry:
+    """Describe a cacheable dataset."""
+
+    key: str
+    filename: str
+    fetcher: Callable[[Path], None]
+    ttl_days: int = 30
+    version: str | None = None
+
+
+@dataclass(frozen=True)
+class CacheRecord:
+    key: str
+    path: Path
+    downloaded_at: datetime
+    ttl_days: int
+    version: str | None
+
+
+class CacheError(RuntimeError):
+    pass
+
+
+class CacheManager:
+    """Handle cached datasets stored under the pydeflate data directory."""
+
+    def __init__(self, base_dir: Path | None = None) -> None:
+        self.base_dir = (base_dir or get_data_dir()).resolve()
+        self.base_dir.mkdir(parents=True, exist_ok=True)
+        self.manifest_path = self.base_dir / "manifest.json"
+        self._lock = FileLock(str(self.base_dir / ".cache.lock"))
+        self._manifest: Dict[str, dict] = self._load_manifest()
+
+    # ------------------------------------------------------------------
+    def ensure(self, entry: CacheEntry, *, refresh: bool = False) -> Path:
+        """Return a local path for the given entry, downloading when needed."""
+
+        with self._lock:
+            record = self._manifest.get(entry.key)
+            path = self.base_dir / entry.filename
+
+            if not refresh and record and path.exists():
+                if not self._is_stale(record, entry):
+                    return path
+
+            path.parent.mkdir(parents=True, exist_ok=True)
+            tmp_path = Path(f"{path}.tmp-{os.getpid()}")
+            try:
+                entry.fetcher(tmp_path)
+                tmp_path.replace(path)
+            finally:
+                if tmp_path.exists():
+                    tmp_path.unlink(missing_ok=True)
+
+            self._manifest[entry.key] = {
+                "filename": entry.filename,
+                "downloaded_at": datetime.now(timezone.utc).strftime(ISO_FORMAT),
+                "ttl_days": entry.ttl_days,
+                "version": entry.version,
+            }
+            self._save_manifest()
+            return path
+
+    # ------------------------------------------------------------------
+    def list_records(self) -> Iterable[CacheRecord]:
+        for key, payload in self._manifest.items():
+            path = self.base_dir / payload["filename"]
+            yield CacheRecord(
+                key=key,
+                path=path,
+                downloaded_at=datetime.strptime(payload["downloaded_at"], ISO_FORMAT),
+                ttl_days=payload["ttl_days"],
+                version=payload.get("version"),
+            )
+
+    # ------------------------------------------------------------------
+    def clear(self, key: str | None = None) -> None:
+        with self._lock:
+            if key is None:
+                for payload in self._manifest.values():
+                    (self.base_dir / payload["filename"]).unlink(missing_ok=True)
+                self._manifest = {}
+            else:
+                payload = self._manifest.pop(key, None)
+                if payload:
+                    (self.base_dir / payload["filename"]).unlink(missing_ok=True)
+            self._save_manifest()
+
+    # ------------------------------------------------------------------
+    def _is_stale(self, record: dict, entry: CacheEntry) -> bool:
+        version_changed = entry.version is not None and entry.version != record.get(
+            "version"
+        )
+        downloaded = datetime.strptime(record["downloaded_at"], ISO_FORMAT)
+        age = datetime.now(timezone.utc) - downloaded
+        ttl = timedelta(days=entry.ttl_days)
+        return version_changed or age > ttl
+
+    # ------------------------------------------------------------------
+    def _load_manifest(self) -> Dict[str, dict]:
+        if not self.manifest_path.exists():
+            return {}
+        try:
+            return json.loads(self.manifest_path.read_text())
+        except json.JSONDecodeError:
+            return {}
+
+    # ------------------------------------------------------------------
+    def _save_manifest(self) -> None:
+        payload = json.dumps(self._manifest, indent=2)
+        self.manifest_path.write_text(payload)
+
+
+_CACHE_MANAGER: Optional[CacheManager] = None
+
+
+def cache_manager() -> CacheManager:
+    global _CACHE_MANAGER
+    base_dir = get_data_dir().resolve()
+    if _CACHE_MANAGER is None or _CACHE_MANAGER.base_dir != base_dir:
+        _CACHE_MANAGER = CacheManager(base_dir)
+    return _CACHE_MANAGER

pydeflate-2.2.0/src/pydeflate/constants.py

@@ -0,0 +1,121 @@
+"""Constants used throughout pydeflate.
+
+Centralizing constants eliminates magic strings and makes refactoring safer.
+"""
+
+from __future__ import annotations
+
+
+class PydeflateColumns:
+    """Standard column names used in pydeflate DataFrames."""
+
+    # Index columns
+    YEAR = "pydeflate_year"
+    ENTITY_CODE = "pydeflate_entity_code"
+    ISO3 = "pydeflate_iso3"
+
+    # Data columns
+    EXCHANGE = "pydeflate_EXCHANGE"
+    EXCHANGE_D = "pydeflate_EXCHANGE_D"
+
+    # Deflator columns
+    NGDP_D = "pydeflate_NGDP_D"
+    NGDP_DL = "pydeflate_NGDP_DL"
+    CPI = "pydeflate_CPI"
+    PCPI = "pydeflate_PCPI"
+    PCPIE = "pydeflate_PCPIE"
+    DAC_DEFLATOR = "pydeflate_DAC_DEFLATOR"
+
+    # Standard index
+    STANDARD_INDEX = [YEAR, ENTITY_CODE, ISO3]
+
+    @classmethod
+    def deflator_column(cls, kind: str) -> str:
+        """Get deflator column name for a given kind.
+
+        Args:
+            kind: Deflator type (e.g., 'NGDP_D', 'CPI')
+
+        Returns:
+            Full column name with pydeflate_ prefix
+        """
+        if kind.startswith("pydeflate_"):
+            return kind
+        return f"pydeflate_{kind}"
+
+
+class CurrencyCodes:
+    """Common currency code mappings."""
+
+    # ISO3 to common codes
+    USD = "USA"
+    EUR = "EUR"  # For most sources
+    EUR_DAC = "EUI"  # For DAC source
+    GBP = "GBR"
+    JPY = "JPN"
+    CAD = "CAN"
+
+    # Special codes
+    LCU = "LCU"  # Local Currency Unit
+    PPP = "PPP"  # Purchasing Power Parity
+    DAC = "DAC"  # DAC members
+
+    # Mapping for user convenience
+    COMMON_ALIASES = {
+        "USD": USA,
+        "EUR": EUR,
+        "GBP": GBR,
+        "JPY": JPN,
+        "CAD": CAN,
+    }
+
+    @classmethod
+    def resolve(cls, code: str, source: str | None = None) -> str:
+        """Resolve a currency code to ISO3.
+
+        Args:
+            code: Currency code (USD, EUR, etc.) or ISO3
+            source: Data source name (affects EUR mapping for DAC)
+
+        Returns:
+            ISO3 country code or special code (LCU, PPP)
+        """
+        # Handle EUR special case for DAC
+        if code == "EUR" and source == "DAC":
+            return cls.EUR_DAC
+
+        # Try aliases
+        return cls.COMMON_ALIASES.get(code, code)
+
+
+class DataSources:
+    """Names of built-in data sources."""
+
+    IMF = "IMF"
+    WORLD_BANK = "World Bank"
+    WORLD_BANK_PPP = "World Bank PPP"
+    DAC = "DAC"
+
+    # Aliases
+    WB = "World Bank"
+    OECD = "DAC"
+
+    ALL_SOURCES = [IMF, WORLD_BANK, WORLD_BANK_PPP, DAC]
+
+
+class CacheDefaults:
+    """Default values for caching."""
+
+    TTL_DAYS_IMF = 60  # IMF data updates less frequently
+    TTL_DAYS_WB = 30  # World Bank monthly updates
+    TTL_DAYS_DAC = 30  # DAC data
+    DEFAULT_TTL = 30
+
+
+class ValidationConfig:
+    """Validation configuration."""
+
+    MIN_YEAR = 1960  # No data before 1960
+    MAX_YEAR = 2100  # No projections beyond 2100
+    MIN_EXCHANGE_RATE = 1e-6  # Extremely low but non-zero
+    MAX_EXCHANGE_RATE = 1e6  # Extremely high but finite