Coinhandler 💰

A Python module to handle interacting with coins

>>> from coinhandler import CoinHandler

>>> handler = CoinHandler(
...     starting_float=(2.00, 1.00, 0.50, 0.20, 0.05)
... )

>>> handler.insert(0.50)
>>> handler.insert(1.00)

>>> handler.purchase(1.25)

>>> handler.return_coins()
CoinCollection(TwentyPence(1), FivePence(1))

Installation

Coinhandler requires Python 3.6 or greater!

pipenv*

pipenv install coinhandler

pip

pip install coinhandler

From source

pip install git+git://github.com/alxwrd/coinhandler.git

*recommended

Useage

CoinHandler

A CoinHandler object can be used to manage a transaction, or a series of transactions. To create a handler instance, it should be provided with a starting float (money supply).

The starting_float should be an iterable of either float or int

from coinhandler import CoinHandler

handler = CoinHandler(
    starting_float=(2.00, 1.00, 0.50, 0.20, 0.05)
)

A CoinHandler object provides a simple interface for making trasactions against the float it started with.

.available_coins -> CoinCollection

Provides access to the current supply of Coins in in the handler.

>>> handler.available_coins
CoinCollection(TwoPound(1), OnePound(1), FiftyPence(1), TwentyPence(1), FivePence(1))

.current_transaction -> Transaction

Provides access to the Coins that are part of the current transaction.

>>> handler.insert(0.50)
>>> handler.current_transaction
Transaction(FiftyPence(1))

.total() -> float

Returns the handlers current total value as a float.

>>> handler.total()
3.75

Also equivalent to:

>>> handler.available_coins.total() / 100
3.75

.insert( value )

Add a coin of value to the current_transaction.

>>> handler.insert(0.50)
>>> handler.current_transaction
Transaction(FiftyPence(1))

.purchase( value )

Moves the coins from current_transaction into the available_coins and makes the difference in coins between the purchase value and the current_transation.total() available in .current_transaction.

>>> handler.available_coins
CoinCollection(TwentyPence(1), FivePence(1))

>>> handler.insert(0.50)
>>> handler.purchase(0.25)

>>> handler.current_transaction
Transaction(TwentyPence(1), FivePence(1))
>>> handler.available_coins
CoinCollection(FiftyPence(1))

.return_coins() -> CoinCollection

Empties out the current_transaction and returns those coins as a CoinCollection.

CoinCollection

A CoinCollection object represents a collection of Coins. It functions similar to a python list, and provides some similar methods.

from coinhandler import CoinCollection

collection = CoinCollection(2.00, 1.00, 0.50)

You can also create a CoinCollection from a value. This will return the smallest amount of Coins needed to create that value.

>>> CoinCollection.from_value(1.25)
CoinCollection(OnePound(1), TwentyPence(1), FivePence(1))

Transaction

A Transaction object is a subclass of CoinCollection, and functions identically.

.remove_by_value( value ) -> CoinCollection

Removes coins from the collection by a value, and returns new collection with valid coins from the original collection.

>>> collection = CoinCollection(2.00, 1.00, 0.20, 0.05)
>>> collection.remove_by_value(1.25)
CoinCollection(OnePound(1), TwentyPence(1), FivePence(1))

NOTE: .remove_by_value will only remove available coins from the original collection. So for the example:

>>> collection = CoinCollection(2.00, 1.00, 0.20, 0.05)
>>> collection.remove_by_value(1.30)
CoinCollection(OnePound(1), TwentyPence(1), FivePence(0.05))

Only '1.25' is returned.

.total()

Returns the total value of the collection as a float.

>>> collection = CoinCollection(2.00, 1.00, 0.50)
>>> coins.total()
3.75

.append( value )

Adds the value to the collection.

>>> collection = CoinCollection(2.00, 1.00, 0.50)
>>> collection.append(1.00)
>>> collection.total()
4.50

.extend( iterable[values] )

Extends the collection by an iterable of values.

>>> collection = CoinCollection(2.00, 1.00, 0.50)
>>> collection.extend([1.00, 1.00])
>>> collection.total()
5.50

.remove( value )

Removes a Coin represented by value from the collection.

>>> collection = CoinCollection(2.00, 1.00, 0.50)
>>> collection.remove(1.00)
>>> collection.total()
2.50

.clear() -> CoinCollection

Removes all Coins from the collection, and returns them as a new collection.

>>> collection = CoinCollection(2.00, 1.00, 0.50)
>>> coins = collection.clear()
>>> collection.total()
0.0
>>> coins.total()
3.50

.pop( index=-1 ) -> Coin

Removes the Coin located index out of the collection and returns it.

>>> collection = CoinCollection(2.00, 1.00, 0.50)
>>> collection.pop()
FiftyPence(1)
>>> collection.pop(0)
TwoPound(1)
>>> coins.total()
1.00

As a list

For basic useage, a CoinCollection can be duck typed as a list. It can be:

Compared to an iterable of values,

>>> collection = CoinCollection(2.00, 1.00, 0.50)
>>> assert collection = [2.00, 1.00, 0.50]
>>> assert collection = (2.00, 1.00, 0.50)

Iterated over,

>>> collection = CoinCollection(2.00, 1.00, 0.50)
>>> for coin in collection:
...     print(coin)
'£2.00'
'£1.00'
'50p'

And accessed by index.

>>> collection = CoinCollection(2.00, 1.00, 0.50)
>>> collection[1]
OnePound(1)

Coin

A Coin object represents a value. Its use allows representing money using int vs. float.

The Coin class is a factory class for all other Coins that have been defined. It will return the highest value coin of a given value.

from coinhandler import Coin
from coinhandler.coins import OnePound, FiftyPence

assert Coin(100) == OnePound(1)
assert Coin(50) == FiftyPence(1)

When using the Coin factory class, a valid coin value should be used. Not doing so can create undesirable Coin objects.

>>> coin = Coin(23)
OnePence(23)

# Use a CoinCollection instead!

>>> CoinCollection.from_value(23)
CoinCollection(TwentyPence(1), TwoPence(1), OnePence(1))

Coins of a specfic type can be created by just by creating an instance of them.

>>> from coinhandler.coins import OnePound
>>> OnePound()
OnePound(1)

All coins have a value, which is the represented as an integer.

>>> from coinhandler.coins import OnePound
>>> OnePound().value
100

Subclassing from Coin will add that coin to the available coins to be created.

>>> from coinhandler import Coin
>>> Coin(25)
FivePence(5)

>>> class Quarter(Coin):
...     multiplier = 25
...     def __str__(self):
...         return f"{self.value}¢"
>>> coin = Coin(25)
>>> print(coin)
'25¢'
>>> coin.value
25