stapel-currencies

CI coverage pypi downloads python license llms.txt

Currencies and exchange rates — configurable base currency, pluggable rate providers (ECB by default), cross-rate conversion as a comm Function

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

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

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

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

Project links

Data verified by PyPI on Aug 2, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for ucsoftworks from gravatar.com ucsoftworks

GitHub Statistics

Data verified by PyPI on Aug 2, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.11

Provides Extra

all

Tags

django stapel currencies

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

stapel_currencies-0.1.8.tar.gz (26.6 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

stapel_currencies-0.1.8-py3-none-any.whl (26.4 kB view details)

Uploaded Python 3

File details

Details for the file stapel_currencies-0.1.8.tar.gz.

File metadata

  • Download URL: stapel_currencies-0.1.8.tar.gz
  • Upload date:
  • Size: 26.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for stapel_currencies-0.1.8.tar.gz
Algorithm Hash digest
SHA256 7c4aa9aa9495e759924a8dfbc218d32f83ff01edca4c102fdb1bf4748c0c97c2
MD5 c8b87deb5b6bb7ac5993e1961622f778
BLAKE2b-256 6264a3a30afc7823aeca3adc7bff6b33b8ee63a3c8f4aa8606a1f6ed742725ea

See more details on using hashes here.

Provenance

The following attestation bundles were made for stapel_currencies-0.1.8.tar.gz:

Publisher: publish.yml on usestapel/stapel-currencies

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file stapel_currencies-0.1.8-py3-none-any.whl.

File metadata

File hashes

Hashes for stapel_currencies-0.1.8-py3-none-any.whl
Algorithm Hash digest
SHA256 8850512b4acbbfb40ab03800d8d5a2bdd4b5755a408535f168b34c36ad0dc410
MD5 48a603089a1f97aa7bf2860d7ece0859
BLAKE2b-256 57aa4e139b9defee9dc9c5dafaf874cfc86152fe8be1634d236ccbadc2bd8e41

See more details on using hashes here.

Provenance

The following attestation bundles were made for stapel_currencies-0.1.8-py3-none-any.whl:

Publisher: publish.yml on usestapel/stapel-currencies

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.1.8 This release

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

0.1.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page