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

pydeflate/exchange/get_rates.py

@@ -0,0 +1,207 @@
+from functools import wraps
+
+import pandas as pd
+
+from pydeflate.core.api import BaseExchange
+from pydeflate.core.source import DAC, IMF, WorldBank, WorldBankPPP
+
+
+def _generate_get_rates_docstring(source_name: str) -> str:
+    """Generate docstring for each get exchange rates function."""
+    return (
+        f"Get exchange rate data from {source_name} without requiring user data.\n\n"
+        f"This function returns a DataFrame containing exchange rates for the specified parameters.\n\n"
+        "Args:\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"
+        "    update_rates (bool, optional): Update the exchange rate 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"
+        "        - exchange_rate: Exchange rate from source to target currency\n"
+    )
+
+
+def _get_exchange_rates(exchange_source_cls, **fixed_params):
+    """Decorator to create get_exchange_rates wrappers with specific source."""
+
+    def decorator(func):
+        @wraps(func)
+        def wrapper(
+            *,
+            source_currency: str = "USA",
+            target_currency: str = "USA",
+            countries: list[str] | None = None,
+            years: list[int] | range | None = None,
+            use_source_codes: bool = False,
+            update_rates: bool = False,
+        ):
+            # Apply fixed parameters - no validation needed since these are internally set
+            if "target_currency" in fixed_params:
+                target_currency = fixed_params["target_currency"]
+
+            # Initialize the exchange source
+            if exchange_source_cls.__name__ == "WorldBankPPP":
+                source = exchange_source_cls(
+                    update=update_rates,
+                    from_lcu=False if source_currency == "USA" else True,
+                )
+                source_currency = "LCU" if source_currency == "USA" else source_currency
+            else:
+                source = exchange_source_cls(update=update_rates)
+
+            # Create an exchange object
+            exchange = BaseExchange(
+                exchange_source=source,
+                source_currency=source_currency,
+                target_currency=target_currency,
+                use_source_codes=use_source_codes,
+            )
+
+            # Get the exchange rate data
+            data = exchange.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 and rename columns
+            result = data[[entity_col, "pydeflate_year", "pydeflate_EXCHANGE"]].copy()
+            result = result.rename(
+                columns={
+                    entity_col: "entity_code" if use_source_codes else "iso_code",
+                    "pydeflate_year": "year",
+                    "pydeflate_EXCHANGE": "exchange_rate",
+                }
+            )
+
+            # Reset index
+            result = result.reset_index(drop=True)
+
+            return result
+
+        wrapper.__doc__ = _generate_get_rates_docstring(exchange_source_cls.__name__)
+        return wrapper
+
+    return decorator
+
+
+@_get_exchange_rates(DAC)
+def get_oecd_dac_exchange_rates(
+    *,
+    source_currency: str = "USA",
+    target_currency: str = "USA",
+    countries: list[str] | None = None,
+    years: list[int] | range | None = None,
+    use_source_codes: bool = False,
+    update_rates: bool = False,
+) -> pd.DataFrame: ...
+
+
+@_get_exchange_rates(WorldBank)
+def get_wb_exchange_rates(
+    *,
+    source_currency: str = "USA",
+    target_currency: str = "USA",
+    countries: list[str] | None = None,
+    years: list[int] | range | None = None,
+    use_source_codes: bool = False,
+    update_rates: bool = False,
+) -> pd.DataFrame: ...
+
+
+def get_wb_ppp_rates(
+    *,
+    source_currency: str = "USA",
+    countries: list[str] | None = None,
+    years: list[int] | range | None = None,
+    use_source_codes: bool = False,
+    update_rates: bool = False,
+) -> pd.DataFrame:
+    """Get PPP exchange rate data from WorldBankPPP without requiring user data.
+
+    This function returns a DataFrame containing PPP exchange rates for the specified parameters.
+
+    Args:
+        source_currency (str, optional): The source currency code. Defaults to 'USA'.
+        countries (list[str] | None, optional): List of country codes to include. If None, returns all. Defaults to None.
+        years (list[int] | range | None, optional): List or range of years to include. If None, returns all. Defaults to None.
+        use_source_codes (bool, optional): Use source-specific entity codes. Defaults to False.
+        update_rates (bool, optional): Update the exchange rate data before retrieval. Defaults to False.
+
+    Returns:
+        pd.DataFrame: DataFrame with columns:
+            - iso_code (or entity_code if use_source_codes=True): Country/entity identifier
+            - year: Year
+            - exchange_rate: PPP exchange rate
+    """
+    # Initialize the exchange source
+    source = WorldBankPPP(
+        update=update_rates,
+        from_lcu=False if source_currency == "USA" else True,
+    )
+    source_currency_internal = "LCU" if source_currency == "USA" else source_currency
+
+    # Create an exchange object with PPP as target
+    exchange = BaseExchange(
+        exchange_source=source,
+        source_currency=source_currency_internal,
+        target_currency="PPP",
+        use_source_codes=use_source_codes,
+    )
+
+    # Get the exchange rate data
+    data = exchange.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 and rename columns
+    result = data[[entity_col, "pydeflate_year", "pydeflate_EXCHANGE"]].copy()
+    result = result.rename(
+        columns={
+            entity_col: "entity_code" if use_source_codes else "iso_code",
+            "pydeflate_year": "year",
+            "pydeflate_EXCHANGE": "exchange_rate",
+        }
+    )
+
+    # Reset index
+    result = result.reset_index(drop=True)
+
+    return result
+
+
+@_get_exchange_rates(IMF)
+def get_imf_exchange_rates(
+    *,
+    source_currency: str = "USA",
+    target_currency: str = "USA",
+    countries: list[str] | None = None,
+    years: list[int] | range | None = None,
+    use_source_codes: bool = False,
+    update_rates: bool = False,
+) -> pd.DataFrame: ...

pydeflate/plugins.py

@@ -0,0 +1,289 @@
+"""Plugin system for custom data sources.
+
+This module provides a registry-based plugin architecture that allows
+users to register custom data sources without modifying pydeflate's code.
+
+Example:
+    >>> from pydeflate.plugins import register_source
+    >>> from pydeflate.protocols import SourceProtocol
+    >>>
+    >>> @register_source("my_custom_source")
+    >>> class MyCustomSource:
+    ...     def __init__(self, update: bool = False):
+    ...         self.name = "my_custom_source"
+    ...         self.data = load_my_data(update)
+    ...         self._idx = ["pydeflate_year", "pydeflate_entity_code", "pydeflate_iso3"]
+    ...
+    ...     def lcu_usd_exchange(self): ...
+    ...     def price_deflator(self, kind): ...
+    ...     def validate(self): ...
+    >>>
+    >>> # Now use it:
+    >>> result = deflate_with_source("my_custom_source", data=df, ...)
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, TypeVar
+
+from pydeflate.exceptions import PluginError
+from pydeflate.protocols import SourceProtocol
+
+# Type variable for source classes
+SourceType = TypeVar("SourceType", bound=type)
+
+
+class SourceRegistry:
+    """Registry for data source implementations.
+
+    This class maintains a mapping of source names to their implementation
+    classes. It provides methods to register, retrieve, and list sources.
+    """
+
+    def __init__(self):
+        """Initialize an empty registry."""
+        self._sources: dict[str, type] = {}
+        self._factories: dict[str, Callable[..., SourceProtocol]] = {}
+
+    def register(
+        self,
+        name: str,
+        source_class: type | None = None,
+        factory: Callable[..., SourceProtocol] | None = None,
+        *,
+        override: bool = False,
+    ) -> None:
+        """Register a data source.
+
+        Args:
+            name: Unique name for this source (e.g., 'IMF', 'WorldBank')
+            source_class: Class that implements SourceProtocol
+            factory: Factory function that returns a SourceProtocol instance
+            override: If True, allow replacing existing sources
+
+        Raises:
+            PluginError: If name already registered and override=False
+            PluginError: If neither source_class nor factory is provided
+            PluginError: If source doesn't implement SourceProtocol
+        """
+        # Validation
+        if source_class is None and factory is None:
+            raise PluginError(
+                "Must provide either source_class or factory",
+                plugin_name=name,
+            )
+
+        if not override and name in self._sources:
+            raise PluginError(
+                f"Source '{name}' already registered. Use override=True to replace.",
+                plugin_name=name,
+            )
+
+        # Check protocol conformance if source_class provided
+        if source_class is not None:
+            if not self._check_protocol_conformance(source_class):
+                raise PluginError(
+                    f"Source class must implement SourceProtocol",
+                    plugin_name=name,
+                )
+            self._sources[name] = source_class
+
+        if factory is not None:
+            self._factories[name] = factory
+
+    def _check_protocol_conformance(self, source_class: type) -> bool:
+        """Check if a class implements SourceProtocol.
+
+        Args:
+            source_class: Class to check
+
+        Returns:
+            True if class implements the protocol
+        """
+        required_methods = ["lcu_usd_exchange", "price_deflator", "validate"]
+        required_attrs = ["name", "data", "_idx"]
+
+        for method in required_methods:
+            if not hasattr(source_class, method):
+                return False
+            if not callable(getattr(source_class, method)):
+                return False
+
+        # Check that class can be instantiated and has required attributes
+        # Note: We can't fully check this without instantiation,
+        # so we just check the class has these as class attributes or in __init__
+        # This is a best-effort check
+        return True
+
+    def get(self, name: str, **kwargs) -> SourceProtocol:
+        """Get a source instance by name.
+
+        Args:
+            name: Name of the registered source
+            **kwargs: Keyword arguments to pass to source constructor
+
+        Returns:
+            Instance of the source
+
+        Raises:
+            PluginError: If source not found
+        """
+        # Try factory first
+        if name in self._factories:
+            try:
+                return self._factories[name](**kwargs)
+            except Exception as e:
+                raise PluginError(
+                    f"Factory function failed: {e}",
+                    plugin_name=name,
+                ) from e
+
+        # Try class
+        if name in self._sources:
+            try:
+                return self._sources[name](**kwargs)
+            except Exception as e:
+                raise PluginError(
+                    f"Source instantiation failed: {e}",
+                    plugin_name=name,
+                ) from e
+
+        raise PluginError(
+            f"Source '{name}' not found. Available sources: {self.list_sources()}",
+            plugin_name=name,
+        )
+
+    def list_sources(self) -> list[str]:
+        """List all registered source names.
+
+        Returns:
+            List of source names
+        """
+        all_names = set(self._sources.keys()) | set(self._factories.keys())
+        return sorted(all_names)
+
+    def is_registered(self, name: str) -> bool:
+        """Check if a source is registered.
+
+        Args:
+            name: Source name to check
+
+        Returns:
+            True if registered
+        """
+        return name in self._sources or name in self._factories
+
+    def unregister(self, name: str) -> None:
+        """Remove a source from the registry.
+
+        Args:
+            name: Source name to remove
+
+        Raises:
+            PluginError: If source not found
+        """
+        if not self.is_registered(name):
+            raise PluginError(
+                f"Cannot unregister '{name}': not found",
+                plugin_name=name,
+            )
+
+        self._sources.pop(name, None)
+        self._factories.pop(name, None)
+
+
+# Global registry instance
+_global_registry = SourceRegistry()
+
+
+def register_source(
+    name: str,
+    *,
+    override: bool = False,
+) -> Callable[[SourceType], SourceType]:
+    """Decorator to register a source class.
+
+    Example:
+        >>> @register_source("my_source")
+        ... class MySource:
+        ...     def __init__(self, update: bool = False):
+        ...         self.name = "my_source"
+        ...         ...
+        ...
+        ...     def lcu_usd_exchange(self): ...
+        ...     def price_deflator(self, kind): ...
+
+    Args:
+        name: Unique name for this source
+        override: Allow replacing existing sources
+
+    Returns:
+        Decorator function
+    """
+
+    def decorator(cls: SourceType) -> SourceType:
+        _global_registry.register(name, source_class=cls, override=override)
+        return cls
+
+    return decorator
+
+
+def get_source(name: str, **kwargs) -> SourceProtocol:
+    """Get a registered source instance.
+
+    Args:
+        name: Name of the source
+        **kwargs: Arguments to pass to source constructor
+
+    Returns:
+        Source instance
+
+    Raises:
+        PluginError: If source not found or instantiation fails
+    """
+    return _global_registry.get(name, **kwargs)
+
+
+def list_sources() -> list[str]:
+    """List all available sources.
+
+    Returns:
+        Sorted list of source names
+    """
+    return _global_registry.list_sources()
+
+
+def is_source_registered(name: str) -> bool:
+    """Check if a source is registered.
+
+    Args:
+        name: Source name
+
+    Returns:
+        True if registered
+    """
+    return _global_registry.is_registered(name)
+
+
+# Pre-register built-in sources
+def _register_builtin_sources():
+    """Register pydeflate's built-in sources."""
+    from pydeflate.core.source import DAC, IMF, WorldBank, WorldBankPPP
+
+    _global_registry.register("IMF", source_class=IMF, override=True)
+    _global_registry.register("World Bank", source_class=WorldBank, override=True)
+    _global_registry.register(
+        "World Bank PPP", source_class=WorldBankPPP, override=True
+    )
+    _global_registry.register("DAC", source_class=DAC, override=True)
+
+    # Aliases for convenience
+    _global_registry.register("imf", source_class=IMF, override=True)
+    _global_registry.register("wb", source_class=WorldBank, override=True)
+    _global_registry.register("worldbank", source_class=WorldBank, override=True)
+    _global_registry.register("dac", source_class=DAC, override=True)
+    _global_registry.register("oecd", source_class=DAC, override=True)
+
+
+# Register built-in sources when module is imported
+_register_builtin_sources()

pydeflate/protocols.py

@@ -0,0 +1,168 @@
+"""Protocol definitions for type safety and extensibility.
+
+This module defines the core protocols (interfaces) that pydeflate components
+must implement. Using protocols enables:
+- Type checking without inheritance
+- Duck typing with static verification
+- Clear contracts for extensibility
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+import pandas as pd
+
+from pydeflate.sources.common import AvailableDeflators
+
+
+@runtime_checkable
+class SourceProtocol(Protocol):
+    """Protocol for data sources (IMF, World Bank, DAC, etc.).
+
+    All data sources must implement these methods to be compatible
+    with pydeflate's core deflation and exchange logic.
+    """
+
+    name: str
+    """Human-readable name of the data source (e.g., 'IMF', 'World Bank')"""
+
+    data: pd.DataFrame
+    """The raw data loaded from this source"""
+
+    _idx: list[str]
+    """Standard index columns: ['pydeflate_year', 'pydeflate_entity_code', 'pydeflate_iso3']"""
+
+    def lcu_usd_exchange(self) -> pd.DataFrame:
+        """Return local currency to USD exchange rates.
+
+        Returns:
+            DataFrame with columns: pydeflate_year, pydeflate_entity_code,
+            pydeflate_iso3, pydeflate_EXCHANGE
+        """
+        ...
+
+    def price_deflator(self, kind: AvailableDeflators = "NGDP_D") -> pd.DataFrame:
+        """Return price deflator data for the specified type.
+
+        Args:
+            kind: Type of deflator (e.g., 'NGDP_D', 'CPI', 'PCPI')
+
+        Returns:
+            DataFrame with columns: pydeflate_year, pydeflate_entity_code,
+            pydeflate_iso3, pydeflate_{kind}
+
+        Raises:
+            ValueError: If the requested deflator kind is not available
+        """
+        ...
+
+    def validate(self) -> None:
+        """Validate that the source data is properly formatted.
+
+        Raises:
+            ValueError: If data is empty or improperly formatted
+            SchemaValidationError: If data doesn't match expected schema
+        """
+        ...
+
+
+@runtime_checkable
+class DeflatorProtocol(Protocol):
+    """Protocol for deflator objects (price or exchange deflators)."""
+
+    source: SourceProtocol
+    """The data source providing deflator data"""
+
+    deflator_type: str
+    """Type of deflator: 'price' or 'exchange'"""
+
+    base_year: int
+    """The base year for rebasing deflator values (value = 100 at base year)"""
+
+    deflator_data: pd.DataFrame
+    """The deflator data, rebased to base_year"""
+
+    def rebase_deflator(self) -> None:
+        """Rebase deflator values so that base_year has value 100."""
+        ...
+
+
+@runtime_checkable
+class ExchangeProtocol(Protocol):
+    """Protocol for exchange rate objects."""
+
+    source: SourceProtocol
+    """The data source providing exchange rate data"""
+
+    source_currency: str
+    """Source currency code (ISO3 country code or 'LCU')"""
+
+    target_currency: str
+    """Target currency code (ISO3 country code)"""
+
+    exchange_data: pd.DataFrame
+    """Exchange rate data for converting source_currency to target_currency"""
+
+    def exchange_rate(self, from_currency: str, to_currency: str) -> pd.DataFrame:
+        """Calculate exchange rates between two currencies.
+
+        Args:
+            from_currency: Source currency code
+            to_currency: Target currency code
+
+        Returns:
+            DataFrame with exchange rates and deflators
+        """
+        ...
+
+    def deflator(self) -> pd.DataFrame:
+        """Get exchange rate deflator data.
+
+        Returns:
+            DataFrame with columns: pydeflate_year, pydeflate_entity_code,
+            pydeflate_iso3, pydeflate_EXCHANGE_D
+        """
+        ...
+
+
+@runtime_checkable
+class CacheManagerProtocol(Protocol):
+    """Protocol for cache management."""
+
+    base_dir: pd.DataFrame
+    """Base directory for cached data"""
+
+    def ensure(self, entry, *, refresh: bool = False):
+        """Ensure a cache entry exists, downloading if needed.
+
+        Args:
+            entry: CacheEntry describing the dataset
+            refresh: If True, force re-download
+
+        Returns:
+            Path to the cached file
+        """
+        ...
+
+    def clear(self, key: str | None = None) -> None:
+        """Clear cache entries.
+
+        Args:
+            key: If provided, clear only this entry. If None, clear all.
+        """
+        ...
+
+
+# Type aliases for common DataFrame schemas
+ExchangeDataFrame = pd.DataFrame
+"""DataFrame containing exchange rate data"""
+
+DeflatorDataFrame = pd.DataFrame
+"""DataFrame containing deflator data"""
+
+SourceDataFrame = pd.DataFrame
+"""DataFrame containing raw source data"""
+
+UserDataFrame = pd.DataFrame
+"""DataFrame provided by users for deflation/exchange"""