stapel-currencies

CI codecov PyPI

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 Jul 16, 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:
Newer release available (0.1.8)

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 Jul 16, 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.5.tar.gz (23.7 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.5-py3-none-any.whl (22.8 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: stapel_currencies-0.1.5.tar.gz
  • Upload date:
  • Size: 23.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for stapel_currencies-0.1.5.tar.gz
Algorithm Hash digest
SHA256 e4b38dc107e2c549e986b4d129e603a58d81306b7e5beb89e8edfea29c3567b5
MD5 4a08a5ecf50b0f8dd6507994bd30af1d
BLAKE2b-256 af05aebc7c330256ea8fba897f1d5b5b5a75c5aa27897a8d80f8b18264daa5a7

See more details on using hashes here.

Provenance

The following attestation bundles were made for stapel_currencies-0.1.5.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.5-py3-none-any.whl.

File metadata

File hashes

Hashes for stapel_currencies-0.1.5-py3-none-any.whl
Algorithm Hash digest
SHA256 c539b1112263f3f915d74abc34af23de12480b8da0b0b0601ef47fe3819bd637
MD5 890542bcaba3b4b3e56b70dc96c1020e
BLAKE2b-256 30737cfb14a54232d4363e6efb6c28eaa5c679d41cf40213b9e7ac906ef51124

See more details on using hashes here.

Provenance

The following attestation bundles were made for stapel_currencies-0.1.5-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

0.1.8

2 files

0.1.7

2 files

0.1.6

2 files

This release

0.1.5 This release

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