lending.apr Unreviewed

def apr(advances: Sequence[CreditFlow], repayments: Sequence[CreditFlow], periods_per_year: int) -> AprResult

@dataclass(frozen=True)
class CreditFlow:
    """An amount paid at a time measured from the first drawdown."""

    #: whole periods after the first drawdown, 0 or more
    period: int
    #: greater than zero
    amount: Money

@dataclass(frozen=True)
class AprResult:
    """The APR as disclosed, and a finer figure for checking."""

    #: the APR to one decimal place, in basis points: 1990 = 19.9%
    basis_points: int
    #: as disclosed: "19.9%"
    display: str
    #: the APR to two decimal places, half-up, for audit
    precise_basis_points: int

from fune.lending.apr import apr  # lending.apr@^1

from typing import Dict, List, Sequence, Tuple

from .lending_apr_types import AprResult, CreditFlow
from .math_fractional_power import FIXED_SCALE, pow_fixed  ← from math.fractional-power ^1.0.0 · built alongside by fune

_UNITS = (1, 2, 4, 12, 52, 365)

#: 10^10: the APR is settled to ten decimal places of the rate before the disclosure rounding.
_SETTLE = 10 ** 10

_NOT_UNIQUE = "cash flows must be advances first and repayments after: the APR would not be unique"


def _net_flows(advances: Sequence[CreditFlow], repayments: Sequence[CreditFlow]) -> List[Tuple[int, int]]:
    """Net cash flow per period (repayments minus advances), in period order,
    after checking every flow."""
    if len(advances) == 0:
        raise ValueError("advances must not be empty")
    if len(repayments) == 0:
        raise ValueError("repayments must not be empty")
    currency = advances[0].amount.currency
    net: Dict[int, int] = {}

    def add(flow: CreditFlow, sign: int) -> None:
        if flow.amount.currency != currency:
            raise ValueError("currency mismatch: %s and %s" % (currency, flow.amount.currency))
        if flow.amount.minor <= 0:
            raise ValueError("every amount must be greater than zero, received %r" % (flow.amount.minor,))
        p = flow.period
        if isinstance(p, bool) or not isinstance(p, int) or p < 0 or p > 36500:
            raise ValueError("periods must be between 0 and 36500, received %r" % (p,))
        net[p] = net.get(p, 0) + sign * flow.amount.minor

    for flow in advances:
        add(flow, -1)
    earliest = min(flow.period for flow in advances)
    for flow in repayments:
        add(flow, 1)
    if earliest != 0:
        raise ValueError("time is measured from the first drawdown: the earliest advance must be at period 0")
    return sorted((p, a) for p, a in net.items() if a != 0)


def apr(advances: Sequence[CreditFlow], repayments: Sequence[CreditFlow], periods_per_year: int) -> AprResult:
    """The APR by the total charge for credit equation (FCA Handbook CONC
    App 1.2.6R): the rate X at which the drawdowns, discounted to the first
    drawdown at (1 + X)^-t, equal the repayments discounted the same way, with
    t in years.

    Solved by bisection on the per-period discount factor
    v = (1 + X)^(-1/periods_per_year) in 18-place fixed point, which only
    needs whole powers of v, then X = v^-periods_per_year - 1, settled to ten
    decimal places and rounded to one decimal place of a percent as
    App 1.2.6(3)(f) requires.
    """
    if isinstance(periods_per_year, bool) or periods_per_year not in _UNITS:
        raise ValueError("periodsPerYear must be 1, 2, 4, 12, 52 or 365, received %r" % (periods_per_year,))
    flows = _net_flows(advances, repayments)
    # One change of sign, advances then repayments, is what makes the root unique.
    seen_positive = False
    for _, amount in flows:
        if amount > 0:
            seen_positive = True
        elif seen_positive:
            raise ValueError(_NOT_UNIQUE)
    if len(flows) == 0 or flows[0][1] > 0:
        raise ValueError(_NOT_UNIQUE)
    total = sum(amount for _, amount in flows)
    if total < 0:
        raise ValueError("the repayments total less than the credit: the APR would be negative")
    rate = 0
    if total > 0:

        def value(v: int) -> int:
            return sum(amount * pow_fixed(v, period) for period, amount in flows)

        lo, hi = 0, FIXED_SCALE
        while hi - lo > 1:
            mid = (lo + hi) // 2
            if value(mid) >= 0:
                hi = mid
            else:
                lo = mid
        growth = pow_fixed(hi, periods_per_year)
        if growth == 0:
            raise ValueError("the APR is too large to compute")
        rate = max(0, (FIXED_SCALE * FIXED_SCALE) // growth - FIXED_SCALE)
    # Settle the solver's last-digit noise, then round as the rule says.
    settled = (2 * rate * _SETTLE + FIXED_SCALE) // (2 * FIXED_SCALE)
    tenths = (2 * settled * 1000 + _SETTLE) // (2 * _SETTLE)
    precise = (2 * settled * 10000 + _SETTLE) // (2 * _SETTLE)
    return AprResult(
        basis_points=tenths * 10,
        display="%d.%d%%" % (tenths // 10, tenths % 10),
        precise_basis_points=precise,
    )

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 3 dependencies, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add lending.apr

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./lending.apr-1.0.1-python.fune, or fetch it from a terminal with fune pull lending.apr@1.0.1:python.

The whole function, every language, is one file too: lending.apr-1.0.1.fune, 49,352 bytes, sha256 dd7bb6a99d431966dc31b1c9bb87c668e459af3781904ae26a062587a8944735. It installs into a project of any language.

# fune: before lending.apr

# fune: after lending.apr

# fune: replace math.big-integer in lending.apr
# fune: replace math.fractional-power in lending.apr
# fune: replace money.amount in lending.apr

# fune: step lending.apr after <n|label>

More from the author

## The rule

FCA Handbook, CONC App 1.2.6R, "Total charge for credit rules for other agreements" (App 1.1 covers certain agreements secured on land). These rules took over from the Consumer Credit (Total Charge for Credit) Regulations 2010 when consumer credit moved to the FCA in 2014:

Σ C_k (1 + X)^(−t_k) = Σ D_l (1 + X)^(−s_l)

drawdowns C_k at t_k years, repayments and charges D_l at s_l years, both measured from the first drawdown; X is the APR. App 1.2.6(3): a year is 365 days (366 in a leap year), 52 weeks or 12 equal months; and "the result of the calculation shall be expressed with an accuracy of at least one decimal place; if the figure at the following decimal place is greater than or equal to 5, the figure at that particular decimal place shall be increased by one." Source: https://www.handbook.fca.org.uk/handbook/CONC/App/1/2.html, read 2026-09-23.

## Inputs

Each flow is a whole number of periods after the first drawdown, and `periodsPerYear` says what a period is: 12 (months), 52 (weeks), 365 (days), 4, 2 or 1. So a monthly loan is described in months and t = months / 12, and a 30-day loan in days with t = days / 365. The earliest advance must be at period 0. Fees and charges the borrower pays are repayments, at the period they are paid (an arrangement fee at drawdown is a repayment at period 0). Every amount must be positive and in one currency.

## How it is solved

With v = (1 + X)^(−1/periodsPerYear), the equation becomes a polynomial in v with whole exponents: Σ (net flow at t) × v^t = 0. It is solved by bisection on v between 0 and 1 in 18-place fixed point (math.fractional-power's `powFixed`, the same floors in the same order in every language), about 60 halvings until v is pinned to 10^-18. Then X = v^(−periodsPerYear) − 1.

Precision: the unrounded APR is accurate to around 10^-14. It is first settled to ten decimal places of the rate (10^-8 of a percentage point), which removes the solver's last-digit noise so an APR of exactly 12.65% is 12.65 and not 12.6499999, and then rounded as App 1.2.6(3)(f) says: to one decimal place, rounding up when the second decimal place is 5 or more. That is half-up, so 12.65% is 12.7% and 12.64% is 12.6%. `preciseBasisPoints` gives the settled APR to two decimal places (half-up) for checking.

The root is unique when the flows change sign once: all drawdowns (net) come before all repayments (net). Flows that interleave, such as a second drawdown after a repayment, can have more than one solution and are refused rather than answered with whichever root bisection finds. Repayments that total less than the credit (a negative APR) are refused; exactly equal totals are 0.0%.

## What a specialist should check

- The leap-year rule: "366 days for leap years" is not applied. Day-based flows use t = days / 365 throughout, the common industry reading; a specialist should confirm that for agreements spanning 29 February. - Which charges go into the total charge for credit, and the assumptions of CONC App 1.2 (for example for running-account credit and the assumed drawdown and repayment patterns of App 1.2.7 onwards) are the caller's. This computes the rate from the flows it is given. - Whether whole periods are fine enough: a first payment 45 days after drawdown on a monthly loan must be described in days, with every flow in days.

## Before you rely on this

**Not professional advice.** This capability calculates lending figures from published rules. It is a software component for developers, not financial advice. Rules change and every rate here has an effective date. Check that the dates cover your case. Verify results against the official sources listed above, and have a consumer-credit compliance specialist review how you use it, before anyone relies on the output. Provided "as is" under its licence, without warranty.

**Unreviewed.** This capability's implementations agree in every language and pass its published test vectors, which were worked out from the official sources cited. But no qualified consumer-credit compliance specialist has yet checked those vectors, or confirmed that the capability covers the cases it claims. Treat it as a draft. Do not use it for real people, money or decisions without your own expert review. Once a qualified reviewer signs off, this notice is replaced with their name, qualification and the date. Each new version needs fresh sign-off.

1.0.1 marks it unreviewed. The code and the tests are unchanged.

Files