stapel-currencies

CI codecov

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 "EUR" 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 European 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 6, 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 6, 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.2.tar.gz (23.3 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.2-py3-none-any.whl (22.2 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: stapel_currencies-0.1.2.tar.gz
  • Upload date:
  • Size: 23.3 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.2.tar.gz
Algorithm Hash digest
SHA256 865ed0535cef11d88ae6d950e43819baf926a1efa00a54a021e11532d83d19fc
MD5 799407883ab4a9ffd0e96ed7c3f81bc0
BLAKE2b-256 9af23670be6ad0cb55127e697cde1250e0c055737579fdaf07d0fb5f5b6294fe

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for stapel_currencies-0.1.2-py3-none-any.whl
Algorithm Hash digest
SHA256 ec6cbd3bc9d8ba714171cdb0d679a489a329a217e4a19d5d2d4a71b252d8fea7
MD5 676a18e06a051239d001b766190b4277
BLAKE2b-256 2621273a8a7bc9923d363289387ceb69f6d5470428862c7351c2dcc08bc7a8d4

See more details on using hashes here.

Provenance

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

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

This release

0.1.2 This release

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