financecalculator2025.present_value
===================================

.. py:module:: financecalculator2025.present_value


Functions
---------

.. autoapisummary::

   financecalculator2025.present_value.present_value


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

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

   Calculates the present value of an investment or loan, accounting for optional contributions.

   :param principal: The initial investment or loan amount.
   :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), a non-zero positive integer.
   :type n_periods: int
   :param contribution: Payment made per period (monthly contributions). Defaults to 0 if not provided.
   :type contribution: float, optional

   :returns:

             A DataFrame containing the following columns:
                 - 'Present Value': The present value of the investment or loan.
                 - 'Principal': The initial investment or loan amount.
                 - 'Contributions': Total amount contributed over the investment period.
                 - 'Interest Saved': The amount of interest avoided by paying a lump sum today instead
                     of spreading payments over time.
   :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 present value will not include any interest effects.
          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

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