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

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"""

pydeflate/pydeflate_config.py

@@ -1,14 +1,79 @@
+from __future__ import annotations
+
 import logging
+import os
+from dataclasses import dataclass
 from pathlib import Path
 
 
-class PYDEFLATE_PATHS:
-    """Class to store the paths to the data and output folders."""
+from platformdirs import user_cache_dir
+
+
+DATA_DIR_ENV = "PYDEFLATE_DATA_DIR"
+
+_PACKAGE_ROOT = Path(__file__).resolve().parent.parent
+_SETTINGS_DIR = _PACKAGE_ROOT / "pydeflate" / "settings"
+_TEST_DATA_DIR = _PACKAGE_ROOT / "tests" / "test_files"
+
+_DATA_DIR_OVERRIDE: Path | None = None
+
+
+def _ensure_dir(path: Path) -> Path:
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def _default_data_dir() -> Path:
+    env_value = os.environ.get(DATA_DIR_ENV)
+    if env_value:
+        return _ensure_dir(Path(env_value).expanduser().resolve())
+    return _ensure_dir(Path(user_cache_dir("pydeflate", "pydeflate")))
+
+
+def get_data_dir() -> Path:
+    """Return the directory where pydeflate caches data files."""
+
+    if _DATA_DIR_OVERRIDE is not None:
+        return _ensure_dir(_DATA_DIR_OVERRIDE)
+    return _default_data_dir()
+
 
-    package = Path(__file__).resolve().parent.parent
-    data = package / "pydeflate" / ".pydeflate_data"
-    settings = package / "pydeflate" / "settings"
-    test_data = package / "tests" / "test_files"
+def set_data_dir(path: str | Path) -> Path:
+    """Override the pydeflate data directory for the current process."""
+
+    global _DATA_DIR_OVERRIDE
+    resolved = _ensure_dir(Path(path).expanduser().resolve())
+    _DATA_DIR_OVERRIDE = resolved
+    return resolved
+
+
+def reset_data_dir() -> None:
+    """Reset any process-level overrides and fall back to defaults."""
+
+    global _DATA_DIR_OVERRIDE
+    _DATA_DIR_OVERRIDE = None
+
+
+@dataclass(frozen=True)
+class _Paths:
+    package: Path
+    settings: Path
+    test_data: Path
+
+    @property
+    def data(self) -> Path:
+        return get_data_dir()
+
+    @data.setter  # type: ignore[override]
+    def data(self, value: Path | str) -> None:  # pragma: no cover - simple proxy
+        set_data_dir(value)
+
+
+PYDEFLATE_PATHS = _Paths(
+    package=_PACKAGE_ROOT,
+    settings=_SETTINGS_DIR,
+    test_data=_TEST_DATA_DIR,
+)
 
 
 def setup_logger(name) -> logging.Logger:
@@ -41,3 +106,9 @@ def setup_logger(name) -> logging.Logger:
 
 
 logger = setup_logger("pydeflate")
+
+
+def set_pydeflate_path(path: str | Path) -> Path:
+    """Set the path to the data folder (public API)."""
+
+    return set_data_dir(path)

pydeflate/schemas.py

@@ -0,0 +1,297 @@
+"""Pandera schemas for data validation.
+
+This module defines validation schemas for all DataFrame structures used
+in pydeflate. This ensures data integrity from external sources and
+catches API changes early.
+"""
+
+from __future__ import annotations
+
+import pandas as pd
+
+try:
+    # New import (pandera >= 0.20)
+    import pandera.pandas as pa
+    from pandera.pandas import Check, Column, DataFrameSchema
+except ImportError:
+    # Fallback to old import for older pandera versions
+    import pandera as pa
+    from pandera import Check, Column, DataFrameSchema
+
+# Column definitions for reuse
+YEAR_COLUMN = Column(
+    int,
+    checks=[
+        Check.ge(1960),  # No data before 1960
+        Check.le(2100),  # No projections beyond 2100
+    ],
+    nullable=False,
+    description="Year as integer",
+)
+
+ENTITY_CODE_COLUMN = Column(
+    str,
+    checks=[Check(lambda s: s.str.len() <= 10)],
+    nullable=False,
+    description="Entity code from source (varies by source)",
+)
+
+ISO3_COLUMN = Column(
+    str,
+    checks=[
+        Check(lambda s: (s.str.len() == 3) | s.isna()),
+    ],
+    nullable=True,
+    description="ISO3 country code",
+)
+
+EXCHANGE_RATE_COLUMN = Column(
+    float,
+    checks=[
+        Check.gt(0),  # Exchange rates must be positive
+    ],
+    nullable=True,
+    description="Exchange rate (LCU per USD)",
+)
+
+DEFLATOR_COLUMN = Column(
+    float,
+    checks=[
+        Check.gt(0),  # Deflators must be positive
+    ],
+    nullable=True,
+    description="Price deflator index",
+)
+
+
+class SourceDataSchema(pa.DataFrameModel):
+    """Base schema for all data sources.
+
+    All sources must have these minimum columns after processing.
+    """
+
+    pydeflate_year: int = pa.Field(ge=1960, le=2100)
+    pydeflate_entity_code: str = pa.Field(str_length={"max_value": 10})
+    pydeflate_iso3: str | None = pa.Field(nullable=True)
+
+    class Config:
+        """Schema configuration."""
+
+        strict = False  # Allow additional columns
+        coerce = True  # Attempt type coercion
+
+
+class ExchangeDataSchema(SourceDataSchema):
+    """Schema for exchange rate data."""
+
+    pydeflate_EXCHANGE = EXCHANGE_RATE_COLUMN
+    pydeflate_EXCHANGE_D = Column(
+        float,
+        checks=[Check.gt(0)],
+        nullable=True,
+        description="Exchange rate deflator (rebased)",
+    )
+
+    class Config:
+        """Schema configuration."""
+
+        strict = False
+        coerce = True
+
+
+class IMFDataSchema(SourceDataSchema):
+    """Schema for IMF WEO data.
+
+    IMF provides GDP deflators, CPI, and exchange rates.
+    """
+
+    pydeflate_NGDP_D = Column(
+        float,
+        checks=[Check.gt(0)],
+        nullable=True,
+        description="GDP deflator",
+    )
+    pydeflate_PCPI = Column(
+        float,
+        checks=[Check.gt(0)],
+        nullable=True,
+        description="CPI (period average)",
+    )
+    pydeflate_PCPIE = Column(
+        float,
+        checks=[Check.gt(0)],
+        nullable=True,
+        description="CPI (end of period)",
+    )
+    pydeflate_EXCHANGE = EXCHANGE_RATE_COLUMN
+
+    class Config:
+        """Schema configuration."""
+
+        strict = False
+        coerce = True
+
+
+class WorldBankDataSchema(SourceDataSchema):
+    """Schema for World Bank data."""
+
+    pydeflate_NGDP_D = Column(
+        float,
+        checks=[Check.gt(0)],
+        nullable=True,
+        description="GDP deflator",
+    )
+    pydeflate_NGDP_DL = Column(
+        float,
+        checks=[Check.gt(0)],
+        nullable=True,
+        description="GDP deflator (linked)",
+    )
+    pydeflate_CPI = Column(
+        float,
+        checks=[Check.gt(0)],
+        nullable=True,
+        description="Consumer Price Index",
+    )
+    pydeflate_EXCHANGE = EXCHANGE_RATE_COLUMN
+
+    class Config:
+        """Schema configuration."""
+
+        strict = False
+        coerce = True
+
+
+class DACDataSchema(SourceDataSchema):
+    """Schema for OECD DAC data."""
+
+    pydeflate_DAC_DEFLATOR = Column(
+        float,
+        checks=[Check.gt(0)],
+        nullable=True,
+        description="DAC deflator",
+    )
+    pydeflate_NGDP_D = Column(
+        float,
+        checks=[Check.gt(0)],
+        nullable=True,
+        description="GDP deflator (computed)",
+    )
+    pydeflate_EXCHANGE = EXCHANGE_RATE_COLUMN
+
+    class Config:
+        """Schema configuration."""
+
+        strict = False
+        coerce = True
+
+
+class UserInputSchema:
+    """Validation for user-provided DataFrames.
+
+    This is not a Pandera schema but provides methods to validate
+    user input with custom column names.
+    """
+
+    @staticmethod
+    def validate(
+        df,
+        id_column: str,
+        year_column: str,
+        value_column: str,
+    ) -> None:
+        """Validate user DataFrame has required columns and types.
+
+        Args:
+            df: User's DataFrame
+            id_column: Name of column with entity identifiers
+            year_column: Name of column with year data
+            value_column: Name of column with numeric values
+
+        Raises:
+            ConfigurationError: If required columns are missing
+            SchemaValidationError: If column types are invalid
+        """
+        from pydeflate.exceptions import ConfigurationError, SchemaValidationError
+
+        # Check required columns exist
+        missing_cols = []
+        for col_name, col in [
+            ("id_column", id_column),
+            ("year_column", year_column),
+            ("value_column", value_column),
+        ]:
+            if col not in df.columns:
+                missing_cols.append(f"{col_name}='{col}'")
+
+        if missing_cols:
+            raise ConfigurationError(
+                f"Required columns missing from DataFrame: {', '.join(missing_cols)}"
+            )
+
+        # Validate value column is numeric
+        if not pd.api.types.is_numeric_dtype(df[value_column]):
+            raise SchemaValidationError(
+                f"Column '{value_column}' must be numeric, got {df[value_column].dtype}"
+            )
+
+        # Validate year column can be converted to datetime
+        try:
+            pd.to_datetime(df[year_column], errors="coerce")
+        except Exception as e:
+            raise SchemaValidationError(
+                f"Column '{year_column}' cannot be interpreted as dates: {e}"
+            )
+
+
+# Registry of schemas by source name
+SCHEMA_REGISTRY: dict[str, type[DataFrameSchema]] = {
+    "IMF": IMFDataSchema,
+    "World Bank": WorldBankDataSchema,
+    "DAC": DACDataSchema,
+}
+
+
+def get_schema_for_source(source_name: str) -> type[DataFrameSchema] | None:
+    """Get the appropriate schema for a data source.
+
+    Args:
+        source_name: Name of the source (e.g., 'IMF', 'World Bank')
+
+    Returns:
+        Schema class for the source, or None if not found
+    """
+    return SCHEMA_REGISTRY.get(source_name)
+
+
+def validate_source_data(df, source_name: str) -> None:
+    """Validate that source data matches expected schema.
+
+    Args:
+        df: DataFrame to validate
+        source_name: Name of the source
+
+    Raises:
+        SchemaValidationError: If data doesn't match schema
+    """
+    from pydeflate.exceptions import SchemaValidationError
+
+    schema_class = get_schema_for_source(source_name)
+    if schema_class is None:
+        # No schema defined for this source, skip validation
+        return
+
+    try:
+        # Instantiate the schema and validate
+        schema = schema_class()
+        schema.validate(df, lazy=True)
+    except pa.errors.SchemaErrors as e:
+        # Collect all validation errors
+        error_messages = []
+        for error in e.failure_cases.itertuples():
+            error_messages.append(f"  - {error.check}: {error.failure_case}")
+
+        raise SchemaValidationError(
+            f"Data validation failed for {source_name}:\n" + "\n".join(error_messages),
+            source=source_name,
+        ) from e