Skip to main content

A Python module to handle interacting with coins

Project description

Coinhandler :moneybag:

A Python module to handle interacting with coins

Build Status

>>> 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))



pipenv install coinhandler


pip install coinhandler

From source

pip install git+git://




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(20), FivePence(5))

.current_transaction -> Transaction

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

>>> handler.insert(0.50)
>>> handler.current_transaction

.total() -> float

Returns the handlers current total value as a float.


Also equivalent to:

>>> / 100

.insert( value )

Add a coin of value to the current_transaction.

>>> handler.insert(0.50)
>>> handler.current_transaction

.purchase( value )

Moves the coins from current_transaction into the available_coins and makes the difference in coins between the purchase value and the 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

.return_coins() -> CoinCollection

Empties out the current_transaction and returns those coins as a 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))


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.


Returns the total value of the collection as a float.

>>> collection = CoinCollection(2.00, 1.00, 0.50)

.append( value )

Adds the value to the collection.

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

.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])

.remove( value )

Removes a Coin represented by value from the collection.

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

.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()

.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()
>>> collection.pop(0)

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)

And accessed by index.

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


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)

# Use a CoinColletion 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()

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

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

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

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

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

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

coinhandler-0.3.tar.gz (5.3 kB view hashes)

Uploaded source

Built Distribution

coinhandler-0.3-py3-none-any.whl (5.5 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page