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

## Project description

### 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 (sean.patrick516@gmail.com)

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

## Project details

## Release history Release notifications

## Download files

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

Filename, size & hash SHA256 hash help | File type | Python version | Upload date |
---|---|---|---|

easydollar-1.0.2-py3-none-any.whl (5.9 kB) Copy SHA256 hash SHA256 | Wheel | py3 | |

easydollar-1.0.2.tar.gz (5.0 kB) Copy SHA256 hash SHA256 | Source | None |