Usage
*****

The internal implementations of this library are meant to be accessed through
a public API composed by the classes

*   ``Loan``
*   ``IofGrossup``

Loan
----

For example, a ``Loan`` can be instantiated as

::

    >>> from datetime import date
    >>> from loan_calculator import Loan
    >>> loan = Loan(
    ...     10000.00,  # principal
    ...     0.54,  # annual interest rate
    ...     date(2020, 1, 5),  # start date
    ...     [
    ...         date(2020, 2, 12),  # expected return date
    ...         date(2020, 3, 13),  # expected return date
    ...         date(2020, 3, 11),  # expected return date
    ...         date(2020, 4, 13),  # expected return date
    ...         date(2020, 5, 12),  # expected return date
    ...         date(2020, 6, 12),  # expected return date
    ...         date(2020, 7, 14),  # expected return date
    ...         date(2020, 8, 15),  # expected return date
    ...     ],
    ...     year_size=365,  # used to convert between annual and daily interest rates
    ...     grace_period=0,  # number of days for which the principal is not affected by the interest rate
    ...     amortization_schedule_type='progressive_price_schedule',  # determines how the principal is amortized
    ... )


A summary of this loan can be displayed with the function ``display_summary``

::

    >>> from loan_calculator import display_summary
    >>> display_summary(loan)
    ... +------------+----------+--------------+--------------+--------------+--------------+
    ... |    dates   |    days  |    balance   | amortization |   interest   |    payment   |
    ... +------------+----------+--------------+--------------+--------------+--------------+
    ... | 2020-01-05 |        0 |     10000.00 |              |              |              |
    ... | 2020-02-12 |       38 |      9020.32 |      1105.69 |       333.77 |      1439.46 |
    ... | 2020-03-13 |       68 |      6463.86 |      1148.35 |       291.12 |      1439.46 |
    ... | 2020-03-11 |       66 |      7884.64 |      1192.65 |       246.81 |      1439.46 |
    ... | 2020-04-13 |       99 |      5265.84 |      1237.20 |       202.26 |      1439.46 |
    ... | 2020-05-12 |      128 |      4010.16 |      1280.38 |       159.08 |      1439.46 |
    ... | 2020-06-12 |      159 |      2720.49 |      1331.35 |       108.11 |      1439.46 |
    ... | 2020-07-14 |      191 |      1385.99 |      1328.20 |       111.26 |      1439.46 |
    ... | 2020-08-15 |      223 |         0.00 |      1376.19 |        63.27 |      1439.46 |
    ... +------------+----------+--------------+--------------+--------------+--------------+
    ... |            |          |              |     10000.00 |      1515.69 |     11515.69 |
    ... +------------+----------+--------------+--------------+--------------+--------------+

Grossup
-------

Loan operations will usually involve taxes and service fees. Therefore, the
loan's principal must be grossed up (i.e., "incremented") in order to
comprehend such quantities. This library implements a grossup for the brazilian
tax IOF. Its specifications are provided by current Brazilian law.

`IOF grossup`. Consider the same loan as above and let us apply the IOF grossup
over it. Picking ``date(2020, 1, 15)`` as the taxable event, we obtain

::

    >>> from loan_calculator import IofGrossup
    >>> iof_grossup = IofGrossup(
    ...     loan,
    ...     date(2020, 1, 15),
    ...     daily_iof_aliquot=0.000082,
    ...     complementary_iof_aliquot=0.0038,
    ...     service_fee_aliquot=0.05
    ... )
    >>> display_summary(grossup.grossed_up_loan, reference_date=grossup.reference_date)
    ... +------------+----------+--------------+--------------+--------------+--------------+
    ... |    dates   |    days  |    balance   | amortization |   interest   |    payment   |
    ... +------------+----------+--------------+--------------+--------------+--------------+
    ... | 2020-01-15 |        0 |     10664.51 |              |              |              |
    ... | 2020-02-12 |       28 |      9619.73 |      1179.16 |       355.95 |      1535.12 |
    ... | 2020-03-13 |       58 |      6893.39 |      1224.65 |       310.46 |      1535.12 |
    ... | 2020-03-11 |       89 |      8408.59 |      1271.90 |       263.21 |      1535.12 |
    ... | 2020-04-13 |      118 |      5615.76 |      1319.41 |       215.70 |      1535.12 |
    ... | 2020-05-12 |      149 |      4276.64 |      1365.46 |       169.65 |      1535.12 |
    ... | 2020-06-12 |      181 |      2901.27 |      1419.82 |       115.30 |      1535.12 |
    ... | 2020-07-14 |      213 |      1478.09 |      1416.46 |       118.65 |      1535.12 |
    ... | 2020-08-15 |      240 |         0.00 |      1467.64 |        67.48 |      1535.12 |
    ... +------------+----------+--------------+--------------+--------------+--------------+
    ... |            |          |              |     10664.51 |      1616.41 |     12280.92 |
    ... +------------+----------+--------------+--------------+--------------+--------------+


IRR
---

The internal return rate is the interest rate that the borrower actually
experiences, since the only monetary amount the borrower receives is the net
principal, while she has to pay off the grossed up principal. The internal
return can be evaluated from the property `BaseGrossup.irr`, which will
numerically approximate the IRR. For example, for the same loan
as above, the IRR is given by

::

    >>> print(iof_grossup.irr)
    ... 0.0019046654159656333

Notice how this is slightly greater than the daily interest rate of the
base loan:

::

    >>> print(iof_grossup.base_loan.daily_interest_rate)
    ... 0.0011836655041597144