Provides Currency and Money classes for use in your Python code.
Project description
Overview
The need to represent instances of money frequently arises in software development, particularly any financial/economics software. To address that need, the py-moneyed package provides the classes of Money and Currency, at a level more useful than just using Python’s Decimal class, or ($DEITY forbid) the float primitive. The package is meant to be stand-alone and easy to either use directly, or subclass further. py-moneyed is BSD-licensed.
Some of the py-moneyed code was first derived from python-money available via this URL: http://code.google.com/p/python-money/ Because that Google Code version has been inactive since May 2008, I forked it and modified it for my needs in 2010. Compared to python-money, major changes here in py-moneyed include separating it from Django usage, tightening types handling in operators, a complete suite of unit tests, PEP8 adherence, providing a setup.py, and local currency formatting/display.
Usage
On to the code! The Money class is instantiated with:
An amount which can be of type int, string, float, or Decimal. It will be converted to a Decimal internally. Therefore, it is best to avoid float objects, since they do not convert losslessly to Decimal.
A currency, which usually is specified by the three-capital-letters ISO currency code, e.g. USD, EUR, CNY, and so on. It will be converted to a Currency object.
For example,
from moneyed import Money
sale_price_today = Money(amount='99.99', currency='USD')
You then use Money instances as a normal number. The Money class provides operators with type checking, matching currency checking, and sensible dimensional behavior, e.g. you cannot multiply two Money instances, nor can you add a Money instance to a non-Money number; dividing a Money instance by another results in a Decimal value, etc.
The Currency class is provided with a complete dictionary of ISO 4217 currencies data, each key (e.g. ‘USD’) mapping to a Currency instance with ISO numeric code, canonical name in English, and countries using the currency. Thanks to the python-money developers for their (possibly tedious) data-entry of the ISO codes!
All of these are available as pre-built Currency objects in the moneyed module.
You can also pass in the arguments to Money as positional arguments. So you can also write:
>>> from moneyed import Money, USD
>>> price = Money('19.50', USD)
>>> price
19 USD
>>> price.amount
Decimal('19.50')
>>> price.currency
USD
>>> price.currency.code
'USD'
Formatting
You can print Money object as follows:
>>> from moneyed.localization import format_money
>>> format_money(Money(10, USD), locale='en_US')
'$10.00'
Testing
Unit-tests have been provided, and can be run with tox (recommended) or just py.test.
If you don’t have tox installed on your system, it’s a modern Python tool to automate running tests and deployment; install it to your global Python environment with:
sudo pip install tox
Then you can activate a virtualenv (any will do - by design tox will not run from your globally-installed python), cd to the py-moneyed source directory then run the tests at the shell:
cd where/py-moneyed-source/is tox
If you do not have all versions of Python that are used in testing, you can use pyenv. After installing pyenv, install the additional plugin pyenv-implict.
The py-moneyed package is tested against Python 2.6, 2.7, 3.2, 3.3, 3.4, 3.5, and PyPy 2.1.
Future
Future versions of py-moneyed may provide currency conversions or other capabilities, dependent on feedback and usage.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for py_moneyed-0.7.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0c5dc04f77f1e0a123df051cc6ddc79267a48c612cb2d3dcfe7eb88cfc395bf9 |
|
MD5 | b5800fb689f2df0c9c3315904aec3340 |
|
BLAKE2b-256 | 4c2c3c57645cddb0e64aac10749829a843eb5e3aab8e067e2c870d98c38a7947 |