Pricing
Maintainer
Joe Black | me@joeblack.nyc | github
Introduction
Pricing classes and tools with CLDR-backed locale-aware formatting and currency exchange. Easy to extend/customize since it's built on ZCA.
Define your custom currencies and exchange's in your project's ZCML and you're golden.
Installation
pip3 install pricing
Usage
Basic
>>> from pricing import Price
... Price('2.22', 'USD')
EUR 2.22
>>> Price('2.34223434', 'BTC')
BTC 2.34223434
>>> m = Price(2, 'USD')
... m.amount
Decimal('2')
... m.currency
'USD'
>>> m = Price('2.22', 'EUR')
... m / 2
EUR 1.11
>>> m + Price('7.77', 'EUR')
EUR 9.99
Formatting
>>> m = Price('1234.567', 'EUR')
... str(m)
'EUR 1,234.57'
>>> m.format()
'€1,234.57'
Payment URI's
Create BIP21 and EIP681 compatible payment URI's.
>>> from pricing.uris import BIP21PaymentURI
... BIP21PaymentURI(
... 'bitcoin',
... address='19kxPokCjD6tUU3sHaLZgEQBkRsCTBt3jj',
... amount='4.32345').to_uri()
'bitcoin:19kxPokCjD6tUU3sHaLZgEQBkRsCTBt3jj?amount=4.32345'
>>> from pricing.uris import EIP681PaymentURI
... EIP681PaymentURI(
... 'ethereum',
... address='077a7506b69e37e4f6852577190f04a35df9a36c',
... value='4.32345').to_uri()
'ethereum:0x077a7506b69e37e4f6852577190f04a35df9a36c?value=4.32345'
Currency Exchange
Currency exchange works by "installing" a backend class that implements the IExchangeBackend
interface.
XPrice
You can use money.XPrice
(a subclass of Price), for automatic currency conversion while adding, subtracting, and dividing money objects (+, +=, -, -=, /, //). This is useful when aggregating lots of money objects with heterogeneous currencies. The currency of the leftmost object has priority.
from pricing import XPrice
# Register backend and rates as above...
a = XPrice(1, 'AAA')
b = XPrice(1, 'BBB')
assert sum([a, b]) == XPrice('1.25', 'AAA')
Extending and customization
You can use ZCML to configure custom currencyFormats and exchanges, create a new file called currency.zcml
, and follow the example below to configure.
<configure
xmlns:zope="http://namespaces.zope.org/zope"
xmlns="http://namespaces.zope.org/currency">
<zope:include package="pricing" file="currency-meta.zcml" />
<currency default="USD">
<currencyFormat
name="bitcoin"
code="BTC"
symbol="₿"
format="¤#,##0.########"
currency_digits="false"
decimal_quantization="true" />
<currencyFormat
name="litecoin"
code="LTC"
symbol="Ł"
format="¤#,##0.########"
currency_digits="false"
decimal_quantization="true" />
<currencyFormat
name="ether"
code="ETH"
symbol="Ξ"
format="¤#,##0.##################"
currency_digits="false"
decimal_quantization="true" />
<exchange
component="pricing.exchange.Exchange"
backend="pricing.exchange.CoinBaseBackend"
base="USD" />
</currency>
</configure>
Then include currency.zcml
in your configure.zcml
file:
<include file="currency.zcml" />
Fields
Included are custom fields for zope.schema
and attrs
based classes. Checkout money.fields
.
Exceptions
PriceException(Exception)
Base class for all exceptions.
CurrencyMismatch(PriceException, ValueError)
Thrown when mixing different currencies, e.g. Price(2, 'EUR') + Price(2, 'USD')
. Price objects must be converted first to the same currency, or XPrice could be used for automatic conversion.
InvalidOperandType(PriceException, TypeError)
Thrown when attempting invalid operations, e.g. multiplication between money objects.
ExchangeError(PriceException)
Base class for exchange exceptions.
ExchangeBackendNotInstalled(ExchangeError)
Thrown if a conversion is attempted, but there is no backend available.
ExchangeRateNotFound(ExchangeError)
The installed backend failed to provide a suitable exchange rate between the origin and target currencies.
Hierarchy
-
PriceException
CurrencyMismatch
InvalidOperandType
-
ExchangeError
ExchangeBackendNotInstalled
ExchangeRateNotFound