stapel-currencies

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 — composable Django apps that deploy as a monolith or as microservices without changing module code.

Install

pip install stapel-currencies

At a glance

Documentation

OpenAPI · capabilities.json · llms.txt (for agents)

Quick start

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

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

Seed the catalog and pull live rates:

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:

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

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):

HTTP API

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

comm surface

Extension points

See 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

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

License

MIT — see LICENSE.

_{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.}