py-moneyed

library3.0pypypi✓ verified 22d ago

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.

serialization data payments

pip install py-moneyed

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · PY-MONEYED

py-moneyed

serializationpythonv3.0

Install

2.1s avg

Import

62ms

Disk

49MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.064s · 51.1MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.1s · import 0.060s · 52MB

49MB installed

● package 49MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

✗ from moneyed.localization 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.

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()}")

Debug

Known issues

breakingPython 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.

affects: 3.0+, 2.0+

breakingThe `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`).

affects: 2.0+

breakingInstantiating 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')`).

affects: 2.0+

gotchaIt 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)`).

affects: All

deprecatedThe `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.

affects: 3.0+

deprecatedSetting 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.

affects: 2.0+

Errors

Common errors & fixes

TypeError: unsupported operand type(s) for +: 'Money' and 'int'

Py-moneyed's Money objects do not implicitly convert or allow direct arithmetic operations with standard Python numeric types (like int or float) or strings to maintain strict monetary integrity.

fix

Convert the non-Money operand to a Decimal or another Money instance of the same currency before performing the operation. For example, `money_object + Money(Decimal('5'), USD)` or `money_object.amount + Decimal('5')` if you only need the amount.

TypeError: Cannot add or subtract two Money instances with different currencies.

Py-moneyed strictly enforces that arithmetic and comparison operations can only be performed between Money objects of the same currency to prevent accidental mixing of different monetary values.

fix

Ensure both Money instances have the same Currency before performing the operation. If currency conversion is intended, explicitly convert one of the amounts using a dedicated exchange rate mechanism (not provided by py-moneyed) before creating a new Money object.

ImportError: cannot import name 'DEFAULT_CURRENCY' from 'moneyed'

The `DEFAULT_CURRENCY` constant was removed in `py-moneyed` version 2.0 (and subsequently version 3.0), making it unavailable for import.

fix

Update your code to explicitly provide a `Currency` object when instantiating `Money`, or import and use pre-defined currency constants like `USD`, `EUR`, `GBP` directly from the `moneyed` module (e.g., `from moneyed import Money, USD`).

TypeError: Money() missing 1 required positional argument: 'currency'

As of `py-moneyed` version 3.0, the `currency` argument is mandatory when instantiating a `Money` object. Earlier versions might have defaulted to a placeholder 'XYZ' currency if omitted, but this behavior was changed to a `TypeError` to prevent unexpected issues.

fix

Always provide a valid `Currency` object (e.g., `USD`, `EUR` imported from `moneyed`) or a three-letter ISO currency code string to the `Money` constructor. For example, `Money('10.00', USD)` or `Money(amount='10.00', currency='USD')`.

ValueError: invalid literal for Decimal()

The amount provided to the `Money` constructor, especially if it's a string, does not represent a valid number or has incorrect precision for the specified currency, leading to an error during internal conversion to a `Decimal` object.

fix

Ensure the amount argument is a valid numeric string (e.g., '10.50'), an `int`, or a `Decimal` instance. Avoid using `float` directly due to potential precision issues, and ensure the string format matches what `decimal.Decimal` expects.

Upgrade

Version history

3.0latest on PyPI · released Nov 27, 2022

Audit

Dependencies

pythonrequiredRequires Python 3.7 or newer.

Agent activity

37 hits · last 30 days

node

OpenAI (training)

Resources

githubhttp://github.com/py-moneyed/py-moneyed ↗

packagehttps://pypi.org/project/py-moneyed/ ↗

docshttps://py-moneyed.readthedocs.io/en/latest/ ↗