easydollar 1.0.2

A simple, light-weight data type for handling cash (in USD)

What's new in v1.0.2

• Improved parsing of easydollar.usd() to allow commas (eg '$1,000.00')
• Changed the output of USD.repr to improve readability
• Fixed a major logical error in USD.distribute(). It should now function as intended.

Example

cash = usd('$5,000.67')
print(repr(cash)) # Output: USD(dollars=5000, cents=67)

easydollar | py

written by Sean Franklin ([e-mail])

pip install easydollar

Floating-Point values should not be used in money calculations. Python's Decimal or BigDecimal in Java are a bit clunky to use for quick prototyping.

This module is useful for str-parsed US-Dollar amounts (from user input, or a .txt/.csv/.xls)

This is the wrong module for cent calcuations that need three or more decimal-point places (like gas prices or some APR calculations)

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