Money
The Money class is the core component of the library, representing a monetary amount with a specific currency.
- class moneyx.Money(amount, currency='USD', rounding='HALF_UP')[source]
Bases:
objectRepresents 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:
- __add__(other)[source]
Add two Money objects.
- Parameters:
other (
Money) – Money object to add- Return type:
- Returns:
A new Money object with the sum
- Raises:
ValueError – If currencies don’t match
- __sub__(other)[source]
Subtract Money object from this one.
- Parameters:
other (
Money) – Money object to subtract- Return type:
- Returns:
A new Money object with the difference
- Raises:
ValueError – If currencies don’t match
- __lt__(other)[source]
Compare if this Money object is less than another.
- Parameters:
other (
Money) – Another Money object to compare with- Return type:
- Returns:
True if this Money is less than other
- Raises:
ValueError – If currencies don’t match
- __gt__(other)[source]
Compare if this Money object is greater than another.
- Parameters:
other (
Money) – Another Money object to compare with- Return type:
- Returns:
True if this Money is greater than other
- Raises:
ValueError – If currencies don’t match
- __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 Decimalcurrency (
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
-
rounding_mode:
Literal['HALF_UP','HALF_DOWN','BANKERS','DOWN','UP','CEILING','FLOOR','HALF_ODD','HALF_TOWARDS_ZERO','HALF_AWAY_FROM_ZERO']
- add(other)[source]
Add another Money object to this one.
- Parameters:
other (
Money) – Money object to add- Return type:
- Returns:
A new Money object with the sum
- Raises:
ValueError – If currencies don’t match
- subtract(other)[source]
Subtract another Money object from this one.
- Parameters:
other (
Money) – Money object to subtract- Return type:
- Returns:
A new Money object with the difference
- 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:
- 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:
- Return type:
- Returns:
A new Money object in the target currency
Example
>>> Money("100.00", "USD").convert_to("EUR", 0.85) <Money 85.00 EUR>
- split_evenly(n)[source]
Split this money amount evenly among n recipients.
- Parameters:
n (
int) – Number of recipients- Return type:
- 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>]
- 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:
- Returns:
Locale-formatted string representation
Example
>>> Money("1234.56", "USD").format_locale("de_DE") '1.234,56 $'