{"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":"en","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,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}