Metadata-Version: 2.4
Name: streamlit-unirate
Version: 0.1.0
Summary: Streamlit integration for the UniRate currency-exchange API — cached helpers with st.cache_resource and st.cache_data support.
Project-URL: Homepage, https://github.com/UniRate-API/streamlit-unirate
Project-URL: Repository, https://github.com/UniRate-API/streamlit-unirate
Project-URL: Issues, https://github.com/UniRate-API/streamlit-unirate/issues
Project-URL: Provider, https://unirateapi.com
Author: Unirate Team
License: MIT
License-File: LICENSE
Keywords: currency,data,exchange-rates,fintech,forex,money,streamlit,unirate
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: streamlit<2.0,>=1.25
Requires-Dist: unirate-api<2.0,>=1.0
Description-Content-Type: text/markdown

# streamlit-unirate

Streamlit integration for the [UniRate API](https://unirateapi.com) — live exchange rates, currency conversion, and VAT rates with automatic `st.cache_data` / `st.cache_resource` caching built in.

[![PyPI](https://img.shields.io/pypi/v/streamlit-unirate)](https://pypi.org/project/streamlit-unirate/)
[![Python](https://img.shields.io/pypi/pyversions/streamlit-unirate)](https://pypi.org/project/streamlit-unirate/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![CI](https://github.com/UniRate-API/streamlit-unirate/actions/workflows/test.yml/badge.svg)](https://github.com/UniRate-API/streamlit-unirate/actions)

## Installation

```bash
pip install streamlit-unirate
```

## Quick start

```python
import streamlit as st
import streamlit_unirate as ur

# List currencies (cached 1 h)
currencies = ur.list_currencies()

from_cur = st.selectbox("From", currencies)
to_cur   = st.selectbox("To",   currencies)
amount   = st.number_input("Amount", value=100.0)

if st.button("Convert"):
    result = ur.convert(to_cur, amount, from_cur)
    st.metric(f"{amount} {from_cur} →", f"{result:.4f} {to_cur}")
```

## API key

Set `UNIRATE_API_KEY` in `.streamlit/secrets.toml` (preferred) or as an environment variable:

```toml
# .streamlit/secrets.toml
UNIRATE_API_KEY = "your_api_key_here"
```

```bash
UNIRATE_API_KEY=your_key streamlit run app.py
```

Get a free key at [unirateapi.com](https://unirateapi.com).

## API reference

All functions use Streamlit's caching automatically — no extra decorators needed.

### `get_client(api_key=None, base_url=None)`

Returns the underlying `unirate.UnirateClient` singleton (cached via `@st.cache_resource`). Use this when you need direct access to Pro endpoints such as historical rates or time series.

```python
client = ur.get_client()
data = client.get_time_series("2025-01-01", "2025-01-31", base_currency="USD")
```

### `get_rate(from_currency="USD", to_currency=None)` → `float | dict`

Current exchange rate. Cached for **5 minutes**.

```python
rate = ur.get_rate("USD", "EUR")          # → 0.9214  (float)
all_rates = ur.get_rate("USD")            # → {"EUR": 0.92, "GBP": 0.79, ...}
```

### `convert(to_currency, amount=1.0, from_currency="USD")` → `float`

Convert an amount. Cached for **5 minutes**.

```python
eur = ur.convert("EUR", 250.0, "USD")     # → 230.35
```

### `list_currencies()` → `list[str]`

All supported currency codes. Cached for **1 hour**.

```python
codes = ur.list_currencies()              # → ["AED", "AFN", ..., "ZWL"]
```

### `get_vat_rates(country=None)` → `dict`

VAT rates for all countries or a single ISO-3166 country code. Cached for **24 hours**.

```python
all_vat = ur.get_vat_rates()
de_vat  = ur.get_vat_rates("DE")
```

## Error handling

All functions raise exceptions from `unirate.exceptions`:

| Exception | Cause |
|---|---|
| `AuthenticationError` | Missing or invalid API key |
| `RateLimitError` | Free-tier rate limit exceeded |
| `InvalidCurrencyError` | Unknown currency code |
| `APIError` | Other API error (check `.status_code`) |

```python
from unirate.exceptions import RateLimitError, AuthenticationError
import streamlit_unirate as ur

try:
    rate = ur.get_rate("USD", "EUR")
except AuthenticationError:
    st.error("Check your UNIRATE_API_KEY.")
except RateLimitError:
    st.warning("Rate limit hit — try again in a moment.")
```

## Related UniRate clients

<!-- unirate-ecosystem-footer:start -->
**Other UniRate integrations:**
[Python](https://github.com/UniRate-API/unirate-api-python) · [Node.js](https://github.com/UniRate-API/unirate-api-nodejs) · [Go](https://github.com/UniRate-API/unirate-api-go) · [Rust](https://github.com/UniRate-API/unirate-api-rust) · [Ruby](https://github.com/UniRate-API/unirate-api-ruby) · [PHP](https://github.com/UniRate-API/unirate-api-php) · [Java](https://github.com/UniRate-API/unirate-api-java) · [Swift](https://github.com/UniRate-API/unirate-api-swift) · [.NET](https://github.com/UniRate-API/unirate-api-dotnet) · [FastAPI](https://github.com/UniRate-API/fastapi-unirate) · [Flask](https://github.com/UniRate-API/flask-unirate) · [Django REST](https://github.com/UniRate-API/djangorestframework-unirate) · [Wagtail](https://github.com/UniRate-API/wagtail-unirate) · [Next.js](https://github.com/UniRate-API/next-unirate) · [Nuxt](https://github.com/UniRate-API/nuxt-unirate) · [SvelteKit](https://github.com/UniRate-API/sveltekit-unirate) · [React](https://github.com/UniRate-API/react-unirate) · [Vue](https://github.com/UniRate-API/vue-unirate) · [Angular](https://github.com/UniRate-API/angular-unirate) · [Remix](https://github.com/UniRate-API/remix-unirate) · [NestJS](https://github.com/UniRate-API/nestjs-unirate) · [LangChain (Python)](https://github.com/UniRate-API/langchain-unirate) · [LangChain.js](https://github.com/UniRate-API/langchain-js-unirate) · [Astro](https://github.com/UniRate-API/astro-unirate) · [Eleventy](https://github.com/UniRate-API/eleventy-unirate) · [Hugo](https://github.com/UniRate-API/hugo-unirate) · [Jekyll](https://github.com/UniRate-API/jekyll-unirate) · [Strapi](https://github.com/UniRate-API/strapi-plugin-unirate) · [Directus](https://github.com/UniRate-API/directus-extension-unirate) · [Medusa](https://github.com/UniRate-API/medusa-plugin-unirate) · [MCP Server](https://github.com/UniRate-API/unirate-mcp) · [CLI](https://github.com/UniRate-API/unirate-cli)
<!-- unirate-ecosystem-footer:end -->

## License

MIT — see [LICENSE](LICENSE).
