From a52eb5654211bf43e7306de4eb88a7da8d12d304 Mon Sep 17 00:00:00 2001 From: Ryan Xiao Wei Lin Date: Sat, 26 Sep 2026 22:28:30 +0100 Subject: [PATCH 1/4] DOC: clarify pmt cash-flow signs --- numpy_financial/_financial.py | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/numpy_financial/_financial.py b/numpy_financial/_financial.py index 1adbbea..47ec483 100644 --- a/numpy_financial/_financial.py +++ b/numpy_financial/_financial.py @@ -317,9 +317,10 @@ def pmt(rate, nper, pv, fv: Any = 0, when: _When = 'end'): nper : array_like Number of compounding periods pv : array_like - Present value + Present value. For a loan, the amount received is positive. fv : array_like, optional - Future value (default = 0) + Future cash balance (default = 0). For a loan with positive `pv`, + use a negative value for a balance that remains to be repaid. when : {{'begin', 1}, {'end', 0}}, {string, int} When payments are due ('begin' (1) or 'end' (0)) @@ -345,6 +346,11 @@ def pmt(rate, nper, pv, fv: Any = 0, when: _When = 'end'): for ``pmt``. + Cash received is positive and cash paid out is negative. For example, + from a borrower's perspective, the loan principal `pv` is positive and + the payments returned by `pmt` are negative. A remaining loan balance + is represented by a negative `fv`, since it must still be paid out. + Note that computing a monthly mortgage payment is only one use for this function. For example, pmt returns the periodic deposit one must make to achieve a specified @@ -377,6 +383,18 @@ def pmt(rate, nper, pv, fv: Any = 0, when: _When = 'end'): today, a monthly payment of $1,854.02 would be required. Note that this example illustrates usage of `fv` having a default value of 0. + For a $200,000 loan over 30 years at an annual interest rate of 5%, + compounded monthly, compare paying off the loan with leaving $50,000 + to be repaid at the end of the term: + + >>> print(f"{npf.pmt(0.05/12, 12*30, 200000):.2f}") + -1073.64 + >>> print(f"{npf.pmt(0.05/12, 12*30, 200000, fv=-50000):.2f}") + -1013.57 + + Leaving a balance reduces the monthly payment. The negative `fv` + represents the $50,000 still owed after the regular payments. + """ when = _convert_when(when) (rate, nper, pv, fv, when) = map(np.array, [rate, nper, pv, fv, when]) From ad8b847bfb81e9edfb274ac8c0a1a99e5d1bdfb8 Mon Sep 17 00:00:00 2001 From: Ryan Xiao Wei Lin Date: Sat, 26 Sep 2026 22:33:24 +0100 Subject: [PATCH 2/4] DOC: simplify remaining loan balance example --- numpy_financial/_financial.py | 20 +++++--------------- 1 file changed, 5 insertions(+), 15 deletions(-) diff --git a/numpy_financial/_financial.py b/numpy_financial/_financial.py index 47ec483..6fe085c 100644 --- a/numpy_financial/_financial.py +++ b/numpy_financial/_financial.py @@ -346,11 +346,6 @@ def pmt(rate, nper, pv, fv: Any = 0, when: _When = 'end'): for ``pmt``. - Cash received is positive and cash paid out is negative. For example, - from a borrower's perspective, the loan principal `pv` is positive and - the payments returned by `pmt` are negative. A remaining loan balance - is represented by a negative `fv`, since it must still be paid out. - Note that computing a monthly mortgage payment is only one use for this function. For example, pmt returns the periodic deposit one must make to achieve a specified @@ -383,17 +378,12 @@ def pmt(rate, nper, pv, fv: Any = 0, when: _When = 'end'): today, a monthly payment of $1,854.02 would be required. Note that this example illustrates usage of `fv` having a default value of 0. - For a $200,000 loan over 30 years at an annual interest rate of 5%, - compounded monthly, compare paying off the loan with leaving $50,000 - to be repaid at the end of the term: - - >>> print(f"{npf.pmt(0.05/12, 12*30, 200000):.2f}") - -1073.64 - >>> print(f"{npf.pmt(0.05/12, 12*30, 200000, fv=-50000):.2f}") - -1013.57 + For a $100 loan with no interest, ten payments of $8 leave $20 owed. + Use ``fv=-20`` for this remaining debt; payments are negative because + they represent money paid out: - Leaving a balance reduces the monthly payment. The negative `fv` - represents the $50,000 still owed after the regular payments. + >>> float(npf.pmt(0, 10, 100, fv=-20)) + -8.0 """ when = _convert_when(when) From 91b727b0f970798fce7cede96d33d297b9399a63 Mon Sep 17 00:00:00 2001 From: Ryan Xiao Wei Lin Date: Thu, 1 Oct 2026 20:44:54 +0100 Subject: [PATCH 3/4] DOC: address review of cash-flow sign explanations --- numpy_financial/_financial.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/numpy_financial/_financial.py b/numpy_financial/_financial.py index 6fe085c..278883d 100644 --- a/numpy_financial/_financial.py +++ b/numpy_financial/_financial.py @@ -2,6 +2,10 @@ patterned after spreadsheet computations. +Cash received is positive and cash paid out is negative, from a consistent +perspective. For a borrower, loan proceeds are positive and repayments are +negative; for a lender, the signs are reversed. + There is some complexity in each function so that the functions behave like ufuncs with broadcasting and being able to be called with scalars @@ -317,9 +321,10 @@ def pmt(rate, nper, pv, fv: Any = 0, when: _When = 'end'): nper : array_like Number of compounding periods pv : array_like - Present value. For a loan, the amount received is positive. + Present value. Cash received is positive and cash paid out is + negative. For a borrower, the loan amount is positive. fv : array_like, optional - Future cash balance (default = 0). For a loan with positive `pv`, + Future value (default = 0). For a loan with positive `pv`, use a negative value for a balance that remains to be repaid. when : {{'begin', 1}, {'end', 0}}, {string, int} When payments are due ('begin' (1) or 'end' (0)) From fe376f68a027b4c4660a8ce99606a5fd996081d9 Mon Sep 17 00:00:00 2001 From: Ryan Xiao Wei Lin Date: Thu, 1 Oct 2026 20:46:32 +0100 Subject: [PATCH 4/4] DOC: simplify cash-flow convention wording --- numpy_financial/_financial.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/numpy_financial/_financial.py b/numpy_financial/_financial.py index 278883d..08220b2 100644 --- a/numpy_financial/_financial.py +++ b/numpy_financial/_financial.py @@ -2,9 +2,9 @@ patterned after spreadsheet computations. -Cash received is positive and cash paid out is negative, from a consistent -perspective. For a borrower, loan proceeds are positive and repayments are -negative; for a lender, the signs are reversed. +Cash received is positive and cash paid out is negative. For a borrower, +loan proceeds are positive and repayments are negative; for a lender, +the signs are reversed. There is some complexity in each function so that the functions behave like ufuncs with