A simple, light-weight data type for handling cash (in USD)
Project description
easydollar | py
written by Sean Franklin (sean.patrick516@gmail.com)
Floating-Points should never be used in money calculations!
This module contains the USD data-type, which can replace clunky "BigInt" interfaces for handling and representing cash without using any floating-point values or arithmetic.
The intuitive nature of this class will become obvious as you incorporate it in your existing projects. For example, If you're getting the cash amount data from user input or from reading a file, you can just wrap the str with usd()
amount = usd(input('Enter cash amount $'))
Note "Instantiating a USD with a float" is a feature intentionally left out. Input like 50.20 actually becomes 50.2 which then becomes $50.02 ..which is obviously incorrect.
How to use the USD type
Note You can see the output of all the below examples by writing
import easydollar.examples
How to import
It is recommended you use the lower-case usd() to instantiate USD instances.
usd() casts a str to a USD instance.
from easydollar.USD import usd
Add cash amounts
Example 1
husband_income = usd('55000.00')
# if it's a whole dollar amount, the decimal-point is optional.
wife_income = usd('62000')
household_income = husband_income + wife_income
print(f'Total household income: {household_income}\n')
Example 2
# USD instances will implicitly roll over cents into dollars when cast to a string.
money1 = usd('1.50')
money2 = usd('0.50')
total = money1 + money2
print (f'Dollar addition: {money1} + {money2} = {total}')
print (f"Output of usd('0.5255') = {usd('0.5255')}") # Outputs "$52.55"
print(f"Output of usd('1000575.100') = {usd('1000575.100')}") # Outputs "$1,000,576.00"
Making change from a transaction
price = usd('56.60')
paid = usd('60.00')
change = paid - price
print(f'Price: {price}')
print(f'Paid: {paid}')
print (f'Change due: {change}')
IMPORTANT!
The multiply operator on the USD object is a "scale" operation (only accepts a whole number) You can't multiply two USD's together.
payrate = usd('15.00')
hours_worked = 40
paycheck = payrate * hours_worked
print(f'This weeks earnings: {paycheck}')
Division, and Interest Multiplication
The divide operator in USD is a distribution function.
Similar to the multiply operator, a USD instance can only be "divided" by a whole number.
IMPORTANT!
The division operator is not a true division (this would involve using floating-point values in some cases.) Instead, it invokes USD's 'distribute' method.
USD.distribute(n) distributes the USD-instance's value among n and returns a list of USD
If you were to sum the elements of the list, you would have the pre-distribute() value exactly
The divide "/" operator is only a shorthand for my_usd.distribute(n)[0]
IMPORTANT!
If you add the result of the "/" operator n times, you might not get the original value.
loan_amount = usd('10653.26')
interest = 21 # 21 percent (21%)
total_loan_interest = loan_amount.interest(interest)
term = 60
monthly_principle = loan_amount / term
monthly_interest = total_loan_interest / term
first_payment = monthly_interest + monthly_principle
print('~~ Loan Issued. ~~')
print(f'Loan Amount: {loan_amount}')
print(f'Interest: {interest}%')
print(f'Term: {term} months')
print(f'Total interest to be paid over term: {total_loan_interest}\n')
print(f'Principle monthly: {monthly_principle}')
print(f'Interest monthly: {monthly_interest}\n')
print(f'First payment due: {first_payment}')
Using the division operator here is okay, because this is a calculation of the first payment. It is equivilent to
monthly_principle = loan_amount.distribute(term)[0]
To find the current payment, you could do:
current_payment = my_usd.distribute(total_term)[payments_already_made]
or
current_payment = my_usd.distribute(remaining_term)[0]
A feature to streamline this is being worked on.
Other features of note:
with_interest(percent)
appreciated_value = my_usd.with_interest(50) # 50% appreciation
apply_interest(percent)
my_usd.apply_interest(0.6) # Applies 0.6% interest to my_usd
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for easydollar-1.0.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6968a295df810883a55e57bba14c3bba055623c5facebe8c96028b5a187d2c1c |
|
MD5 | 78f24fc5d06b862a484b281e4aad31e3 |
|
BLAKE2b-256 | 20950bee72db6e72b5183c153ba73d00c6fa9dee16f5a52c8ac4153b5f493ba8 |