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

{pydeflate-2.1.3.dist-info → pydeflate-2.3.0.dist-info}/METADATA

@@ -1,24 +1,26 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: pydeflate
-Version: 2.1.3
+Version: 2.3.0
 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)
+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
@@ -26,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.
@@ -34,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.
@@ -56,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)
@@ -180,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.
@@ -280,5 +395,123 @@ 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
+
+## 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.3.0.dist-info/RECORD

@@ -0,0 +1,34 @@
+pydeflate/.pydeflate_data/README.md,sha256=atNtUL9dD8G184YSd6juFib8TgEQBcSLogiz99APPVs,25
+pydeflate/__init__.py,sha256=Bp8xuw0h7-bOrtKXMRqxE_PjdZsPGKCP1zthphGSu3U,2747
+pydeflate/cache.py,sha256=jfNilTrzGucdFpaTn6AwQWCFMT5123ZgcYwhDgtsCK8,4755
+pydeflate/constants.py,sha256=-xxH2skAWHHMQxIJSFWOayU-GmRlqowjkIhIzvyUuac,2972
+pydeflate/context.py,sha256=0HBHnaHcpESDbyfZLo-5W_Kg03WI5Itf0LCABa2w08E,6565
+pydeflate/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pydeflate/core/api.py,sha256=W-MFdxsbO1dNG0pX1e2xxtjQL3qmYxTqiLLISVkizQA,15941
+pydeflate/core/deflator.py,sha256=Ax3dmOF3tYRZnkIfFvMMo3SOLgAJHkXSmA-OtIUZkp0,5932
+pydeflate/core/exchange.py,sha256=br6RVgTGa7LW09XemUJZ4Koazf65zuXPQKYKGhS6ROM,8535
+pydeflate/core/source.py,sha256=dZiMqVdUXD6KQ0RuzR4clb7sCPYcCMZOkg9GhhjqppI,4908
+pydeflate/deflate/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pydeflate/deflate/deflators.py,sha256=qd6afJfVNHpNb12xDfS0TGHg5p4ngH5Tb_CWk6555Us,7768
+pydeflate/deflate/get_deflators.py,sha256=rR5lTU_rv2tEPlNEMwGXuUC3vY2fQ5k9MZMvw4T8J5I,8308
+pydeflate/deflate/legacy_deflate.py,sha256=N9tIuKzVOQtSw5QBeJG6Um86nheLG0yXgdvPVZCmrIA,3900
+pydeflate/exceptions.py,sha256=31LzEG0aOT41e6S21NvsR2Lt_pozQmVgonqLwvOcn7I,4711
+pydeflate/exchange/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pydeflate/exchange/exchangers.py,sha256=HxKM2cqDEArQplww2d-lm-EAbccSMxEovErpkgTunkk,6721
+pydeflate/exchange/get_rates.py,sha256=-v9QbKWNKGTtsWqSUXD0j0S2qtan6wtXhu3DQN6akSk,7775
+pydeflate/plugins.py,sha256=fZxO79v4cbbHvsYAvstIC7kk2uSPVCiurXqrS2mukqI,8872
+pydeflate/protocols.py,sha256=0jVSynQItjt-yv8HSU19RPQrfo1Vgo7Ws1CQfX5ZIaI,4694
+pydeflate/pydeflate_config.py,sha256=9r8tu-k-XhFMM2x3dQwEjk2dHj-pwdUf6pdvEowbE2I,2725
+pydeflate/schemas.py,sha256=XBfBVIQjie6IK5rsEn6MSBqv5IxRkKxa7xnc7UaH9kU,7779
+pydeflate/settings/emu.json,sha256=BIvbiMUeHUtCESR3sMcBNrS028yp2YraCJdhDJGvAAo,133
+pydeflate/settings/oecd_codes.json,sha256=jAKI1EgQP4rttjoG3Z-44r1tUJrIEzPCZF5V2aboQhE,911
+pydeflate/sources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pydeflate/sources/common.py,sha256=37HuExGr86RtCD-ZkF0NiIIfRbGgPbImZCQeZjYSzhk,8509
+pydeflate/sources/dac.py,sha256=RkO_nFZcp8AeSJNFzdBrGqaL2kLVUeXBHTPO6PkUFy0,3824
+pydeflate/sources/imf.py,sha256=Nu8Gm4wT-FdBpTuaYUrzOC2V3BNP9srNOIuQJ9E16_0,6712
+pydeflate/sources/world_bank.py,sha256=1DzDlr0Xe0DA0OUsycjwiq-4yMasnP0TneXEK0VmcRw,7281
+pydeflate/utils.py,sha256=HRVMUuWKS1IpU8lmkvQN1jIMA5-LEFzyEd0ReZSx65k,4252
+pydeflate-2.3.0.dist-info/licenses/LICENSE,sha256=8ymAThz7Z4JhjqL6vDwTaoq29tFytQRDkoW3rnTGstI,1075
+pydeflate-2.3.0.dist-info/WHEEL,sha256=n2u5OFBbdZvCiUKAmfnY1Po2j3FB_NWfuUlt5WiAjrk,79
+pydeflate-2.3.0.dist-info/METADATA,sha256=dMxbCpdH_ya7gJ4WNrqAfxwVseSd30-Ln1nLtn3jwsI,20555
+pydeflate-2.3.0.dist-info/RECORD,,

pydeflate-2.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.8.23
+Root-Is-Purelib: true
+Tag: py3-none-any

{pydeflate-2.1.3.dist-info → pydeflate-2.3.0.dist-info/licenses}/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.3.dist-info/RECORD

@@ -1,25 +0,0 @@
-pydeflate/.pydeflate_data/README.md,sha256=atNtUL9dD8G184YSd6juFib8TgEQBcSLogiz99APPVs,25
-pydeflate/__init__.py,sha256=_E54U6FY77A_i2PSCt-oUF0E4EN2GiEpBotw1IQ6fXk,1013
-pydeflate/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pydeflate/core/api.py,sha256=iB4fLdfnqN_nLLcnMzWtoGksQ6y4sfL0CZsVpiiPGQY,14687
-pydeflate/core/deflator.py,sha256=Ax3dmOF3tYRZnkIfFvMMo3SOLgAJHkXSmA-OtIUZkp0,5932
-pydeflate/core/exchange.py,sha256=br6RVgTGa7LW09XemUJZ4Koazf65zuXPQKYKGhS6ROM,8535
-pydeflate/core/source.py,sha256=n603ocgGjthXNcBWwgADkefxWmSFuN77Km9Z0T2zpIg,2027
-pydeflate/deflate/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pydeflate/deflate/deflators.py,sha256=hyLFoX46BAn5m8gTLjw-TFv3x3W6CTQmvmUvq5a_cio,7768
-pydeflate/deflate/legacy_deflate.py,sha256=9pfqsi5KeWgP1yhXeI6K7bAjUeFY-fmRxrpDB7Zu0zo,3900
-pydeflate/exchange/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pydeflate/exchange/exchangers.py,sha256=TQ4puU1T2fFQ5gpTP1RUyqJMIXZc1voOyTtS2wj1zrk,6721
-pydeflate/pydeflate_config.py,sha256=5s4SLJf5is5XcUgJHDRx4f27pPiaVh0H2BL8w9QjW0k,1097
-pydeflate/settings/emu.json,sha256=BIvbiMUeHUtCESR3sMcBNrS028yp2YraCJdhDJGvAAo,133
-pydeflate/settings/oecd_codes.json,sha256=jAKI1EgQP4rttjoG3Z-44r1tUJrIEzPCZF5V2aboQhE,911
-pydeflate/sources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pydeflate/sources/common.py,sha256=zm8fvPES4g1BWzVAGiLX7wMOEfMSdqdeQ_RIm3ucR0E,9978
-pydeflate/sources/dac.py,sha256=ngFiApGZ_tIQg74ogGVTIbGUA0efnF1SYwfUuqGofOQ,3791
-pydeflate/sources/imf.py,sha256=fuUq_dq_fcxd-bz-VokqPTxEttyFwHunUSEeGDAmGMc,7167
-pydeflate/sources/world_bank.py,sha256=uMHidFVgEpj1HVUnNhIZV-rV64hsCBV9ZAbYKk6H0Vw,9333
-pydeflate/utils.py,sha256=tJBd271WzZxVhW9ZMiIRHR0fZWr_MagAYLdmXXaUY3M,3983
-pydeflate-2.1.3.dist-info/LICENSE,sha256=q5tm9mQxwSbV5Ivvjxs7MMqBgan6DM8I4r4irPvmqZM,1075
-pydeflate-2.1.3.dist-info/METADATA,sha256=uko5SoGA28g70lBi567CZnZ5upLCPk-GShbVHr-G2Ts,12437
-pydeflate-2.1.3.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-pydeflate-2.1.3.dist-info/RECORD,,

pydeflate-2.1.3.dist-info/WHEEL

@@ -1,4 +0,0 @@
-Wheel-Version: 1.0
-Generator: poetry-core 2.1.3
-Root-Is-Purelib: true
-Tag: py3-none-any