financecalculator2025.n_periods
===============================

.. py:module:: financecalculator2025.n_periods


Functions
---------

.. autoapisummary::

   financecalculator2025.n_periods.n_periods


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

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

   Calculates the number of periods (in months) needed to reach a specified future value,
   given an initial principal, an annual interest rate, and optional monthly contributions.

   :param principal: The initial amount, which can be a positive value for an investment or a negative value for a loan.
   :type principal: float
   :param annual_rate: Annual interest rate (as a percentage, e.g., 5 for 5%).
   :type annual_rate: float
   :param future_value: The target future value of the investment or loan balance.
   :type future_value: float
   :param contribution: Payment made per period (monthly contributions). Defaults to 0 if not provided.
   :type contribution: float, optional

   :returns: **n_periods** -- The number of periods (in months) required to reach the future value.
   :rtype: int

   :raises TypeError: If any of `principal`, `annual_rate`, `future_value`, or `contribution` is not a float or int.
   :raises ValueError: If both `principal` and `contribution` are 0.
       If `annual_rate` is negative.

   .. warning::

      UserWarning
          If `annual_rate` is unusually low (<1), indicating the user may have entered a percentage instead of a decimal.
          If `annual_rate` is 0, the future value cannot be reached without a contribution.
          If `n_periods` is unusually low (<5), suggesting the user may have entered years instead of months.

   .. rubric:: Examples

   >>> n_periods(principal=1000, annual_rate=5, future_value=2000, contribution=50)