{"id":4698,"library":"py-moneyed","title":"PyMoneyed","description":"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.","status":"active","version":"3.0","language":"python","source_language":"en","source_url":"http://github.com/py-moneyed/py-moneyed","tags":["money","currency","finance","decimal"],"install":[{"cmd":"pip install py-moneyed","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"Requires Python 3.7 or newer.","package":"python","optional":false}],"imports":[{"symbol":"Money","correct":"from moneyed import Money"},{"note":"Use the 3-letter ISO code for common currencies (e.g., USD, EUR).","symbol":"Currency (pre-built)","correct":"from moneyed import USD"},{"note":"`moneyed.localization` was dropped in v2.0; use `moneyed.l10n` instead for Babel-based formatting.","wrong":"from moneyed.localization import format_money","symbol":"format_money","correct":"from moneyed.l10n import format_money"},{"note":"Function to retrieve all available Currency objects.","symbol":"list_all_currencies","correct":"from moneyed import list_all_currencies"}],"quickstart":{"code":"from moneyed import Money, USD, EUR\nfrom decimal import Decimal\n\n# Instantiate Money with Decimal or string for precision\nprice_usd = Money(amount='99.99', currency=USD)\nprice_eur = Money(Decimal('75.50'), EUR)\n\nprint(f\"USD Price: {price_usd}\")\nprint(f\"EUR Price: {price_eur}\")\n\n# Arithmetic operations (currency-aware)\ntotal_price = price_usd + Money('10.01', USD)\nprint(f\"Total USD: {total_price}\")\n\n# Invalid operations raise TypeError\ntry:\n    invalid_sum = price_usd + price_eur\nexcept TypeError as e:\n    print(f\"Error: {e}\")\n\n# Access components\nprint(f\"Amount: {total_price.amount}, Currency Code: {total_price.currency.code}\")\n\n# Get amount in sub-units (e.g., cents for USD)\nprint(f\"USD Price in cents: {price_usd.get_amount_in_sub_unit()}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.7 or newer.","message":"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.","severity":"breaking","affected_versions":"3.0+, 2.0+"},{"fix":"Migrate any usage of `moneyed.localization.format_money` to `moneyed.l10n.format_money`. Ensure Babel is installed for formatting capabilities (`pip install Babel`).","message":"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.","severity":"breaking","affected_versions":"2.0+"},{"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')`).","message":"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.","severity":"breaking","affected_versions":"2.0+"},{"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)`).","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Use `Currency.country_codes` or other Babel-based methods for country-related currency information.","message":"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.","severity":"deprecated","affected_versions":"3.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.","message":"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.","severity":"deprecated","affected_versions":"2.0+"}],"env_vars":null,"search_vec":"'3.0':20 'addit':30 'cadenc':25 'chang':35 'class':8 'compat':37 'currenc':5,42 'current':17 'decim':44 'ensur':36 'featur':29 'financ':43 'handl':10 'modern':39 'monetari':11 'money':7,41 'practic':40 'provid':3 'pymoney':1,2 'python':14,32 'releas':24 'robust':4 'signific':28 'support':34 'tie':26 'valu':12 'version':19,33","created_at":"2026-04-12T14:03:47.484588+00:00","updated_at":"2026-04-16T18:17:20.897800+00:00","problems":[{"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.","cause":"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.","error":"TypeError: unsupported operand type(s) for +: 'Money' and 'int'"},{"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.","cause":"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.","error":"TypeError: Cannot add or subtract two Money instances with different currencies."},{"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`).","cause":"The `DEFAULT_CURRENCY` constant was removed in `py-moneyed` version 2.0 (and subsequently version 3.0), making it unavailable for import.","error":"ImportError: cannot import name 'DEFAULT_CURRENCY' from 'moneyed'"},{"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')`.","cause":"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.","error":"TypeError: Money() missing 1 required positional argument: 'currency'"},{"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.","cause":"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.","error":"ValueError: invalid literal for Decimal()"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"http://github.com/py-moneyed/py-moneyed","docs":"https://py-moneyed.readthedocs.io/en/latest/","changelog":null,"pypi":"https://pypi.org/project/py-moneyed/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","data","payments"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}