financecalculator2025.future_value
==================================

.. py:module:: financecalculator2025.future_value


Functions
---------

.. autoapisummary::

   financecalculator2025.future_value.future_value


Module Contents
---------------

.. py:function:: future_value(principal, annual_rate, n_periods, contribution=0)

   Calculates the future value of an investment with optional monthly contributions.

   :param principal: The initial investment (positive value) or loan (negative value).
   :type principal: float
   :param annual_rate: Annual interest rate (as a percentage, e.g., 5 for 5%).
   :type annual_rate: float
   :param n_periods: Total number of periods (in months).
   :type n_periods: int
   :param contribution: Payment made per period (monthly contributions). Defaults to 0 if not provided.
                        A negative contribution indicates withdrawals.
   :type contribution: float, optional

   :returns:

             A DataFrame containing the following columns:
                 - 'Future Value': The future value of the investment, including contributions.
                 - 'Principal': The initial investment.
                 - 'Contributions': Total amount contributed over the investment period.
                 - 'Interest Earned': The total interest earned from the investment.
   :rtype: pandas.DataFrame

   :raises TypeError: If any of `principal`, `annual_rate`, `n_periods`, or `contribution` is not a float or int.
   :raises ValueError: If `n_periods` is not positive.
       If `annual_rate` is negative.

   .. warning::

      UserWarning
          If `annual_rate` is 0, the future value will be equal to the principal plus contributions.
          If `annual_rate` is unusually low (<1), indicating the user may have entered a percentage instead of a decimal.
          If `n_periods` is unusually low (<6), suggesting the user may have entered years instead of months.

   .. rubric:: Examples

   >>> future_value(principal=1000, annual_rate=5, n_periods=120, contribution=100)