Metadata-Version: 2.1
Name: easydollar
Version: 1.0.2
Summary: A simple, light-weight data type for handling cash (in USD)
Home-page: https://github.com/SeanCPP/easydollar
Author: Sean Patrick Franklin
Author-email: sean.patrick516@gmail.com
License: UNKNOWN
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
        ```python
        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
        ```python
        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.
        
        ```python
        from easydollar.USD import usd
        ```
        
        #### Add cash amounts
        
        *Example 1*
        ```python
        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*
        ```python
        # 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
        
        ```python
        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.*
        
        ```python
        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.
        
        ```python
        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 
        ```python
        monthly_principle = loan_amount.distribute(term)[0]
        ```
        
        To find the current payment, you could do:
        ```python
        current_payment = my_usd.distribute(total_term)[payments_already_made]
        ```
        or
        ```python
        current_payment = my_usd.distribute(remaining_term)[0]
        ```
        
        *A feature to streamline this is being worked on.*
        
        
        ## Other features of note:
        
        
        #### with_interest(percent)
        ```python
        appreciated_value = my_usd.with_interest(50) # 50% appreciation
        ```
        
        #### apply_interest(percent)
        ```python
        my_usd.apply_interest(0.6) # Applies 0.6% interest to my_usd
        ```
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3.6
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
