angee.money.models

Money: the currency catalogue, dated rates, and conversion.

A :class:Currency is one ISO-4217 currency in a shared catalogue; a :class:CurrencyRate is one dated exchange rate for a currency expressed as units of that currency per one reference unit. The reference is ANGEE_MONEY_REFERENCE_CURRENCY — a required project setting with no shipped default: money bakes in no fiscal constant (a currency, country, or locale is a project fact, never a framework one), so a USD default was deliberately rejected in review. :func:reference_currency_code fails fast with :class:~django.core.exceptions.ImproperlyConfigured naming the setting when it is unset, and the addon's system check (apps.py) surfaces the same at manage.py check time.

Rounding vocabulary lives here too. :meth:Currency.round wraps :func:angee.base.numeric.quantize to the currency's exponent and resolves the mode from :class:angee.money.rounding.RoundingMode, defaulting to half_up unless a caller explicitly overrides it. :meth:Currency.convert crosses through the reference currency and returns the amount unrounded — the consumer rounds the converted amount at the point that owns the business policy.

REFERENCE_CURRENCY_SETTING

The project setting naming the ISO-4217 code every :class:CurrencyRate is relative to.

reference_currency_code

def reference_currency_code() -> str

Return the configured reference currency code, or fail fast.

The single owner of "which currency all rates are relative to" — read by the rate manager and the addon's system check alike. Raises :class:~django.core.exceptions.ImproperlyConfigured naming :data:REFERENCE_CURRENCY_SETTING when it is unset, because money ships no default (the project owns this choice).

CurrencyQuerySet

class CurrencyQuerySet(ArchiveQuerySet[Any], AngeeQuerySet[Any])

Archive read scopes layered over the REBAC-scoped currency queryset.

Currency

class Currency(ArchiveMixin, AngeeDataModel)

One ISO-4217 currency: its code, display name, symbol, and minor-unit exponent.

decimal_places is the currency's minor-unit exponent (2 for most, 0 for JPY/KRW, 3 for the Gulf dinars). :meth:round quantizes to it with the money-owned default mode unless a caller passes an explicit override.

Meta

class Meta()

Django model options for a currency.

__str__

def __str__() -> str

Return the ISO-4217 code for Django displays.

round

def round(amount: Decimal, mode: RoundingMode | str | None = None) -> Decimal

Return amount quantized to this currency's exponent.

mode may be a :class:angee.money.rounding.RoundingMode value or its stored string value. When omitted, the money addon's default rounding vocabulary applies.

convert

def convert(amount: Decimal,
            to_currency: Currency,
            on_date: Any = None) -> Decimal

Return amount re-expressed in to_currency at on_date rates.

Identity is a fast-path (same currency returns the amount untouched). Otherwise the amount crosses through the reference currency: rates are units per one reference unit, so amount in this currency is worth amount / rate_for(self) reference units, and amount * rate_for(to_currency) / rate_for(self) in the target. The result is not rounded — the consumer rounds per its own policy (:meth:round with its chosen mode). Raises :class:CurrencyRate.DoesNotExist when a needed rate is missing and :class:~django.core.exceptions.ImproperlyConfigured when the reference currency setting is unset.

CurrencyRateManager

class CurrencyRateManager(AngeeManager)

Resolves the effective exchange rate for a currency on a date.

rate_for

def rate_for(currency: models.Model, on_date: Any = None) -> Decimal

Return the latest rate for currency dated on or before on_date.

Decimal(1) for the reference currency itself (no row needed — it is the unit every other rate is quoted against). Otherwise the most recent :class:CurrencyRate with date <= on_date (today when on_date is omitted). Fails fast with :class:CurrencyRate.DoesNotExist when no rate exists on or before the date — a missing rate is a data gap the caller must see, never a silent zero.

CurrencyRate

class CurrencyRate(AngeeDataModel)

One dated exchange rate for a currency, quoted per one reference unit.

rate is units of currency per one ANGEE_MONEY_REFERENCE_CURRENCY unit on date; the (currency, date) pair is unique. Rows are global (not per-company) in v1 — per-company rates arrive later as an additive extends merge.

Meta

class Meta()

Django model options for a currency rate.

__str__

def __str__() -> str

Return a readable label for Django displays.

MoneyRole

The money/role anchor: its const admin arm resolves a platform admin as an effective money manager. See :func:angee.base.models.role_anchor.