MAINT: deprecate financial functions.

As per NEP-32, the financial functions are deprecated.

1 files changed, 115 insertions, 0 deletions

diff --git a/numpy/lib/financial.py b/numpy/lib/financial.py
index d72384e99..3ac3a4c33 100644
--- a/numpy/lib/financial.py
+++ b/numpy/lib/financial.py
@@ -12,6 +12,7 @@ otherwise stated.
 """
 from __future__ import division, absolute_import, print_function
 
+import warnings
 from decimal import Decimal
 import functools
 
@@ -19,6 +20,10 @@ import numpy as np
 from numpy.core import overrides
 
 
+_depmsg = ("numpy.{name} is deprecated and will be removed from NumPy 1.20. "
+           "Use numpy_financial.{name} instead "
+           "(https://pypi.org/project/numpy-financial/).")
+
 array_function_dispatch = functools.partial(
     overrides.array_function_dispatch, module='numpy')
 
@@ -45,6 +50,8 @@ def _convert_when(when):
 
 
 def _fv_dispatcher(rate, nper, pmt, pv, when=None):
+    warnings.warn(_depmsg.format(name='fv'),
+                  DeprecationWarning, stacklevel=3)
     return (rate, nper, pmt, pv)
 
 
@@ -53,6 +60,15 @@ def fv(rate, nper, pmt, pv, when='end'):
     """
     Compute the future value.
 
+    .. deprecated:: 1.18
+
+       `fv` is deprecated; see NEP 32::
+
+           https://numpy.org/neps/nep-0032-remove-financial-functions.html
+
+        Use the corresponding function in the numpy-financial library,
+        https://pypi.org/project/numpy-financial
+
     Given:
      * a present value, `pv`
      * an interest `rate` compounded once per period, of which
@@ -139,6 +155,8 @@ def fv(rate, nper, pmt, pv, when='end'):
 
 
 def _pmt_dispatcher(rate, nper, pv, fv=None, when=None):
+    warnings.warn(_depmsg.format(name='pmt'),
+                  DeprecationWarning, stacklevel=3)
     return (rate, nper, pv, fv)
 
 
@@ -147,6 +165,15 @@ def pmt(rate, nper, pv, fv=0, when='end'):
     """
     Compute the payment against loan principal plus interest.
 
+    .. deprecated:: 1.18
+
+       `pmt` is deprecated; see NEP 32::
+
+           https://numpy.org/neps/nep-0032-remove-financial-functions.html
+
+        Use the corresponding function in the numpy-financial library,
+        https://pypi.org/project/numpy-financial
+
     Given:
      * a present value, `pv` (e.g., an amount borrowed)
      * a future value, `fv` (e.g., 0)
@@ -237,6 +264,8 @@ def pmt(rate, nper, pv, fv=0, when='end'):
 
 
 def _nper_dispatcher(rate, pmt, pv, fv=None, when=None):
+    warnings.warn(_depmsg.format(name='nper'),
+                  DeprecationWarning, stacklevel=3)
     return (rate, pmt, pv, fv)
 
 
@@ -245,6 +274,15 @@ def nper(rate, pmt, pv, fv=0, when='end'):
     """
     Compute the number of periodic payments.
 
+    .. deprecated:: 1.18
+
+       `nper` is deprecated; see NEP 32::
+
+           https://numpy.org/neps/nep-0032-remove-financial-functions.html
+
+        Use the corresponding function in the numpy-financial library,
+        https://pypi.org/project/numpy-financial
+
     :class:`decimal.Decimal` type is not supported.
 
     Parameters
@@ -311,6 +349,8 @@ def nper(rate, pmt, pv, fv=0, when='end'):
 
 
 def _ipmt_dispatcher(rate, per, nper, pv, fv=None, when=None):
+    warnings.warn(_depmsg.format(name='ipmt'),
+                  DeprecationWarning, stacklevel=3)
     return (rate, per, nper, pv, fv)
 
 
@@ -319,6 +359,15 @@ def ipmt(rate, per, nper, pv, fv=0, when='end'):
     """
     Compute the interest portion of a payment.
 
+    .. deprecated:: 1.18
+
+       `ipmt` is deprecated; see NEP 32::
+
+           https://numpy.org/neps/nep-0032-remove-financial-functions.html
+
+        Use the corresponding function in the numpy-financial library,
+        https://pypi.org/project/numpy-financial
+
     Parameters
     ----------
     rate : scalar or array_like of shape(M, )
@@ -422,6 +471,8 @@ def _rbl(rate, per, pmt, pv, when):
 
 
 def _ppmt_dispatcher(rate, per, nper, pv, fv=None, when=None):
+    warnings.warn(_depmsg.format(name='ppmt'),
+                  DeprecationWarning, stacklevel=3)
     return (rate, per, nper, pv, fv)
 
 
@@ -430,6 +481,15 @@ def ppmt(rate, per, nper, pv, fv=0, when='end'):
     """
     Compute the payment against loan principal.
 
+    .. deprecated:: 1.18
+
+       `ppmt` is deprecated; see NEP 32::
+
+           https://numpy.org/neps/nep-0032-remove-financial-functions.html
+
+        Use the corresponding function in the numpy-financial library,
+        https://pypi.org/project/numpy-financial
+
     Parameters
     ----------
     rate : array_like
@@ -456,6 +516,8 @@ def ppmt(rate, per, nper, pv, fv=0, when='end'):
 
 
 def _pv_dispatcher(rate, nper, pmt, fv=None, when=None):
+    warnings.warn(_depmsg.format(name='pv'),
+                  DeprecationWarning, stacklevel=3)
     return (rate, nper, nper, pv, fv)
 
 
@@ -464,6 +526,15 @@ def pv(rate, nper, pmt, fv=0, when='end'):
     """
     Compute the present value.
 
+    .. deprecated:: 1.18
+
+       `pv` is deprecated; see NEP 32::
+
+           https://numpy.org/neps/nep-0032-remove-financial-functions.html
+
+        Use the corresponding function in the numpy-financial library,
+        https://pypi.org/project/numpy-financial
+
     Given:
      * a future value, `fv`
      * an interest `rate` compounded once per period, of which
@@ -567,6 +638,8 @@ def _g_div_gp(r, n, p, x, y, w):
 
 def _rate_dispatcher(nper, pmt, pv, fv, when=None, guess=None, tol=None,
                      maxiter=None):
+    warnings.warn(_depmsg.format(name='rate'),
+                  DeprecationWarning, stacklevel=3)
     return (nper, pmt, pv, fv)
 
 
@@ -582,6 +655,15 @@ def rate(nper, pmt, pv, fv, when='end', guess=None, tol=None, maxiter=100):
     """
     Compute the rate of interest per period.
 
+    .. deprecated:: 1.18
+
+       `rate` is deprecated; see NEP 32::
+
+           https://numpy.org/neps/nep-0032-remove-financial-functions.html
+
+        Use the corresponding function in the numpy-financial library,
+        https://pypi.org/project/numpy-financial
+
     Parameters
     ----------
     nper : array_like
@@ -651,6 +733,8 @@ def rate(nper, pmt, pv, fv, when='end', guess=None, tol=None, maxiter=100):
 
 
 def _irr_dispatcher(values):
+    warnings.warn(_depmsg.format(name='irr'),
+                  DeprecationWarning, stacklevel=3)
     return (values,)
 
 
@@ -659,6 +743,15 @@ def irr(values):
     """
     Return the Internal Rate of Return (IRR).
 
+    .. deprecated:: 1.18
+
+       `irr` is deprecated; see NEP 32::
+
+           https://numpy.org/neps/nep-0032-remove-financial-functions.html
+
+        Use the corresponding function in the numpy-financial library,
+        https://pypi.org/project/numpy-financial
+
     This is the "average" periodically compounded rate of return
     that gives a net present value of 0.0; for a more complete explanation,
     see Notes below.
@@ -734,6 +827,8 @@ def irr(values):
 
 
 def _npv_dispatcher(rate, values):
+    warnings.warn(_depmsg.format(name='npv'),
+                  DeprecationWarning, stacklevel=3)
     return (values,)
 
 
@@ -742,6 +837,15 @@ def npv(rate, values):
     """
     Returns the NPV (Net Present Value) of a cash flow series.
 
+    .. deprecated:: 1.18
+
+       `npv` is deprecated; see NEP 32::
+
+           https://numpy.org/neps/nep-0032-remove-financial-functions.html
+
+        Use the corresponding function in the numpy-financial library,
+        https://pypi.org/project/numpy-financial
+
     Parameters
     ----------
     rate : scalar
@@ -808,6 +912,8 @@ def npv(rate, values):
 
 
 def _mirr_dispatcher(values, finance_rate, reinvest_rate):
+    warnings.warn(_depmsg.format(name='mirr'),
+                  DeprecationWarning, stacklevel=3)
     return (values,)
 
 
@@ -816,6 +922,15 @@ def mirr(values, finance_rate, reinvest_rate):
     """
     Modified internal rate of return.
 
+    .. deprecated:: 1.18
+
+       `mirr` is deprecated; see NEP 32::
+
+           https://numpy.org/neps/nep-0032-remove-financial-functions.html
+
+        Use the corresponding function in the numpy-financial library,
+        https://pypi.org/project/numpy-financial
+
     Parameters
     ----------
     values : array_like