py-money

library0.5.0pypypi✓ verified 22d ago

py-money is a Python 3 library that provides `Money` and `Currency` classes for precise monetary calculations. It enforces correct decimal places for currencies, leverages Python's `Decimal` type to prevent floating-point errors, and supports basic arithmetic and logical operations for immutable money objects. The current version is 0.5.0, with releases historically focused on bug fixes and minor feature enhancements.

serialization payments

pip install py-money

github ↗package ↗

INSTALL

IMPORT

SIG · PY-MONEY

py-money

serializationpythonv0.5.0

Install

2.0s avg

Import

39ms

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 v0.5.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.042s · 50.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.0s · import 0.036s · 51MB

49MB installed

● package 49MB

Code

Verified usage

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

Money

✓ from money.money import Money

✗ from py_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

✗ from py_money 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

✗ from money.money import USD

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

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

Debug

Known issues

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

affects: All versions

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

affects: All versions

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

affects: All versions

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

affects: All versions

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

affects: <0.4.0

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

affects: <0.3.0

Errors

Common errors & fixes

TypeError: Cannot combine Money with different currencies

The `py-money` library strictly enforces that mathematical and logical operations (e.g., addition, subtraction, comparison) can only be performed between `Money` objects that share the exact same currency.

fix

Ensure both `Money` objects in an operation have the same `Currency`. If cross-currency operations are required, amounts must be manually converted to a common currency before performing the operation, as direct conversion is not supported by `py-money`.

ValueError: Invalid amount '3.678' for currency USD (expected 2 decimal places)

The `py-money` library enforces the correct number of decimal places for each currency. Providing an amount (as a string or `Decimal`) with more decimal places than allowed for the specified currency will raise this error.

fix

Ensure the monetary amount string or `Decimal` conforms to the standard decimal places for its respective currency (e.g., '123.45' for USD, '100' for JPY) before creating `Money` objects.

ImportError: cannot import name 'Money' from 'money'

The `Money` and `Currency` classes in `py-money` are located within specific submodules (`money.money` and `money.currency`), not directly under the top-level `money` package.

fix

Use explicit imports for the classes: `from money.money import Money` and `from money.currency import Currency`.

TypeError: ('%.18g' % amount) must be string, not float

While `py-money` leverages Python's `Decimal` type for precision, it strongly recommends providing monetary amounts as strings or `Decimal` objects to prevent floating-point inaccuracies. Directly passing a `float` can sometimes lead to type errors, especially if the float cannot be precisely converted or if the internal parsing expects a string.

fix

Always initialize `Money` objects with the amount as a string (e.g., `Money('10.50', Currency.USD)`) or a `Decimal` object (e.g., `Money(Decimal('10.50'), Currency.USD)`), rather than a `float`.

Upgrade

Version history

0.5.0latest on PyPI · released Jan 29, 2020

Audit

Dependencies

BabeloptionalUsed for locale-aware formatting of monetary amounts, though not a strict installation dependency. Version 0.4.0 expanded allowed Babel versions.

Agent activity

36 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/vimeo/py-money ↗

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