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

Installation

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

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

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

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

Uploaded Source

Built Distribution

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

Uploaded Python 3

File details

Details for the file coinhandler-0.3.tar.gz.

File metadata

  • Download URL: coinhandler-0.3.tar.gz
  • Upload date:
  • Size: 5.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.11.0 pkginfo/1.4.2 requests/2.19.1 setuptools/40.2.0 requests-toolbelt/0.8.0 tqdm/4.26.0 CPython/3.6.3

File hashes

Hashes for coinhandler-0.3.tar.gz
Algorithm Hash digest
SHA256 8df8705e7ad13e1e4974a142fcdd807ac63f53d5277175de9e8a42c0857f81fe
MD5 4293427a959fd63d4d318fa67ec01531
BLAKE2b-256 cd56e1b803e4ea9f885d27b58d9b0415de597ccf483eaa8803d1edd3a3d41b72

See more details on using hashes here.

File details

Details for the file coinhandler-0.3-py3-none-any.whl.

File metadata

  • Download URL: coinhandler-0.3-py3-none-any.whl
  • Upload date:
  • Size: 5.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.11.0 pkginfo/1.4.2 requests/2.19.1 setuptools/40.2.0 requests-toolbelt/0.8.0 tqdm/4.26.0 CPython/3.6.3

File hashes

Hashes for coinhandler-0.3-py3-none-any.whl
Algorithm Hash digest
SHA256 eb98c048077eb93cadd3c5c3763c779df1fa92bc34d24e0b142b14c09dc22b47
MD5 6547ffb80a4a2f6c9b8780ef2e5ec104
BLAKE2b-256 5ee5a51536c120a6aba48b395dad2ef1fc21f49eb3152d8d824520d93aca6414

See more details on using hashes here.

Supported by

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