Metadata-Version: 2.4
Name: imf-fx
Version: 0.1.0
Summary: High-performance Python client for IMF SDMX 3.0 exchange-rate data, with a monthly USD dataset helper.
Author-email: Cody Wallace <codywallace.dev@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Cody Wallace
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to do so, subject to the
        following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/codywallace/imf-fx
Project-URL: Repository, https://github.com/codywallace/imf-fx
Project-URL: Issues, https://github.com/codywallace/imf-fx/issues
Keywords: imf,sdmx,sdmx-3.0,exchange-rates,fx,polars,development-finance,iati,oecd,crs,financial-modeling
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.32.0
Requires-Dist: polars>=1.0.0
Requires-Dist: pycountry>=24.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: ruff>=0.8.4; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.7.0; extra == "dev"
Dynamic: license-file

# imf-fx

![CI](https://github.com/codywallace/imf-fx/actions/workflows/ci.yml/badge.svg)
![PyPI](https://img.shields.io/pypi/v/imf-fx)
![Python](https://img.shields.io/pypi/pyversions/imf-fx)
![License](https://img.shields.io/pypi/l/imf-fx)


---


High-performance Python client for IMF SDMX 3.0 exchange-rate data, with a production-ready monthly USD dataset helper.

---

## Overview

The International Monetary Fund (IMF) publishes official exchange rate data through its SDMX 3.0 API.

`imf-fx` provides:

- Direct integration with the official SDMX 3.0 exchange-rate endpoint
- Batched country requests for efficient network usage
- Fast parsing using Polars
- Client-side time-window enforcement
- ISO2 and ISO3 country compatibility
- Log exchange rate output for modeling workflows

Unlike spreadsheet scraping or HTML extraction approaches, `imf-fx` uses the official IMF SDMX 3.0 API contract directly. This ensures structural stability and alignment with IMF data standards.

---

## Why This Is Useful

Exchange rate normalization is essential for:

- Development finance analytics
- Aid Information Management Systems (AIMS)
- Development Finance Information Management Systems (DFIMS)
- IATI data processing
- OECD CRS normalization
- Public financial management dashboards
- Cross-country budget comparisons
- Financial modeling pipelines

Public finance systems frequently ingest transactions denominated in multiple currencies. Consistent historical FX normalization ensures:

- Accurate aggregation across currencies
- Time-consistent financial comparisons
- Reproducible modeling
- Transparent auditability of conversions

`imf-fx` provides a fast, structured, and authoritative way to obtain exchange rate data for these workflows.

---

## Installation

```bash
pip install imf-fx

```

Python 3.11 or newer is required.

---

## Quick Start

Download the full monthly USD dataset

```Python
from imf_fx import monthly_usd_only

df = monthly_usd_only()
print(df.head())

```
---

## Bulk exports

The dataset can be written directly to CSV, or export to Parquet for use in other systems

```Python
from imf_fx import monthly_usd_only

df = monthly_usd_only()

df.write_csv("imf_monthly_usd.csv")
df.write_parquet("imf_monthly_usd.parquet")

```

---

Download a specific time-window

```Python
from imf_fx import monthly_usd_only

df = monthly_usd_only(
    start="2020-M01",
    end="2020-M12"
)

```

---

Retreive dataset with metadata

```Python
from imf_fx import monthly_usd_only

df, meta = monthly_usd_only(return_meta=True)

print(meta)

```

---

Example metadata output:

```Python
{
  "countries_requested": 260,
  "countries_with_data": 222,
  "rows_final": 154333,
  "min_period": "1924-M06",
  "max_period": "2026-M01",
  "elapsed_s": 2.7
}

```


## Output Schema

The normalized dataset includes

| Column                 | Description                   |
| ---------------------- | ----------------------------- |
| `country_iso3`         | ISO 3-letter country code     |
| `country_iso2`         | ISO 2-letter country code     |
| `country_name`         | Country name                  |
| `date`                 | End-of-month date             |
| `ym`                   | Year-month string (`YYYY-MM`) |
| `usd_per_domestic`     | Domestic currency per 1 USD   |
| `log_usd_per_domestic` | Natural log of exchange rate  |


Both ISO2 and ISO3 codes are included to simplify integration with:

- IATI datasets
- OECD CRS datasets
- National aid platforms
- Government finance systems
- Custom financial tools and pipelines

Users do not need to perform separate country code mapping.

---

## Performance

The dataset helper uses:

- Batched SDMX country keys (reducing HTTP calls)
- Parallel batch fetching
- Polars-based parsing for speed and memory efficiency
- Columnar construction rather than row-by-row dictionary assembly

Typical performance:

- Full historical dataset (1924–present)
- 150k rows
- ~2–3 seconds on a standard machine

Time-windowed requests are significantly faster.

---

## Minimal Dependencies

External dependencies are intentionally minimal:

- requests
- polars
- pycountry

This keeps the package lightweight and suitable for integration into larger systems.

---

## Public API

Stable public interface:

```Python
from imf_fx import monthly_usd_only

```

---

## License

MIT License

---

## IMF Data License

The source of the data is extracted from the IMF's Exchange Data.

Below is an excerpt on the IMF Copyright and Usage page, effective 11 October, 2024; accessed 2026-02-23:

> You may download, extract, copy, create derivative works, publish, distribute, and use Data obtained from IMF Sites, subject to the following conditions:
>
> Whether obtained directly from the IMF or another party, when Data is distributed or reproduced in any manner, it must appear accurately with attribution to the IMF as the source, e.g. “Source: International Monetary Fund, Database Name, <<link to the dataset>>.”
>
> Users shall not infringe upon the integrity of the Data and in particular shall refrain from any act of alteration of the Data that intentionally affects its nature or accuracy. If the Data is materially transformed by the User, this must be stated explicitly along with the required source citation.
>
> Users who make IMF Data available to other Users through any type of distribution or download environment agree to take reasonable efforts to communicate and promote compliance by their users with these terms.
>
> If IMF Data is sold by Users as a standalone product, sellers must inform purchasers that the Data is available free of charge from the IMF.
>
> The Data is provided to Users “as is” and without warranty of any kind, either express or implied, including, without limitation, warranties of merchantability, fitness for a particular purpose, and noninfringement.
>
> The policy of free access and free reuse of IMF Data does not imply a right to obtain confidential or any unpublished data, over which the IMF reserves all rights.
>
> Except as stated in this Section on Data Usage, all other terms set forth in the general terms and conditions shall continue to apply to use of IMF Data.
>
> For any potential commercial reuse of IMF Data, please email copyright@imf.org to request permission.
