Metadata-Version: 2.4
Name: nbp_rates
Version: 1.5.20260724
Summary: A modular library for NBP exchange rates with offline and online support.
Keywords: NBP,exchange,rates,exchange rates,currency,FX,Foreign Exchange,forex,polska,pln,waluty,kursy,kursy walut,narodowy bank polski,nbp api,nbp rates,nbp exchange rates
Author: Sebastian Kowalik
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Natural Language :: Polish
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
License-File: LICENSE
Requires-Dist: pytest>=6.0 ; extra == "dev"
Requires-Dist: pytest-cov>=2.12 ; extra == "dev"
Requires-Dist: twine>=3.4 ; extra == "dev"
Requires-Dist: build>=0.7 ; extra == "dev"
Requires-Dist: pytest>=6.0 ; extra == "test"
Requires-Dist: pytest-cov>=2.12 ; extra == "test"
Project-URL: Bug Tracker, https://github.com/varciasz/nbp_rates/issues
Project-URL: Homepage, https://github.com/varciasz/nbp_rates
Project-URL: Repository, https://github.com/varciasz/nbp_rates.git
Provides-Extra: dev
Provides-Extra: test

# nbp_rates

A modular Python library for providing NBP (Narodowy Bank Polski) exchange rates with both offline and online support. Very fast and easy to use.

## Features

- **Offline Support**: Includes historical exchange rates data from 1984 to 23-July-2026
- **Online Fallback**: Automatically fetches from NBP API for dates after 23-July-2026
- **Dual Table Support**: Supports both Table A (major currencies) and Table B (minor currencies)
- **Smart Fallback**: Optionally searches last available rate before given date (handles holidays, weekends and missing data)
- **Super Fast**: Optimized for speed with most queries served from local data with minimal API calls
- **Easy and Powerful**: Simple to use with 200+ currencies supported
- **Precise and exact output**: No rounding within library. Results provided as string to avoid floating-point rounding issues
- **Reliable**: As most of data is served offline, it is not affected by NBP API downtime, responsiveness or rate limits
- **Flexible Date Input**: Accepts `datetime.date`, `datetime.datetime`, or ISO format strings (YYYY-MM-DD)
- **No external dependencies**: Pure Python with standard library
- **Daily Updates**: new version of library released daily with the latest exchange rates available offline


## Installation

Install from PyPI:

```bash
pip install nbp_rates
```

Or install in development mode from the repository:

```bash
git clone https://github.com/varciasz/nbp_rates.git
cd nbp_rates
pip install -e .
```

## Requirements

- Python 3.6 or higher
- No external dependencies (uses only Python standard library)

## Usage

### Basic Usage

Get the exchange rate for a specific date and currency:

```python
from nbp_rates import ProvideCurrencyRate
from datetime import date

# Get USD rate for a specific date
rate = ProvideCurrencyRate(date(2024, 1, 15), 'USD')
print(f"USD rate on 2024-01-15: {rate}")

# Using a string date (ISO format)
rate = ProvideCurrencyRate('2024-01-15', 'EUR')
print(f"EUR rate on 2024-01-15: {rate}")

# Using datetime object
from datetime import datetime
rate = ProvideCurrencyRate(datetime(2024, 1, 15, 10, 30), 'GBP')
print(f"GBP rate on 2024-01-15: {rate}")
```

### Using Fallback

Enable fallback to search up to 31 days back for an available rate (useful for holidays, weekends and missing data):

```python
# Get rate for a holiday, falling back to previous business day if needed
rate = ProvideCurrencyRate(date(2024, 1, 1), 'USD', fallback=True)
print(f"USD rate: {rate}")
```

### Return Values

- Successfully fetched rate: String representation of the exchange rate (e.g., `"4.25"`)
- Currency not found: `"Error - wrong currency"`
- Module loading error: `"Error - unable to load currency module"`
- Fallback limit exceeded or rate not found: `"-1"`

### Supported Currencies

The library supports 200+ currencies including:

**Major currencies (Table A):**
USD, EUR, GBP, JPY, CHF, CAD, AUD, and many more

**Minor currencies (Table B):**
INR, CNY, MXN, BRL, ZAR, SGD, and many more

See the source code for the complete list of `TABLE_A_CURRENCIES` and `TABLE_B_CURRENCIES`.

## API Reference

### `ProvideCurrencyRate(date_given, currency, fallback=False, _depth=0)`

Fetches the FX rate for a given date and currency.

**Parameters:**
- `date_given` (datetime.date, datetime.datetime, or str): The date for which to fetch the rate
- `currency` (str): ISO 4217 currency code (e.g., 'USD', 'EUR')
- `fallback` (bool, optional): If True, searches up to 31 days back for available rates. Default: False
- `_depth` (int, optional): Internal parameter for recursion tracking. Default: 0

**Returns:**
- str: Exchange rate as a string, or error message

**Raises:**
- ValueError: If the date format is invalid or currency is not recognized

## Data Sources

- **Offline Data**: Embedded exchange rate data from 1984 to 23-July-2026
- **Online Data**: NBP API (`https://api.nbp.pl/`) for dates after the offline data cutoff

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Author

Sebastian Kowalik

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Changelog

### Current Version 1.5.20260724
- Library is updated daily with the latest exchange rates included offline. Last 8 digits of version number represent the date when the version was generated (YYYYMMDD).

### Version 1.5
- First official stable version with automated daily updates and support for 200+ currencies.

