semvec/pypi-packages huggingface dataset:
prepid 1.0.0
A Python package for fetching and converting currency rates using the Prebid currency file.
Requires Python: >=3.8
Keywords: converter, currency, exchange-rates, prebid

# Prebid Currency Converter

[![PyPI version](https://img.shields.io/pypi/v/prepid)](https://pypi.org/project/prepid/)
[![CI](https://github.com/kokamkarsahil/prepid-py/actions/workflows/python-package.yml/badge.svg)](https://github.com/kokamkarsahil/prepid-py/actions/workflows/python-package.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Python package for fetching and converting currency rates using the Prebid currency file. The library provides a simple interface to convert amounts between different currencies, with automatic caching of currency data to minimize API requests.

## Installation

```bash
pip install prepid
```

## Quick Start

```python
from prepid import CurrencyConverter

converter = CurrencyConverter()

# Convert 100 USD to EUR
amount = converter.convert_currency(100, "USD", "EUR")
print(f"100 USD = {amount:.2f} EUR")
```

## Usage

### Convert Currency

```python
from prepid import CurrencyConverter, CurrencyError

converter = CurrencyConverter()

try:
    result = converter.convert_currency(250, "GBP", "USD")
    print(f"250 GBP = {result:.2f} USD")
except CurrencyError as e:
    print(f"Conversion failed: {e}")
```

Currency codes are **case-insensitive** — `"usd"`, `"USD"`, and `" Usd "` all work.

### Get a Conversion Rate

```python
rate = converter.get_conversion_rate("EUR", "GBP")
print(f"1 EUR = {rate:.4f} GBP")
```

### List Available Currencies

```python
currencies = converter.list_available_currencies()
print(", ".join(currencies))  # AED, ARS, AUD, ...
```

### Caching

The library caches currency data both **in-memory** and **on disk** to avoid redundant API calls. By default, data expires after 6 hours:

```python
# Set cache to expire after 24 hours
converter = CurrencyConverter(cache_duration_hours=24)
```

The disk cache is stored in a platform-appropriate user cache directory.

## API Reference

### `CurrencyConverter(cache_duration_hours=6)`

| Method | Returns | Description |
|---|---|---|
| `convert_currency(amount, from_currency, to_currency)` | `float` | Convert an amount between currencies |
| `get_conversion_rate(from_currency, to_currency)` | `float` | Get the rate multiplier between two currencies |
| `list_available_currencies()` | `list[str]` | Sorted list of available currency codes |
| `get_currency_rates()` | `dict` | Raw currency data from the Prebid API |

### `CurrencyError`

Raised when a conversion fails (invalid currency code, network error, etc.).

## Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue on the [GitHub repository](https://github.com/kokamkarsahil/prepid-py/issues).

## License

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