API Reference

This section contains the complete API reference for all public modules and classes in moneyx.

Core Components

class moneyx.Currency(code, symbol, decimals, name=None, number=None, countries=None)[source]

Bases: object

Parameters:

code (str)
symbol (str)
decimals (int)
name (str | None)
number (str | None)
countries (List[str] | None)

classmethod get(code)[source]

Return type:: Currency
Parameters:: code (str)

classmethod get_by_country(country_name)[source]

Get all currencies used in a specific country.

Return type:: List[Currency]
Parameters:: country_name (str)

classmethod get_by_number(number)[source]

Get a currency by its numeric code.

Return type:: Currency
Parameters:: number (str)

exception moneyx.InvalidCurrencyError[source]

Bases: MoneyError

Unknown or invalid currency.

class moneyx.Money(amount, currency='USD', rounding='HALF_UP')[source]

Bases: object

Represents a monetary amount in a specific currency.

The Money class handles all money-related operations with precision, ensuring correct decimal handling and currency validation.

Parameters:

amount (Decimal)
currency (Currency)
rounding (Literal['HALF_UP', 'HALF_DOWN', 'BANKERS', 'DOWN', 'UP', 'CEILING', 'FLOOR', 'HALF_ODD', 'HALF_TOWARDS_ZERO', 'HALF_AWAY_FROM_ZERO'])

__init__(amount, currency='USD', rounding='HALF_UP')[source]

Initialize a Money object.

Parameters:

amount (Union[Decimal, str, int, float]) – The monetary amount as a string, int, float, or Decimal
currency (str) – The ISO currency code (e.g., “USD”, “EUR”)
rounding (Literal['HALF_UP', 'HALF_DOWN', 'BANKERS', 'DOWN', 'UP', 'CEILING', 'FLOOR', 'HALF_ODD', 'HALF_TOWARDS_ZERO', 'HALF_AWAY_FROM_ZERO']) – The rounding mode to use for calculations

Raises:

InvalidCurrencyError – If the currency code is not valid
PrecisionError – If the amount has more decimal places than the currency allows

Return type:

None

add(other)[source]

Add another Money object to this one.

Parameters:: other (Money) – Money object to add
Return type:: Money
Returns:: A new Money object with the sum
Raises:: ValueError – If currencies don’t match

allocate(ratios)[source]

Allocate this money amount according to a list of ratios.

Parameters:: ratios (List[Union[int, float, Decimal]]) – List of ratio values for allocation
Return type:: List[Money]
Returns:: List of Money objects with allocated amounts

Example

>>> Money("100.00", "USD").allocate([1, 1, 1])
[<Money 33.34 USD>, <Money 33.33 USD>, <Money 33.33 USD>]

convert_to(target_currency_code, rate)[source]

Convert this money amount to another currency.

Parameters:

target_currency_code (str) – ISO code of the target currency
rate (float) – Conversion rate from this currency to target

Return type:

Money

Returns:

A new Money object in the target currency

Example

>>> Money("100.00", "USD").convert_to("EUR", 0.85)
<Money 85.00 EUR>

extract_tax(tax_rate_percent)[source]

Calculate base amount and tax from a tax-inclusive amount.

Parameters:: tax_rate_percent (float) – The tax rate as a percentage (e.g., 10 for 10%)
Return type:: Dict[str, Money]
Returns:: Dictionary with “base” and “tax” components

format(locale='en-US')[source]

Format the money amount with currency symbol.

Parameters:: locale (str) – The locale to use for formatting
Return type:: str
Returns:: Formatted string representation

format_locale(locale='en_US')[source]

Format the money amount using locale-specific formatting.

Parameters:: locale (str) – The locale to use for formatting
Return type:: str
Returns:: Locale-formatted string representation

Example

>>> Money("1234.56", "USD").format_locale("de_DE")
'1.234,56 $'

classmethod from_dict(data)[source]

Create a Money object from a dictionary.

Parameters:: data (Dict[str, Any]) – Dictionary with amount, currency, and optional rounding
Return type:: TypeVar(T, bound= Money)
Returns:: New Money object

classmethod from_json(json_str)[source]

Create a Money object from a JSON string.

Parameters:: json_str (str) – JSON string representation
Return type:: TypeVar(T, bound= Money)
Returns:: New Money object

multiply(multiplier)[source]

Multiply this Money object by a number.

Parameters:: multiplier (Union[int, float, Decimal]) – Number to multiply by
Return type:: Money
Returns:: A new Money object with the product

split_evenly(n)[source]

Split this money amount evenly among n recipients.

Parameters:: n (int) – Number of recipients
Return type:: List[Money]
Returns:: List of Money objects with evenly split amounts
Raises:: ValueError – If n is less than 1

Example

>>> Money("100.00", "USD").split_evenly(3)
[<Money 33.34 USD>, <Money 33.33 USD>, <Money 33.33 USD>]

subtract(other)[source]

Subtract another Money object from this one.

Parameters:: other (Money) – Money object to subtract
Return type:: Money
Returns:: A new Money object with the difference
Raises:: ValueError – If currencies don’t match

to_dict()[source]

Convert Money object to a dictionary.

Return type:: Dict[str, str]
Returns:: Dictionary with amount, currency, and rounding mode

to_json(indent=None)[source]

Convert Money object to a JSON string.

Parameters:: indent (Optional[int]) – Optional indentation for pretty-printing
Return type:: str
Returns:: JSON string representation

with_tax(tax_rate_percent)[source]

Add tax to this money amount.

Parameters:: tax_rate_percent (float) – The tax rate as a percentage (e.g., 10 for 10%)
Return type:: Money
Returns:: A new Money object with tax included

amount: Decimal

currency: Currency

rounding_mode: Literal['HALF_UP', 'HALF_DOWN', 'BANKERS', 'DOWN', 'UP', 'CEILING', 'FLOOR', 'HALF_ODD', 'HALF_TOWARDS_ZERO', 'HALF_AWAY_FROM_ZERO']

exception moneyx.MoneyError[source]

Bases: Exception

General error for the moneyx library.

exception moneyx.PrecisionError[source]

Bases: MoneyError

More decimal places than allowed for the currency.

class moneyx.RoundingMode[source]

Bases: object

Constants for various rounding modes.

BANKERS: Literal['HALF_UP', 'HALF_DOWN', 'BANKERS', 'DOWN', 'UP', 'CEILING', 'FLOOR', 'HALF_ODD', 'HALF_TOWARDS_ZERO', 'HALF_AWAY_FROM_ZERO'] = 'BANKERS'

CEILING: Literal['HALF_UP', 'HALF_DOWN', 'BANKERS', 'DOWN', 'UP', 'CEILING', 'FLOOR', 'HALF_ODD', 'HALF_TOWARDS_ZERO', 'HALF_AWAY_FROM_ZERO'] = 'CEILING'

DOWN: Literal['HALF_UP', 'HALF_DOWN', 'BANKERS', 'DOWN', 'UP', 'CEILING', 'FLOOR', 'HALF_ODD', 'HALF_TOWARDS_ZERO', 'HALF_AWAY_FROM_ZERO'] = 'DOWN'

FLOOR: Literal['HALF_UP', 'HALF_DOWN', 'BANKERS', 'DOWN', 'UP', 'CEILING', 'FLOOR', 'HALF_ODD', 'HALF_TOWARDS_ZERO', 'HALF_AWAY_FROM_ZERO'] = 'FLOOR'

HALF_AWAY_FROM_ZERO: Literal['HALF_UP', 'HALF_DOWN', 'BANKERS', 'DOWN', 'UP', 'CEILING', 'FLOOR', 'HALF_ODD', 'HALF_TOWARDS_ZERO', 'HALF_AWAY_FROM_ZERO'] = 'HALF_AWAY_FROM_ZERO'

HALF_DOWN: Literal['HALF_UP', 'HALF_DOWN', 'BANKERS', 'DOWN', 'UP', 'CEILING', 'FLOOR', 'HALF_ODD', 'HALF_TOWARDS_ZERO', 'HALF_AWAY_FROM_ZERO'] = 'HALF_DOWN'

HALF_EVEN: Literal['HALF_UP', 'HALF_DOWN', 'BANKERS', 'DOWN', 'UP', 'CEILING', 'FLOOR', 'HALF_ODD', 'HALF_TOWARDS_ZERO', 'HALF_AWAY_FROM_ZERO'] = 'BANKERS'

HALF_ODD: Literal['HALF_UP', 'HALF_DOWN', 'BANKERS', 'DOWN', 'UP', 'CEILING', 'FLOOR', 'HALF_ODD', 'HALF_TOWARDS_ZERO', 'HALF_AWAY_FROM_ZERO'] = 'HALF_ODD'

HALF_TOWARDS_ZERO: Literal['HALF_UP', 'HALF_DOWN', 'BANKERS', 'DOWN', 'UP', 'CEILING', 'FLOOR', 'HALF_ODD', 'HALF_TOWARDS_ZERO', 'HALF_AWAY_FROM_ZERO'] = 'HALF_TOWARDS_ZERO'

HALF_UP: Literal['HALF_UP', 'HALF_DOWN', 'BANKERS', 'DOWN', 'UP', 'CEILING', 'FLOOR', 'HALF_ODD', 'HALF_TOWARDS_ZERO', 'HALF_AWAY_FROM_ZERO'] = 'HALF_UP'

UP: Literal['HALF_UP', 'HALF_DOWN', 'BANKERS', 'DOWN', 'UP', 'CEILING', 'FLOOR', 'HALF_ODD', 'HALF_TOWARDS_ZERO', 'HALF_AWAY_FROM_ZERO'] = 'UP'

exception moneyx.SerializationError[source]

Bases: MoneyError

Error raised when serialization or deserialization fails.