pydeflate 2.1.3__py3-none-any.whl → 2.3.0__py3-none-any.whl

pydeflate/core/source.py

@@ -2,6 +2,7 @@ from dataclasses import dataclass, field
 
 import pandas as pd
 
+from pydeflate.exceptions import ConfigurationError, DataSourceError
 from pydeflate.sources.common import AvailableDeflators
 from pydeflate.sources.dac import read_dac
 from pydeflate.sources.imf import read_weo
@@ -10,6 +11,12 @@ from pydeflate.sources.world_bank import read_wb, read_wb_lcu_ppp, read_wb_usd_p
 
 @dataclass
 class Source:
+    """Base class for data sources implementing SourceProtocol.
+
+    This class handles loading data from external sources, caching,
+    and validation. It implements the SourceProtocol interface.
+    """
+
     name: str
     reader: callable
     update: bool = False
@@ -17,26 +24,100 @@ class Source:
     _idx = ["pydeflate_year", "pydeflate_entity_code", "pydeflate_iso3"]
 
     def __post_init__(self):
-        self.data = self.reader(self.update)
+        """Load and validate data after initialization."""
+        try:
+            self.data = self.reader(self.update)
+        except Exception as e:
+            raise DataSourceError(
+                f"Failed to load data: {e}",
+                source=self.name,
+            ) from e
+
         self.validate()
 
     def validate(self):
-        if self.data.empty:
-            raise ValueError(f"No data found for {self.name}")
+        """Validate that source data is properly formatted.
 
-        # check all columns start with pydeflate_
-        if not all(col.startswith("pydeflate_") for col in self.data.columns):
-            raise ValueError(f"Invalid data format for {self.name}")
+        Raises:
+            DataSourceError: If data is empty or improperly formatted
+            SchemaValidationError: If data doesn't match expected schema
+        """
+        if self.data.empty:
+            raise DataSourceError(f"No data found", source=self.name)
+
+        # Check all columns start with pydeflate_
+        invalid_cols = [
+            col for col in self.data.columns if not col.startswith("pydeflate_")
+        ]
+        if invalid_cols:
+            raise DataSourceError(
+                f"Invalid column names (must start with 'pydeflate_'): {invalid_cols}",
+                source=self.name,
+            )
+
+        # Validate schema if available and enabled
+        # Note: Schema validation is currently experimental
+        # Set environment variable PYDEFLATE_ENABLE_VALIDATION=1 to enable
+        import os
+
+        if os.environ.get("PYDEFLATE_ENABLE_VALIDATION") == "1":
+            try:
+                from pydeflate.schemas import validate_source_data
+
+                validate_source_data(self.data, self.name)
+            except ImportError:
+                # Pandera not available, skip schema validation
+                pass
+            except Exception as e:
+                # Schema validation failed, but don't break for now
+                # This allows us to roll out schema validation gradually
+                import logging
+
+                logger = logging.getLogger("pydeflate")
+                logger.debug(f"Schema validation skipped for {self.name}: {e}")
 
     def lcu_usd_exchange(self) -> pd.DataFrame:
+        """Return local currency to USD exchange rates.
+
+        Returns:
+            DataFrame with exchange rate data
+
+        Raises:
+            DataSourceError: If exchange rate data is missing
+        """
+        if "pydeflate_EXCHANGE" not in self.data.columns:
+            raise DataSourceError(
+                "Exchange rate data (pydeflate_EXCHANGE) not available",
+                source=self.name,
+            )
         return self.data.filter(self._idx + ["pydeflate_EXCHANGE"])
 
     def price_deflator(self, kind: AvailableDeflators = "NGDP_D") -> pd.DataFrame:
-
-        if f"pydeflate_{kind}" not in self.data.columns:
-            raise ValueError(f"No deflator data found for {kind} in {self.name} data.")
-
-        return self.data.filter(self._idx + [f"pydeflate_{kind}"])
+        """Return price deflator data for specified kind.
+
+        Args:
+            kind: Type of deflator (e.g., 'NGDP_D', 'CPI')
+
+        Returns:
+            DataFrame with deflator data
+
+        Raises:
+            ConfigurationError: If deflator kind not available for this source
+        """
+        column_name = f"pydeflate_{kind}"
+        if column_name not in self.data.columns:
+            available = [
+                col.replace("pydeflate_", "")
+                for col in self.data.columns
+                if col.startswith("pydeflate_") and col not in self._idx
+            ]
+            raise ConfigurationError(
+                f"Deflator '{kind}' not available for {self.name}. "
+                f"Available deflators: {', '.join(available)}",
+                parameter="kind",
+            )
+
+        return self.data.filter(self._idx + [column_name])
 
 
 class IMF(Source):

pydeflate/deflate/deflators.py

@@ -3,7 +3,7 @@ from functools import wraps
 import pandas as pd
 
 from pydeflate.core.api import BaseDeflate
-from pydeflate.core.source import DAC, WorldBank, IMF
+from pydeflate.core.source import DAC, IMF, WorldBank
 
 
 def _generate_docstring(source_name: str, price_kind: str) -> str:

pydeflate/deflate/get_deflators.py

@@ -0,0 +1,233 @@
+from functools import wraps
+
+import pandas as pd
+
+from pydeflate.core.api import BaseDeflate
+from pydeflate.core.source import DAC, IMF, WorldBank
+
+
+def _generate_get_deflator_docstring(source_name: str, price_kind: str) -> str:
+    """Generate docstring for each get deflator function."""
+    return (
+        f"Get deflator data from {source_name} ({price_kind}) without requiring user data.\n\n"
+        f"This function returns a DataFrame containing deflator values for the specified parameters.\n\n"
+        "Args:\n"
+        "    base_year (int): The base year for calculating deflation adjustments.\n"
+        "    source_currency (str, optional): The source currency code. Defaults to 'USA'.\n"
+        "    target_currency (str, optional): The target currency code. Defaults to 'USA'.\n"
+        "    countries (list[str] | None, optional): List of country codes to include. If None, returns all. Defaults to None.\n"
+        "    years (list[int] | range | None, optional): List or range of years to include. If None, returns all. Defaults to None.\n"
+        "    use_source_codes (bool, optional): Use source-specific entity codes. Defaults to False.\n"
+        "    to_current (bool, optional): Get deflators for constant-to-current conversion. Defaults to False.\n"
+        "    include_components (bool, optional): Include price_deflator, exchange_deflator, and exchange_rate columns. Defaults to False.\n"
+        "    update_deflators (bool, optional): Update the deflator data before retrieval. Defaults to False.\n\n"
+        "Returns:\n"
+        "    pd.DataFrame: DataFrame with columns:\n"
+        "        - iso_code (or entity_code if use_source_codes=True): Country/entity identifier\n"
+        "        - year: Year\n"
+        "        - deflator: The combined deflator value\n"
+        "        - price_deflator (if include_components=True): The price deflator component\n"
+        "        - exchange_deflator (if include_components=True): The exchange rate deflator component\n"
+        "        - exchange_rate (if include_components=True): The exchange rate\n"
+    )
+
+
+def _get_deflator(deflator_source_cls, price_kind):
+    """Decorator to create get_deflator wrappers with specific deflator source and price kind."""
+
+    def decorator(func):
+        @wraps(func)
+        def wrapper(
+            *,
+            base_year: int,
+            source_currency: str = "USA",
+            target_currency: str = "USA",
+            countries: list[str] | None = None,
+            years: list[int] | range | None = None,
+            use_source_codes: bool = False,
+            to_current: bool = False,
+            include_components: bool = False,
+            update_deflators: bool = False,
+        ):
+            # Validate input parameters
+            if not isinstance(base_year, int):
+                raise ValueError("The 'base_year' parameter must be an integer.")
+
+            # Initialize the deflator source
+            source = deflator_source_cls(update=update_deflators)
+
+            # Create a deflator object
+            deflator = BaseDeflate(
+                base_year=base_year,
+                deflator_source=source,
+                exchange_source=source,
+                source_currency=source_currency,
+                target_currency=target_currency,
+                price_kind=price_kind,
+                use_source_codes=use_source_codes,
+                to_current=to_current,
+            )
+
+            # Get the pydeflate data
+            data = deflator.pydeflate_data.copy()
+
+            # Determine the entity column based on use_source_codes
+            entity_col = "pydeflate_entity_code" if use_source_codes else "pydeflate_iso3"
+
+            # Filter by countries if specified
+            if countries is not None:
+                data = data[data[entity_col].isin(countries)]
+
+            # Filter by years if specified
+            if years is not None:
+                if isinstance(years, range):
+                    years = list(years)
+                data = data[data["pydeflate_year"].isin(years)]
+
+            # Select columns to return
+            columns_to_keep = [entity_col, "pydeflate_year", "pydeflate_deflator"]
+
+            if include_components:
+                # Add component columns
+                price_col = f"pydeflate_{price_kind}"
+                columns_to_keep.extend(
+                    [price_col, "pydeflate_EXCHANGE_D", "pydeflate_EXCHANGE"]
+                )
+
+            # Keep only the specified columns
+            result = data[columns_to_keep].copy()
+
+            # Rename columns to user-friendly names
+            rename_map = {
+                entity_col: "entity_code" if use_source_codes else "iso_code",
+                "pydeflate_year": "year",
+                "pydeflate_deflator": "deflator",
+            }
+
+            if include_components:
+                rename_map.update(
+                    {
+                        f"pydeflate_{price_kind}": "price_deflator",
+                        "pydeflate_EXCHANGE_D": "exchange_deflator",
+                        "pydeflate_EXCHANGE": "exchange_rate",
+                    }
+                )
+
+            result = result.rename(columns=rename_map)
+
+            # Reset index
+            result = result.reset_index(drop=True)
+
+            return result
+
+        wrapper.__doc__ = _generate_get_deflator_docstring(
+            deflator_source_cls.__name__, price_kind
+        )
+        return wrapper
+
+    return decorator
+
+
+@_get_deflator(DAC, "NGDP_D")
+def get_oecd_dac_deflators(
+    *,
+    base_year: int,
+    source_currency: str = "USA",
+    target_currency: str = "USA",
+    countries: list[str] | None = None,
+    years: list[int] | range | None = None,
+    use_source_codes: bool = False,
+    to_current: bool = False,
+    include_components: bool = False,
+    update_deflators: bool = False,
+) -> pd.DataFrame: ...
+
+
+@_get_deflator(WorldBank, "NGDP_D")
+def get_wb_gdp_deflators(
+    *,
+    base_year: int,
+    source_currency: str = "USA",
+    target_currency: str = "USA",
+    countries: list[str] | None = None,
+    years: list[int] | range | None = None,
+    use_source_codes: bool = False,
+    to_current: bool = False,
+    include_components: bool = False,
+    update_deflators: bool = False,
+) -> pd.DataFrame: ...
+
+
+@_get_deflator(WorldBank, "NGDP_DL")
+def get_wb_gdp_linked_deflators(
+    *,
+    base_year: int,
+    source_currency: str = "USA",
+    target_currency: str = "USA",
+    countries: list[str] | None = None,
+    years: list[int] | range | None = None,
+    use_source_codes: bool = False,
+    to_current: bool = False,
+    include_components: bool = False,
+    update_deflators: bool = False,
+) -> pd.DataFrame: ...
+
+
+@_get_deflator(WorldBank, "CPI")
+def get_wb_cpi_deflators(
+    *,
+    base_year: int,
+    source_currency: str = "USA",
+    target_currency: str = "USA",
+    countries: list[str] | None = None,
+    years: list[int] | range | None = None,
+    use_source_codes: bool = False,
+    to_current: bool = False,
+    include_components: bool = False,
+    update_deflators: bool = False,
+) -> pd.DataFrame: ...
+
+
+@_get_deflator(IMF, "NGDP_D")
+def get_imf_gdp_deflators(
+    *,
+    base_year: int,
+    source_currency: str = "USA",
+    target_currency: str = "USA",
+    countries: list[str] | None = None,
+    years: list[int] | range | None = None,
+    use_source_codes: bool = False,
+    to_current: bool = False,
+    include_components: bool = False,
+    update_deflators: bool = False,
+) -> pd.DataFrame: ...
+
+
+@_get_deflator(IMF, "PCPI")
+def get_imf_cpi_deflators(
+    *,
+    base_year: int,
+    source_currency: str = "USA",
+    target_currency: str = "USA",
+    countries: list[str] | None = None,
+    years: list[int] | range | None = None,
+    use_source_codes: bool = False,
+    to_current: bool = False,
+    include_components: bool = False,
+    update_deflators: bool = False,
+) -> pd.DataFrame: ...
+
+
+@_get_deflator(IMF, "PCPIE")
+def get_imf_cpi_e_deflators(
+    *,
+    base_year: int,
+    source_currency: str = "USA",
+    target_currency: str = "USA",
+    countries: list[str] | None = None,
+    years: list[int] | range | None = None,
+    use_source_codes: bool = False,
+    to_current: bool = False,
+    include_components: bool = False,
+    update_deflators: bool = False,
+) -> pd.DataFrame: ...

pydeflate/deflate/legacy_deflate.py

@@ -4,7 +4,7 @@ import pandas as pd
 from pandas.util._decorators import deprecate_kwarg
 
 from pydeflate.core.api import BaseDeflate
-from pydeflate.core.source import DAC, WorldBank, IMF
+from pydeflate.core.source import DAC, IMF, WorldBank
 
 
 @deprecate_kwarg(old_arg_name="method", new_arg_name="deflator_method")

pydeflate/exceptions.py

@@ -0,0 +1,166 @@
+"""Custom exception hierarchy for pydeflate.
+
+This module defines specific exception types that allow users to handle
+different failure modes appropriately (e.g., retry on network errors,
+fail fast on validation errors).
+"""
+
+from __future__ import annotations
+
+
+class PydeflateError(Exception):
+    """Base exception for all pydeflate errors.
+
+    All exceptions raised by pydeflate inherit from this class,
+    making it easy to catch all pydeflate-specific errors.
+    """
+
+    pass
+
+
+class DataSourceError(PydeflateError):
+    """Raised when there's an issue with a data source.
+
+    This is a base class for all data source related errors.
+    """
+
+    def __init__(self, message: str, source: str | None = None):
+        """Initialize DataSourceError.
+
+        Args:
+            message: Description of the error
+            source: Name of the data source (e.g., 'IMF', 'World Bank')
+        """
+        self.source = source
+        super().__init__(f"[{source}] {message}" if source else message)
+
+
+class NetworkError(DataSourceError):
+    """Raised when network operations fail.
+
+    This typically indicates a transient error that might succeed on retry.
+    """
+
+    pass
+
+
+class SchemaValidationError(DataSourceError):
+    """Raised when data doesn't match expected schema.
+
+    This indicates a problem with the data structure, either from:
+    - External API changes
+    - Corrupted downloaded data
+    - User input with wrong columns/types
+    """
+
+    def __init__(
+        self,
+        message: str,
+        source: str | None = None,
+        expected_schema: dict | None = None,
+        actual_schema: dict | None = None,
+    ):
+        """Initialize SchemaValidationError.
+
+        Args:
+            message: Description of validation failure
+            source: Name of the data source
+            expected_schema: Expected column types/names
+            actual_schema: Actual column types/names found
+        """
+        self.expected_schema = expected_schema
+        self.actual_schema = actual_schema
+        super().__init__(message, source)
+
+
+class CacheError(PydeflateError):
+    """Raised when cache operations fail.
+
+    Examples:
+    - Unable to write to cache directory
+    - Corrupted cache files
+    - Lock file acquisition timeout
+    """
+
+    def __init__(self, message: str, cache_path: str | None = None):
+        """Initialize CacheError.
+
+        Args:
+            message: Description of cache error
+            cache_path: Path to the cache file/directory involved
+        """
+        self.cache_path = cache_path
+        super().__init__(
+            f"Cache error at {cache_path}: {message}" if cache_path else message
+        )
+
+
+class ConfigurationError(PydeflateError):
+    """Raised when configuration parameters are invalid.
+
+    Examples:
+    - Invalid currency code
+    - Base year out of range
+    - Missing required columns in user data
+    - Conflicting parameter combinations
+    """
+
+    def __init__(self, message: str, parameter: str | None = None):
+        """Initialize ConfigurationError.
+
+        Args:
+            message: Description of configuration issue
+            parameter: Name of the problematic parameter
+        """
+        self.parameter = parameter
+        super().__init__(
+            f"Invalid configuration for '{parameter}': {message}"
+            if parameter
+            else message
+        )
+
+
+class MissingDataError(PydeflateError):
+    """Raised when required deflator or exchange data is unavailable.
+
+    This occurs when:
+    - Requested country/year combination has no data in the source
+    - Data gaps in historical records
+    - Future years beyond available estimates
+    """
+
+    def __init__(
+        self,
+        message: str,
+        missing_entities: dict[str, list[int]] | None = None,
+    ):
+        """Initialize MissingDataError.
+
+        Args:
+            message: Description of missing data
+            missing_entities: Dict mapping entity codes to missing years
+        """
+        self.missing_entities = missing_entities
+        super().__init__(message)
+
+
+class PluginError(PydeflateError):
+    """Raised when plugin registration or loading fails.
+
+    Examples:
+    - Plugin doesn't implement required protocol
+    - Plugin name conflicts with existing source
+    - Plugin initialization fails
+    """
+
+    def __init__(self, message: str, plugin_name: str | None = None):
+        """Initialize PluginError.
+
+        Args:
+            message: Description of plugin error
+            plugin_name: Name of the plugin that failed
+        """
+        self.plugin_name = plugin_name
+        super().__init__(
+            f"Plugin '{plugin_name}' error: {message}" if plugin_name else message
+        )

pydeflate/exchange/exchangers.py

@@ -3,7 +3,7 @@ from functools import wraps
 import pandas as pd
 
 from pydeflate.core.api import BaseExchange
-from pydeflate.core.source import DAC, WorldBank, IMF, WorldBankPPP
+from pydeflate.core.source import DAC, IMF, WorldBank, WorldBankPPP
 
 
 def _generate_docstring(source_name: str) -> str: