Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/vimeo/py-money

Money class for Python 3
https://github.com/vimeo/py-money

Last synced: 18 days ago
JSON representation

Money class for Python 3

Awesome Lists containing this project

README 

        
========

py-money

========



.. image:: https://badge.fury.io/py/py-money.svg

    :target: https://badge.fury.io/py/py-money

    :alt: Latest PyPI version



Money class for Python 3. Unlike other Python money classes, this class enforces that all monetary amounts are represented with the correct number of decimal places for the currency. For example, 3.678 USD is invalid, as is 5.5 JPY.



Installation

============



Install the latest release with:



::



    pip install py-money



Usage

=====



A Money object can be created with an amount (specified as a string) and a currency from the Currency class.



.. code:: python



    >>> from money.money import Money

    >>> from money.currency import Currency

    >>> m = Money('9.95', Currency.GBP)

    >>> m

    GBP 9.95



Money objects can also be created from and converted to sub units.



.. code:: python



    >>> m = Money.from_sub_units(499, Currency.USD)

    >>> m

    USD 4.99

    >>> m.sub_units

    499



Money is immutable and supports most mathematical and logical operators.



.. code:: python



    >>> m = Money('10.00', Currency.USD)

    >>> m / 2

    USD 5.00

    >>> m + Money('3.00', Currency.USD)

    USD 8.00

    >>> m > Money('5.55', Currency.USD)

    True



Money will automatically round to the correct number of decimal places for the currency.



.. code:: python



    >>> m = Money('9.95', Currency.EUR)

    >>> m * 0.15

    EUR 1.49

    >>> m = Money('10', Currency.JPY)

    >>> m / 3

    JPY 3



Money can be formatted for different locales.



.. code:: python



    >>> Money('3.24', Currency.USD).format('en_US')

    '$3.24'

    >>> Money('9.95', Currency.EUR).format('en_UK')

    '€5.56'

    >>> Money('94', Currency.JPY).format('ja_JP')

    '￥94'



Money does not support conversion between currencies and probably never will. Mathetmatical and logical operations between two money objects are only allowed if both objects are of the same currency. Otherwise, an error will be thrown.



Money will throw an error if you try to construct an object with an invalid amount for the currency (eg, 3.678 USD or 5.5 JPY).



For more examples, check out the test file!



Is this the money library for me?

=================================



If you're just trying to do simple mathematical operations on money in different currencies, this library is probably perfect for you! Perhaps you're just running a store online and you need to compute sales tax.



.. code:: python



    >>> subtotal = Money('9.95', Currency.USD)

    >>> tax = subtotal * 0.07

    >>> total = tax + subtotal

    >>> subtotal.format('en_US')

    '$9.95'

    >>> tax.format('en_US')

    '$0.70'

    >>> total.format('en_US')

    '$10.65'



All rounding will be done correctly, and you can open up in multiple countries with ease!



If you're doing complicated money operations that require many digits of precision for some reason (or you're running a gas station and charging that extra nine tenths of a cent), this library is not for you.



A word of warning: rounding is performed after each multiplication or division operation. While this is exactly what you want when computing sales tax, it may cause confusion if you're not expecting it.



.. code:: python



    >>> m = Money('9.95', Currency.USD)

    >>> m * 0.5 * 2

    USD 9.96

    >>> m * (0.5 * 2)

    USD 9.95

    >>> m * 1

    USD 9.95



To avoid confusion, make sure you simplify your expressions!



Future improvements

===================

Support may be added one day for setting rounding modes. Foreign exchange rates will probably never be supported.



Contributing

============

Pull requests are welcome! Please include tests. You can install everything needed for development with



::



   make install



You can then run the tests from the root directory with



::



    make test



You can run pylint from the root directory with



::



    make pylint



This repo requires pull-request reviews for all changes on branches bound for production in accordance with Vimeo policy.



Acknowledgements

================

Much of the code is borrowed from https://github.com/carlospalol/money. Much of the logic for handling foreign currencies is taken from https://github.com/sebastianbergmann/money. Money formatting is powered by `Babel `_.