Metadata-Version: 2.4
Name: cbar-currency-rates
Version: 2.0.0
Summary: Python client for official Central Bank of Azerbaijan currency rates.
Home-page: https://github.com/zmmmdf/cbar-currency-rates
Author: Ziya Mammadov
Author-email: ziyamm08@gmail.com
License: MIT
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.20
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# CBAR Currency Rates

Python client for the official currency rates published by the Central Bank of the
Republic of Azerbaijan.

CBAR publishes official AZN exchange-rate bulletins as dated XML files:

```text
https://cbar.az/currencies/DD.MM.YYYY.xml
```

When a date is not provided, this package fetches the latest official bulletin
for the current Baku date and falls back through recent dates if CBAR has not
published a dated XML file yet.

## Installation

```bash
pip install cbar-currency-rates
```

## Quick Start

```python
from cbar_currency_rates import CBARClient

cbar = CBARClient()

# Simple backwards-compatible shape: {"USD": 1.7, "EUR": 1.9362, ...}
rates = cbar.get_rates()
print(rates["USD"])

# Fetch selected currencies only
selected = cbar.get_rates(codes=["USD", "EUR", "TRY"])
print(selected)
```

## Rich Rate Metadata

```python
from cbar_currency_rates import CBARClient

cbar = CBARClient()
table = cbar.latest(codes=["USD", "JPY"])

usd = table.require("USD")
jpy = table.require("JPY")

print(table.date)          # Official bulletin date
print(table.source_url)    # CBAR XML URL
print(usd.value)           # Decimal("1.7000")
print(jpy.nominal_text)    # "100"
print(jpy.rate)            # AZN value for one JPY
```

CBAR lists some currencies by nominal amounts, such as `100 JPY` or `100 RUB`.
`CurrencyRate.value` keeps CBAR's official value for the listed nominal, while
`CurrencyRate.rate` normalizes it to one unit.

## Historical Dates

```python
from datetime import date
from cbar_currency_rates import CBARClient

cbar = CBARClient()
rates = cbar.get_rates(date=date(2024, 5, 27))
same_rates = cbar.get_rates(date="27.05.2024")
```

Accepted date inputs:

- `datetime.date`
- `datetime.datetime`
- `YYYY-MM-DD`
- `DD.MM.YYYY`
- `DD/MM/YYYY`

## Convert Amounts

```python
from cbar_currency_rates import CBARClient

cbar = CBARClient()

azn = cbar.convert(100, "USD", "AZN")
eur = cbar.convert(100, "USD", "EUR")
```

`convert()` returns a `Decimal` and uses CBAR's official AZN cross-rates.

## Bank Metals

Currency methods exclude bank metals by default. Enable them when needed:

```python
from cbar_currency_rates import CBARClient

cbar = CBARClient()
table = cbar.latest(include_metals=True)

gold = table.require("XAU")
print(gold.value)
```

## Compatibility

The old import style still works:

```python
from cbar_currency_rates.rates import CBARRates

cbar = CBARRates()
print(cbar.get_rates())
```

## Development

```bash
pip install -r requirements.txt
pip install pytest
pytest
```

