py-money

Warnings

• breaking Direct currency conversion between different `Money` objects is explicitly not supported by design. Attempting to add or subtract `Money` objects of different currencies will raise an error.
  Fix: Manually convert amounts to a common currency before performing operations, or ensure all operations are between `Money` objects of the same currency.
• gotcha Instantiating `Money` with floating-point numbers can lead to precision issues. Always use strings or `Decimal` objects for monetary amounts to guarantee accuracy.
  Fix: Initialize `Money` objects with `Money('100.50', USD)` or `Money(Decimal('100.50'), USD)` instead of `Money(100.50, USD)`.
• gotcha The library enforces the correct number of decimal places for each currency. Providing an amount with too many decimal places (e.g., '3.678 USD') will raise an error.
  Fix: Ensure monetary amounts conform to the standard decimal places for their respective currencies (e.g., 2 for USD, 0 for JPY) before creating `Money` objects.
• gotcha Rounding is performed after *each* multiplication or division operation. This can lead to different results compared to calculating with higher precision and rounding only at the end of a series of operations.
  Fix: Be mindful of the order of operations and simplify expressions where intermediate rounding might be problematic. For critical financial calculations, evaluate if this rounding behavior meets specific accounting requirements.
• deprecated Older versions of `babel` might have caused compatibility issues. Version `0.4.0` was released to allow `py-money` to work with a broader range of `babel` versions (`>= 2.4.0` and `< 3.0`).
  Fix: Ensure your `babel` dependency, if used for formatting, is within the compatible range, or upgrade `py-money` to `0.4.0` or newer.
• gotcha Prior to v0.3.0, there was no direct support for creating `Money` objects from or converting to currency subunits. This functionality was introduced in v0.3.0.
  Fix: Upgrade to `py-money` v0.3.0 or later to utilize the `Money.from_sub_units()` method and the `.sub_units` property.

Install

• pip install py-money Install latest version

Imports

• Money

  from money.money import Money

  The primary Money class resides within the 'money.money' module path, not directly under the top-level 'py_money' package name.
• Currency

  from money.currency import Currency

  The Currency class is found within the 'money.currency' module path, not directly under the top-level 'py_money' package name.
• USD

  from money.currency import USD

  Pre-defined ISO 4217 currencies like USD are available from `money.currency`, not `money.money`.

Quickstart

This quickstart demonstrates how to create `Money` objects, perform basic arithmetic operations, and work with currency subunits. It highlights the importance of using the correct import paths and shows how to access the amount and currency code.

from money.money import Money
from money.currency import USD, EUR

# Create Money objects
price_usd = Money('100.50', USD)
price_eur = Money('50.25', EUR)

# Accessing amount and currency
print(f"USD Price: {price_usd.amount} {price_usd.currency.code}") # Expected: USD Price: 100.50 USD

# Basic arithmetic (same currency)
total_usd = price_usd + Money('9.50', USD)
print(f"Total USD: {total_usd}") # Expected: Total USD: 110.00 USD

# Subtraction
remaining_usd = price_usd - Money('20.00', USD)
print(f"Remaining USD: {remaining_usd}") # Expected: Remaining USD: 80.50 USD

# Multiplication
taxed_price = price_usd * 1.05
print(f"Taxed USD: {taxed_price}") # Expected: Taxed USD: 105.53 USD (due to rounding)

# Division
split_price = price_usd / 2
print(f"Split USD: {split_price}") # Expected: Split USD: 50.25 USD

# Create from subunits (v0.3.0+)
# e.g., 12345 cents for USD
sub_unit_money = Money.from_sub_units(12345, USD)
print(f"From subunits USD: {sub_unit_money}") # Expected: From subunits USD: 123.45 USD
print(f"To subunits USD: {sub_unit_money.sub_units}") # Expected: To subunits USD: 12345