Metadata-Version: 2.4
Name: stapel-currencies
Version: 0.1.9
Summary: Currencies and exchange rates for the Stapel framework
License: MIT
Project-URL: Homepage, https://github.com/usestapel/stapel-currencies
Project-URL: Repository, https://github.com/usestapel/stapel-currencies
Project-URL: Documentation, https://github.com/usestapel/stapel-currencies#readme
Project-URL: Changelog, https://github.com/usestapel/stapel-currencies/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/usestapel/stapel-currencies/issues
Keywords: django,stapel,currencies
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: stapel-core<1.0,>=0.10
Requires-Dist: celery>=5
Requires-Dist: requests>=2.28
Provides-Extra: all
Dynamic: license-file

<!-- Generated by stapel-readme from docs/readme.md + docs/*.json. Do not edit this file; edit docs/readme.md and re-run `make readme`. -->

# stapel-currencies

[![CI](https://img.shields.io/github/actions/workflow/status/usestapel/stapel-currencies/ci.yml?branch=main&logo=github&label=CI)](https://github.com/usestapel/stapel-currencies/actions/workflows/ci.yml?query=branch%3Amain)
[![coverage](https://img.shields.io/codecov/c/github/usestapel/stapel-currencies?branch=main&logo=codecov&label=coverage)](https://app.codecov.io/gh/usestapel/stapel-currencies)
[![pypi](https://img.shields.io/pypi/v/stapel-currencies?logo=pypi&logoColor=white&label=pypi)](https://pypi.org/project/stapel-currencies/)
[![downloads](https://static.pepy.tech/badge/stapel-currencies/month)](https://pepy.tech/project/stapel-currencies)
[![python](https://img.shields.io/pypi/pyversions/stapel-currencies?logo=python&logoColor=white)](https://pypi.org/project/stapel-currencies/)
[![license](https://img.shields.io/github/license/usestapel/stapel-currencies)](https://github.com/usestapel/stapel-currencies/blob/main/LICENSE)
[![llms.txt](https://img.shields.io/badge/llms.txt-blue)](https://github.com/usestapel/stapel-currencies/blob/main/docs/llms.txt)

> Currencies and exchange rates: a Currency catalog keyed by ISO 4217 code with Decimal rates relative to a configurable base currency, cross-rate conversion (convert()) exposed as a comm Function, a pluggable rate-provider seam (ECB by default), a public read-only HTTP API, and a Celery task / management commands to refresh rates.

Part of the [Stapel framework](https://github.com/usestapel) — composable Django apps that deploy as a monolith or as microservices without changing module code.

## Install

```bash
pip install stapel-currencies
```

## At a glance

| Fact | Value |
|---|---|
| Version | `0.1.9` |
| Python | `>=3.11` (3.11, 3.12, 3.13, 3.14) |
| HTTP operations | 2 |
| Config axes | 2 |
| Usage surface | 3 |
| Extension points | 2 |
| Error codes | 45 |
| Fleet dependencies | [`stapel-core`](https://github.com/usestapel/stapel-core) |

## Documentation

[OpenAPI](https://github.com/usestapel/stapel-currencies/blob/main/docs/schema.json) · [capabilities.json](https://github.com/usestapel/stapel-currencies/blob/main/docs/capabilities.json) · [llms.txt (for agents)](https://github.com/usestapel/stapel-currencies/blob/main/docs/llms.txt)

## Quick start

```python
# settings.py
INSTALLED_APPS = [
    # ...
    "stapel_currencies",
]

# urls.py
path("currencies/", include("stapel_currencies.urls"))
```

Seed the catalog and pull live rates:

```bash
python manage.py migrate
python manage.py load_default_currencies
python manage.py update_exchange_rates          # ECB by default; --dry-run supported
```

Or schedule the Celery task:

```python
CELERY_BEAT_SCHEDULE = {
    "update-exchange-rates": {
        "task": "stapel_currencies.tasks.update_exchange_rates",
        "schedule": crontab(hour=16, minute=30),  # ECB publishes ~16:00 CET
    },
}
```

## Converting

```python
from decimal import Decimal
from stapel_core.comm import call

call("currencies.convert", {
    "amount": "100.00",          # decimal strings on the wire
    "from_currency": "USD",
    "to_currency": "GBP",        # non-base pairs go via the base cross rate
})
# -> {"amount": "78.70"}

# In-process, same math:
from stapel_currencies import convert
convert(Decimal("100"), "USD", "GBP")  # Decimal("78.70")
```

## Settings

All configuration lives in the `STAPEL_CURRENCIES` namespace (dict setting, flat
setting, or env var — resolved lazily):

| Key | Default | Meaning |
|---|---|---|
| `BASE_CURRENCY` | `"USD"` | ISO code all stored rates are relative to (base = 1). |
| `RATE_PROVIDER` | `"stapel_currencies.providers.ECBRateProvider"` | Dotted path to a `RateProvider` subclass — the rate-source seam. |
| `DEFAULT_CURRENCIES` | 16 major world currencies | Seed list for `load_default_currencies`. |
| `CONVERSION_DECIMAL_PLACES` | `2` | Quantization of conversion results (ROUND_HALF_UP). |

## HTTP API

Read-only (writes happen via the Django admin and the rate-update task):

| Route | Meaning |
|---|---|
| `GET currencies/api/` | Active currencies (code, display_name, value, symbol, is_active). |
| `GET currencies/api/<code>/` | One currency by ISO code. |

## comm surface

| Kind | Name | Contract |
|---|---|---|
| Function | `currencies.convert` | `{"amount": "<decimal str>", "from_currency", "to_currency"}` -> `{"amount": "<decimal str>"}` — [schema](https://github.com/usestapel/stapel-currencies/blob/main/schemas/functions/currencies.convert.json) |

## Extension points

See [MODULE.md](https://github.com/usestapel/stapel-currencies/blob/main/MODULE.md)
— the agent-facing map of every fork-free seam (settings, the `RateProvider`
ABC with a custom-provider recipe, serializer seam, comm surface, system
checks).

## Development

```bash
pip install -e . && pip install pytest pytest-django pytest-cov ruff jsonschema
./setup-hooks.sh
pytest tests/
```

## License

MIT — see [LICENSE](https://github.com/usestapel/stapel-currencies/blob/main/LICENSE).

---

<sub>This page is assembled by `stapel-readme` from `docs/readme.md` plus the contract artifacts in `docs/`. Edit the prose in `docs/readme.md`; the badges, facts and links above and below it are generated — do not hand-edit `README.md`.</sub>
