pydeflate 2.2.0__tar.gz → 2.3.0__tar.gz

{pydeflate-2.2.0 → pydeflate-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydeflate
-Version: 2.2.0
+Version: 2.3.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>
@@ -28,6 +28,7 @@ Description-Content-Type: text/markdown
 [![pypi](https://img.shields.io/pypi/v/pydeflate.svg)](https://pypi.python.org/pypi/pydeflate)
 [![black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![Downloads](https://pepy.tech/badge/pydeflate/month)](https://pepy.tech/project/pydeflate)
+[![Documentation](https://img.shields.io/badge/docs-mkdocs-blue)](https://jm-rivera.github.io/pydeflate/)
 
 **pydeflate** is a Python package to:
 - Convert current price data to constant prices.
@@ -36,6 +37,8 @@ Description-Content-Type: text/markdown
 
 When converting to or from constant prices, it takes into account changes in prices and exchange rates over time. This allows for accurate comparisons across years, countries, and currencies.
 
+📚 **[Read the full documentation →](https://jm-rivera.github.io/pydeflate/)**
+
 ## Important Note
 
 **pydeflate v2 has recently been released. It includes api changes which break backwards-compatibility**. While a version of the `deflate` function is still available, it is now deprecated and will be removed in future versions. Please use the new deflator functions for improved simplicity, clarity and performance.
@@ -58,6 +61,11 @@ When converting to or from constant prices, it takes into account changes in pri
 - [Currency Conversion](#currency-conversion)
   - [Example](#example-currency-conversion)
 
+- [Getting Deflators and Exchange Rates Directly](#getting-deflators-and-exchange-rates-directly)
+  - [Getting Deflators](#getting-deflators)
+  - [Getting Exchange Rates](#getting-exchange-rates)
+  - [Common Use Cases](#common-use-cases)
+
 - [Example: Using Source-Specific Codes](#example-using-source-specific-codes)
 
 - [Data Sources and Method Options](#data-sources-and-method-options)
@@ -182,6 +190,111 @@ df_can = oecd_dac_exchange(
 )
 ```
 
+## Getting Deflators and Exchange Rates Directly
+
+**New in v2.3.0**: You can now retrieve deflator and exchange rate data directly as DataFrames, without needing to provide your own data. This is useful for inspecting deflators, analyzing trends, or pre-computing values for later use.
+
+### Getting Deflators
+
+```python
+from pydeflate import get_imf_gdp_deflators, set_pydeflate_path
+
+# Specify the path where deflator data will be saved
+set_pydeflate_path("path/to/data/folder")
+
+# Get deflators for specific countries and years
+deflators = get_imf_gdp_deflators(
+    base_year=2015,
+    source_currency="USA",
+    target_currency="EUR",
+    countries=["USA", "FRA", "GBR"],  # Optional: filter specific countries
+    years=range(2010, 2024),  # Optional: filter specific years
+)
+
+# Returns a DataFrame with columns: iso_code, year, deflator
+print(deflators.head())
+```
+
+You can also get the individual components that make up the deflator:
+
+```python
+# Include price deflator, exchange deflator, and exchange rate components
+deflators_detailed = get_imf_gdp_deflators(
+    base_year=2015,
+    source_currency="USA",
+    target_currency="EUR",
+    include_components=True,  # Adds price_deflator, exchange_deflator, exchange_rate columns
+)
+```
+
+### Available Get Deflator Functions
+
+- `get_imf_gdp_deflators`: Get IMF GDP deflators
+- `get_imf_cpi_deflators`: Get IMF CPI deflators
+- `get_imf_cpi_e_deflators`: Get IMF end-of-period CPI deflators
+- `get_wb_gdp_deflators`: Get World Bank GDP deflators
+- `get_wb_gdp_linked_deflators`: Get World Bank linked GDP deflators
+- `get_wb_cpi_deflators`: Get World Bank CPI deflators
+- `get_oecd_dac_deflators`: Get OECD DAC deflators
+
+### Getting Exchange Rates
+
+```python
+from pydeflate import get_imf_exchange_rates
+
+# Get exchange rates for specific currency pairs
+rates = get_imf_exchange_rates(
+    source_currency="USD",
+    target_currency="EUR",
+    countries=["USA", "FRA", "GBR"],  # Optional: filter specific countries
+    years=range(2010, 2024),  # Optional: filter specific years
+)
+
+# Returns a DataFrame with columns: iso_code, year, exchange_rate
+print(rates.head())
+```
+
+### Available Get Exchange Rate Functions
+
+- `get_imf_exchange_rates`: Get IMF exchange rates
+- `get_wb_exchange_rates`: Get World Bank exchange rates
+- `get_wb_ppp_rates`: Get World Bank PPP conversion rates
+- `get_oecd_dac_exchange_rates`: Get OECD DAC exchange rates
+
+### Common Use Cases
+
+**Analyzing deflator trends:**
+```python
+import matplotlib.pyplot as plt
+
+# Get US GDP deflators over time
+deflators = get_imf_gdp_deflators(
+    base_year=2015,
+    countries=["USA"],
+    years=range(2000, 2024)
+)
+
+plt.plot(deflators["year"], deflators["deflator"])
+plt.title("US GDP Deflator (Base Year 2015)")
+plt.show()
+```
+
+**Pre-computing deflators for manual calculations:**
+```python
+# Get deflators
+deflators = get_imf_gdp_deflators(
+    base_year=2020,
+    source_currency="USA",
+    target_currency="EUR"
+)
+
+# Use in your own calculations
+my_value_2021 = 100  # USD in 2021
+deflator_2021 = deflators[(deflators["iso_code"] == "USA") &
+                          (deflators["year"] == 2021)]["deflator"].iloc[0]
+constant_value = my_value_2021 / deflator_2021
+```
+
 ## Example: Using Source-Specific Codes
 
 If your data uses source-specific country codes (e.g., DAC codes), set use_source_codes=True and specify the appropriate id_column.
@@ -383,3 +496,22 @@ This is useful for:
 - Customizing logging verbosity
 - Testing with temporary cache directories
 
+## Documentation
+
+For comprehensive documentation including detailed examples, advanced features, and troubleshooting:
+
+**[📚 Full Documentation](https://jm-rivera.github.io/pydeflate/)**
+
+The documentation includes:
+- [Getting Started Guide](https://jm-rivera.github.io/pydeflate/getting-started/) - Setup and DataFrame requirements
+- [Deflation Guide](https://jm-rivera.github.io/pydeflate/deflation/) - All deflation methods with examples
+- [Currency Exchange](https://jm-rivera.github.io/pydeflate/exchange/) - Currency conversion examples
+- [Data Sources](https://jm-rivera.github.io/pydeflate/data-sources/) - IMF, World Bank, and OECD DAC comparison
+- [Advanced Topics](https://jm-rivera.github.io/pydeflate/advanced/exceptions/) - Error handling, contexts, plugins, validation
+- [Migration Guide](https://jm-rivera.github.io/pydeflate/migration/) - v1 to v2 migration
+- [FAQ](https://jm-rivera.github.io/pydeflate/faq/) - Common questions and troubleshooting
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request or open an issue on [GitHub](https://github.com/jm-rivera/pydeflate).
+

{pydeflate-2.2.0 → pydeflate-2.3.0}/README.md

@@ -3,6 +3,7 @@
 [![pypi](https://img.shields.io/pypi/v/pydeflate.svg)](https://pypi.python.org/pypi/pydeflate)
 [![black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![Downloads](https://pepy.tech/badge/pydeflate/month)](https://pepy.tech/project/pydeflate)
+[![Documentation](https://img.shields.io/badge/docs-mkdocs-blue)](https://jm-rivera.github.io/pydeflate/)
 
 **pydeflate** is a Python package to:
 - Convert current price data to constant prices.
@@ -11,6 +12,8 @@
 
 When converting to or from constant prices, it takes into account changes in prices and exchange rates over time. This allows for accurate comparisons across years, countries, and currencies.
 
+📚 **[Read the full documentation →](https://jm-rivera.github.io/pydeflate/)**
+
 ## Important Note
 
 **pydeflate v2 has recently been released. It includes api changes which break backwards-compatibility**. While a version of the `deflate` function is still available, it is now deprecated and will be removed in future versions. Please use the new deflator functions for improved simplicity, clarity and performance.
@@ -33,6 +36,11 @@ When converting to or from constant prices, it takes into account changes in pri
 - [Currency Conversion](#currency-conversion)
   - [Example](#example-currency-conversion)
 
+- [Getting Deflators and Exchange Rates Directly](#getting-deflators-and-exchange-rates-directly)
+  - [Getting Deflators](#getting-deflators)
+  - [Getting Exchange Rates](#getting-exchange-rates)
+  - [Common Use Cases](#common-use-cases)
+
 - [Example: Using Source-Specific Codes](#example-using-source-specific-codes)
 
 - [Data Sources and Method Options](#data-sources-and-method-options)
@@ -157,6 +165,111 @@ df_can = oecd_dac_exchange(
 )
 ```
 
+## Getting Deflators and Exchange Rates Directly
+
+**New in v2.3.0**: You can now retrieve deflator and exchange rate data directly as DataFrames, without needing to provide your own data. This is useful for inspecting deflators, analyzing trends, or pre-computing values for later use.
+
+### Getting Deflators
+
+```python
+from pydeflate import get_imf_gdp_deflators, set_pydeflate_path
+
+# Specify the path where deflator data will be saved
+set_pydeflate_path("path/to/data/folder")
+
+# Get deflators for specific countries and years
+deflators = get_imf_gdp_deflators(
+    base_year=2015,
+    source_currency="USA",
+    target_currency="EUR",
+    countries=["USA", "FRA", "GBR"],  # Optional: filter specific countries
+    years=range(2010, 2024),  # Optional: filter specific years
+)
+
+# Returns a DataFrame with columns: iso_code, year, deflator
+print(deflators.head())
+```
+
+You can also get the individual components that make up the deflator:
+
+```python
+# Include price deflator, exchange deflator, and exchange rate components
+deflators_detailed = get_imf_gdp_deflators(
+    base_year=2015,
+    source_currency="USA",
+    target_currency="EUR",
+    include_components=True,  # Adds price_deflator, exchange_deflator, exchange_rate columns
+)
+```
+
+### Available Get Deflator Functions
+
+- `get_imf_gdp_deflators`: Get IMF GDP deflators
+- `get_imf_cpi_deflators`: Get IMF CPI deflators
+- `get_imf_cpi_e_deflators`: Get IMF end-of-period CPI deflators
+- `get_wb_gdp_deflators`: Get World Bank GDP deflators
+- `get_wb_gdp_linked_deflators`: Get World Bank linked GDP deflators
+- `get_wb_cpi_deflators`: Get World Bank CPI deflators
+- `get_oecd_dac_deflators`: Get OECD DAC deflators
+
+### Getting Exchange Rates
+
+```python
+from pydeflate import get_imf_exchange_rates
+
+# Get exchange rates for specific currency pairs
+rates = get_imf_exchange_rates(
+    source_currency="USD",
+    target_currency="EUR",
+    countries=["USA", "FRA", "GBR"],  # Optional: filter specific countries
+    years=range(2010, 2024),  # Optional: filter specific years
+)
+
+# Returns a DataFrame with columns: iso_code, year, exchange_rate
+print(rates.head())
+```
+
+### Available Get Exchange Rate Functions
+
+- `get_imf_exchange_rates`: Get IMF exchange rates
+- `get_wb_exchange_rates`: Get World Bank exchange rates
+- `get_wb_ppp_rates`: Get World Bank PPP conversion rates
+- `get_oecd_dac_exchange_rates`: Get OECD DAC exchange rates
+
+### Common Use Cases
+
+**Analyzing deflator trends:**
+```python
+import matplotlib.pyplot as plt
+
+# Get US GDP deflators over time
+deflators = get_imf_gdp_deflators(
+    base_year=2015,
+    countries=["USA"],
+    years=range(2000, 2024)
+)
+
+plt.plot(deflators["year"], deflators["deflator"])
+plt.title("US GDP Deflator (Base Year 2015)")
+plt.show()
+```
+
+**Pre-computing deflators for manual calculations:**
+```python
+# Get deflators
+deflators = get_imf_gdp_deflators(
+    base_year=2020,
+    source_currency="USA",
+    target_currency="EUR"
+)
+
+# Use in your own calculations
+my_value_2021 = 100  # USD in 2021
+deflator_2021 = deflators[(deflators["iso_code"] == "USA") &
+                          (deflators["year"] == 2021)]["deflator"].iloc[0]
+constant_value = my_value_2021 / deflator_2021
+```
+
 ## Example: Using Source-Specific Codes
 
 If your data uses source-specific country codes (e.g., DAC codes), set use_source_codes=True and specify the appropriate id_column.
@@ -358,3 +471,22 @@ This is useful for:
 - Customizing logging verbosity
 - Testing with temporary cache directories
 
+## Documentation
+
+For comprehensive documentation including detailed examples, advanced features, and troubleshooting:
+
+**[📚 Full Documentation](https://jm-rivera.github.io/pydeflate/)**
+
+The documentation includes:
+- [Getting Started Guide](https://jm-rivera.github.io/pydeflate/getting-started/) - Setup and DataFrame requirements
+- [Deflation Guide](https://jm-rivera.github.io/pydeflate/deflation/) - All deflation methods with examples
+- [Currency Exchange](https://jm-rivera.github.io/pydeflate/exchange/) - Currency conversion examples
+- [Data Sources](https://jm-rivera.github.io/pydeflate/data-sources/) - IMF, World Bank, and OECD DAC comparison
+- [Advanced Topics](https://jm-rivera.github.io/pydeflate/advanced/exceptions/) - Error handling, contexts, plugins, validation
+- [Migration Guide](https://jm-rivera.github.io/pydeflate/migration/) - v1 to v2 migration
+- [FAQ](https://jm-rivera.github.io/pydeflate/faq/) - Common questions and troubleshooting
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request or open an issue on [GitHub](https://github.com/jm-rivera/pydeflate).
+

{pydeflate-2.2.0 → pydeflate-2.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pydeflate"
-version = "2.2.0"
+version = "2.3.0"
 description = "Package to convert current prices figures to constant prices and vice versa"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -30,6 +30,11 @@ dev = [
     "pytest-cov>=7.0.0",
     "ruff>=0.13.3",
 ]
+docs = [
+    "mkdocs-material>=9.5.0",
+    "mkdocs-minify-plugin>=0.8.0",
+    "mkdocstrings[python]>=0.26.0",
+]
 
 [project.urls]
 Homepage = "https://github.com/jm-rivera/pydeflate"

{pydeflate-2.2.0 → pydeflate-2.3.0}/src/pydeflate/__init__.py

@@ -1,5 +1,5 @@
 __author__ = """Jorge Rivera"""
-__version__ = "2.2.0"
+__version__ = "2.3.0"
 
 from pydeflate.deflate.deflators import (
     imf_cpi_deflate,
@@ -10,6 +10,15 @@ from pydeflate.deflate.deflators import (
     wb_gdp_deflate,
     wb_gdp_linked_deflate,
 )
+from pydeflate.deflate.get_deflators import (
+    get_imf_cpi_deflators,
+    get_imf_cpi_e_deflators,
+    get_imf_gdp_deflators,
+    get_oecd_dac_deflators,
+    get_wb_cpi_deflators,
+    get_wb_gdp_deflators,
+    get_wb_gdp_linked_deflators,
+)
 from pydeflate.deflate.legacy_deflate import deflate
 from pydeflate.exchange.exchangers import (
     imf_exchange,
@@ -17,6 +26,12 @@ from pydeflate.exchange.exchangers import (
     wb_exchange,
     wb_exchange_ppp,
 )
+from pydeflate.exchange.get_rates import (
+    get_imf_exchange_rates,
+    get_oecd_dac_exchange_rates,
+    get_wb_exchange_rates,
+    get_wb_ppp_rates,
+)
 from pydeflate.pydeflate_config import set_data_dir, setup_logger
 
 from pydeflate.context import (
@@ -60,11 +75,24 @@ __all__ = [
     "wb_cpi_deflate",
     "wb_gdp_deflate",
     "wb_gdp_linked_deflate",
+    # Get deflators functions
+    "get_imf_cpi_deflators",
+    "get_imf_cpi_e_deflators",
+    "get_imf_gdp_deflators",
+    "get_oecd_dac_deflators",
+    "get_wb_cpi_deflators",
+    "get_wb_gdp_deflators",
+    "get_wb_gdp_linked_deflators",
     # Exchange functions
     "imf_exchange",
     "oecd_dac_exchange",
     "wb_exchange",
     "wb_exchange_ppp",
+    # Get exchange rates functions
+    "get_imf_exchange_rates",
+    "get_oecd_dac_exchange_rates",
+    "get_wb_exchange_rates",
+    "get_wb_ppp_rates",
     # Configuration
     "set_pydeflate_path",
     "setup_logger",

pydeflate-2.3.0/src/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-2.3.0/src/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: ...