PyMoneyed

3.0 · active · verified Sun Apr 12

PyMoneyed provides robust Currency and Money classes for handling monetary values in Python. It is currently at version 3.0 and has a release cadence tied to significant feature additions and Python version support changes, ensuring compatibility and modern practices.

Warnings

breaking Python 3.6 is no longer supported with version 3.0. Previous versions (2.x) also dropped support for Python 2.7, 3.5, and PyPy 2.
Fix: Upgrade your Python environment to 3.7 or newer.
breaking The `moneyed.localization` module has been removed. Its functionality for locale-aware formatting is superseded by the `moneyed.l10n` module, which leverages Babel for CLDR-based formatting.
Fix: Migrate any usage of `moneyed.localization.format_money` to `moneyed.l10n.format_money`. Ensure Babel is installed for formatting capabilities (`pip install Babel`).
breaking Instantiating a `Money` object without providing a currency (e.g., `Money(100)`) now raises a `TypeError`. Previously, this would silently create an object with a made-up 'XYZ' currency.
Fix: Always provide a `Currency` object or a 3-letter ISO currency code string when creating a `Money` instance (e.g., `Money(100, USD)` or `Money(100, 'USD')`).
gotcha It is strongly recommended to avoid using Python's `float` type for the `amount` when instantiating `Money` objects, as floats do not convert losslessly to `Decimal` internally. This can lead to unexpected precision errors.
Fix: Always pass `Decimal` objects or string representations for monetary amounts to the `Money` constructor (e.g., `Money(Decimal('10.20'), USD)` or `Money('10.20', USD)`).
deprecated The `Currency.countries` property is deprecated in version 3.0, as currency country data is now sourced from Babel. `Currency.country_codes` has been added.
Fix: Use `Currency.country_codes` or other Babel-based methods for country-related currency information.
deprecated Setting and reading the `decimal_places_display` property on `Money` instances and using the `CURRENCY_DECIMAL_PLACES_DISPLAY` setting were deprecated in version 2.0.
Fix: These settings are discontinued in 3.0. For formatting, use `moneyed.l10n.format_money` with its locale-aware options, which relies on Babel's CLDR data for proper display.

Install

pip install py-moneyed Install stable release

Imports

Money
```
from moneyed import Money
```
Currency (pre-built)
```
from moneyed import USD
```
Use the 3-letter ISO code for common currencies (e.g., USD, EUR).
format_money
```
from moneyed.l10n import format_money
```
`moneyed.localization` was dropped in v2.0; use `moneyed.l10n` instead for Babel-based formatting.
list_all_currencies
```
from moneyed import list_all_currencies
```
Function to retrieve all available Currency objects.

Quickstart

This quickstart demonstrates how to create `Money` objects, perform basic arithmetic, and access their components. It highlights the importance of using `Decimal` or string for amounts to maintain precision and shows how `Money` enforces currency-aware operations.

from moneyed import Money, USD, EUR
from decimal import Decimal

# Instantiate Money with Decimal or string for precision
price_usd = Money(amount='99.99', currency=USD)
price_eur = Money(Decimal('75.50'), EUR)

print(f"USD Price: {price_usd}")
print(f"EUR Price: {price_eur}")

# Arithmetic operations (currency-aware)
total_price = price_usd + Money('10.01', USD)
print(f"Total USD: {total_price}")

# Invalid operations raise TypeError
try:
    invalid_sum = price_usd + price_eur
except TypeError as e:
    print(f"Error: {e}")

# Access components
print(f"Amount: {total_price.amount}, Currency Code: {total_price.currency.code}")

# Get amount in sub-units (e.g., cents for USD)
print(f"USD Price in cents: {price_usd.get_amount_in_sub_unit()}")

view raw JSON →