MAINT: deprecate financial functions.

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

2 files changed, 151 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
diff --git a/numpy/lib/tests/test_financial.py b/numpy/lib/tests/test_financial.py
index 21088765f..cb67f7c0f 100644
--- a/numpy/lib/tests/test_financial.py
+++ b/numpy/lib/tests/test_financial.py
@@ -1,5 +1,6 @@
 from __future__ import division, absolute_import, print_function
 
+import warnings
 from decimal import Decimal
 
 import numpy as np
@@ -8,22 +9,35 @@ from numpy.testing import (
     )
 
 
+def filter_deprecation(func):
+    def newfunc(*args, **kwargs):
+        with warnings.catch_warnings(record=True) as ws:
+            warnings.filterwarnings('always', category=DeprecationWarning)
+            func(*args, **kwargs)
+            assert_(all(w.category is DeprecationWarning for w in ws))
+    return newfunc
+
+
 class TestFinancial(object):
+    @filter_deprecation
     def test_npv_irr_congruence(self):
         # IRR is defined as the rate required for the present value of a
         # a series of cashflows to be zero i.e. NPV(IRR(x), x) = 0
         cashflows = np.array([-40000, 5000, 8000, 12000, 30000])
         assert_allclose(np.npv(np.irr(cashflows), cashflows), 0, atol=1e-10, rtol=0)
 
+    @filter_deprecation
     def test_rate(self):
         assert_almost_equal(
             np.rate(10, 0, -3500, 10000),
             0.1107, 4)
 
+    @filter_deprecation
     def test_rate_decimal(self):
         rate = np.rate(Decimal('10'), Decimal('0'), Decimal('-3500'), Decimal('10000'))
         assert_equal(Decimal('0.1106908537142689284704528100'), rate)
 
+    @filter_deprecation
     def test_irr(self):
         v = [-150000, 15000, 25000, 35000, 45000, 60000]
         assert_almost_equal(np.irr(v), 0.0524, 2)
@@ -43,20 +57,25 @@ class TestFinancial(object):
         v = [-1, -2, -3]
         assert_equal(np.irr(v), np.nan)
 
+    @filter_deprecation
     def test_pv(self):
         assert_almost_equal(np.pv(0.07, 20, 12000, 0), -127128.17, 2)
 
+    @filter_deprecation
     def test_pv_decimal(self):
         assert_equal(np.pv(Decimal('0.07'), Decimal('20'), Decimal('12000'), Decimal('0')),
                      Decimal('-127128.1709461939327295222005'))
 
+    @filter_deprecation
     def test_fv(self):
         assert_equal(np.fv(0.075, 20, -2000, 0, 0), 86609.362673042924)
 
+    @filter_deprecation
     def test_fv_decimal(self):
         assert_equal(np.fv(Decimal('0.075'), Decimal('20'), Decimal('-2000'), 0, 0),
                      Decimal('86609.36267304300040536731624'))
 
+    @filter_deprecation
     def test_pmt(self):
         res = np.pmt(0.08 / 12, 5 * 12, 15000)
         tgt = -304.145914
@@ -71,6 +90,7 @@ class TestFinancial(object):
         tgt = np.array([[-166.66667, -19311.258], [-626.90814, -19311.258]])
         assert_allclose(res, tgt)
 
+    @filter_deprecation
     def test_pmt_decimal(self):
         res = np.pmt(Decimal('0.08') / Decimal('12'), 5 * 12, 15000)
         tgt = Decimal('-304.1459143262052370338701494')
@@ -94,18 +114,22 @@ class TestFinancial(object):
         assert_equal(res[1][0], tgt[1][0])
         assert_equal(res[1][1], tgt[1][1])
 
+    @filter_deprecation
     def test_ppmt(self):
         assert_equal(np.round(np.ppmt(0.1 / 12, 1, 60, 55000), 2), -710.25)
 
+    @filter_deprecation
     def test_ppmt_decimal(self):
         assert_equal(np.ppmt(Decimal('0.1') / Decimal('12'), Decimal('1'), Decimal('60'), Decimal('55000')),
                      Decimal('-710.2541257864217612489830917'))
 
     # Two tests showing how Decimal is actually getting at a more exact result
     # .23 / 12 does not come out nicely as a float but does as a decimal
+    @filter_deprecation
     def test_ppmt_special_rate(self):
         assert_equal(np.round(np.ppmt(0.23 / 12, 1, 60, 10000000000), 8), -90238044.232277036)
 
+    @filter_deprecation
     def test_ppmt_special_rate_decimal(self):
         # When rounded out to 8 decimal places like the float based test, this should not equal the same value
         # as the float, substituted for the decimal
@@ -118,31 +142,38 @@ class TestFinancial(object):
         assert_equal(np.ppmt(Decimal('0.23') / Decimal('12'), 1, 60, Decimal('10000000000')),
                      Decimal('-90238044.2322778884413969909'))
 
+    @filter_deprecation
     def test_ipmt(self):
         assert_almost_equal(np.round(np.ipmt(0.1 / 12, 1, 24, 2000), 2), -16.67)
 
+    @filter_deprecation
     def test_ipmt_decimal(self):
         result = np.ipmt(Decimal('0.1') / Decimal('12'), 1, 24, 2000)
         assert_equal(result.flat[0], Decimal('-16.66666666666666666666666667'))
 
+    @filter_deprecation
     def test_nper(self):
         assert_almost_equal(np.nper(0.075, -2000, 0, 100000.),
                             21.54, 2)
 
+    @filter_deprecation
     def test_nper2(self):
         assert_almost_equal(np.nper(0.0, -2000, 0, 100000.),
                             50.0, 1)
 
+    @filter_deprecation
     def test_npv(self):
         assert_almost_equal(
             np.npv(0.05, [-15000, 1500, 2500, 3500, 4500, 6000]),
             122.89, 2)
 
+    @filter_deprecation
     def test_npv_decimal(self):
         assert_equal(
             np.npv(Decimal('0.05'), [-15000, 1500, 2500, 3500, 4500, 6000]),
             Decimal('122.894854950942692161628715'))
 
+    @filter_deprecation
     def test_mirr(self):
         val = [-4500, -800, 800, 800, 600, 600, 800, 800, 700, 3000]
         assert_almost_equal(np.mirr(val, 0.08, 0.055), 0.0666, 4)
@@ -156,6 +187,7 @@ class TestFinancial(object):
         val = [39000, 30000, 21000, 37000, 46000]
         assert_(np.isnan(np.mirr(val, 0.10, 0.12)))
 
+    @filter_deprecation
     def test_mirr_decimal(self):
         val = [Decimal('-4500'), Decimal('-800'), Decimal('800'), Decimal('800'),
                Decimal('600'), Decimal('600'), Decimal('800'), Decimal('800'),
@@ -174,6 +206,7 @@ class TestFinancial(object):
         val = [Decimal('39000'), Decimal('30000'), Decimal('21000'), Decimal('37000'), Decimal('46000')]
         assert_(np.isnan(np.mirr(val, Decimal('0.10'), Decimal('0.12'))))
 
+    @filter_deprecation
     def test_when(self):
         # begin
         assert_equal(np.rate(10, 20, -3500, 10000, 1),
@@ -238,6 +271,7 @@ class TestFinancial(object):
         assert_equal(np.nper(0.075, -2000, 0, 100000., 0),
                      np.nper(0.075, -2000, 0, 100000., 'end'))
 
+    @filter_deprecation
     def test_decimal_with_when(self):
         """Test that decimals are still supported if the when argument is passed"""
         # begin
@@ -312,6 +346,7 @@ class TestFinancial(object):
                      np.ipmt(Decimal('0.1') / Decimal('12'), Decimal('1'), Decimal('24'), Decimal('2000'),
                              Decimal('0'), 'end').flat[0])
 
+    @filter_deprecation
     def test_broadcast(self):
         assert_almost_equal(np.nper(0.075, -2000, 0, 100000., [0, 1]),
                             [21.5449442, 20.76156441], 4)
@@ -329,6 +364,7 @@ class TestFinancial(object):
                             [-74.998201, -75.62318601, -75.62318601,
                              -76.88882405, -76.88882405], 4)
 
+    @filter_deprecation
     def test_broadcast_decimal(self):
         # Use almost equal because precision is tested in the explicit tests, this test is to ensure
         # broadcast with Decimal is not broken.