property.rent-review Unreviewed

def rent_review(passing_rent: Money, base_index: int, review_index: int, collar_basis_points: Optional[int], cap_basis_points: Optional[int], upward_only: bool) -> RentReviewResult

RentReviewRule = Literal["index", "collar", "cap", "upward-only"]

@dataclass(frozen=True)
class RentReviewResult:
    """The reviewed rent, what the index alone would give, and which term decided it."""

    #: the rent from the review date
    new_rent: Money
    #: passing rent × reviewIndex ÷ baseIndex, before any collar, cap or floor
    index_rent: Money
    #: the index movement, rounded half-up; for display only
    index_change_basis_points: int
    #: the term that set the new rent
    applied_by: RentReviewRule

from fune.property.rent_review import rent_review  # property.rent-review@^1

from typing import Optional

from .math_round_div import round_div  ← from math.round-div ^1.0.0 · built alongside by fune
from .money_amount import Money, money  ← from money.amount ^1.0.0 · built alongside by fune
from .property_rent_review_types import RentReviewResult, RentReviewRule

_MAX_RENT = 1_000_000_000
_MAX_INDEX = 1_000_000


def _is_int(value: object) -> bool:
    return isinstance(value, int) and not isinstance(value, bool)


def _check_basis_points(name: str, value: Optional[int]) -> None:
    if value is None:
        return
    if not _is_int(value) or value <= -10000 or value > 100000:
        raise ValueError("%s must be an integer from -9999 to 100000, received %r" % (name, value))


def rent_review(
    passing_rent: Money,
    base_index: int,
    review_index: int,
    collar_basis_points: Optional[int],
    cap_basis_points: Optional[int],
    upward_only: bool,
) -> RentReviewResult:
    """The rent after an index-linked review, held between an optional collar
    and cap, and not below the passing rent when upward-only. Every comparison
    is on exact fractions and the rent is rounded half-up once."""
    if passing_rent.minor < 0 or passing_rent.minor > _MAX_RENT:
        raise ValueError(
            "passingRent must be between 0 and %d minor units, received %r" % (_MAX_RENT, passing_rent.minor)
        )
    for name, value in (("baseIndex", base_index), ("reviewIndex", review_index)):
        if not _is_int(value) or value <= 0 or value > _MAX_INDEX:
            raise ValueError("%s must be an integer from 1 to %d, received %r" % (name, _MAX_INDEX, value))
    _check_basis_points("collarBasisPoints", collar_basis_points)
    _check_basis_points("capBasisPoints", cap_basis_points)
    if collar_basis_points is not None and cap_basis_points is not None and collar_basis_points > cap_basis_points:
        raise ValueError("collar %d is above cap %d" % (collar_basis_points, cap_basis_points))
    p = passing_rent.minor
    # The multiplier as a fraction num/den: the index ratio, or 1 + collar/cap.
    num, den = review_index, base_index
    rule: RentReviewRule = "index"
    if cap_basis_points is not None and review_index * 10000 > base_index * (10000 + cap_basis_points):
        num, den, rule = 10000 + cap_basis_points, 10000, "cap"
    elif collar_basis_points is not None and review_index * 10000 < base_index * (10000 + collar_basis_points):
        num, den, rule = 10000 + collar_basis_points, 10000, "collar"
    if upward_only and num < den:
        num, den, rule = 1, 1, "upward-only"
    return RentReviewResult(
        new_rent=money(round_div(p * num, den, "half-up"), passing_rent.currency),
        index_rent=money(round_div(p * review_index, base_index, "half-up"), passing_rent.currency),
        index_change_basis_points=round_div((review_index - base_index) * 10000, base_index, "half-up"),
        applied_by=rule,
    )

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 2 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 property.rent-review

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

The whole function, every language, is one file too: property.rent-review-1.0.1.fune, 24,294 bytes, sha256 a99fdebf211fc8b8352ce6c5280a8c91645000b6a5b3b61bc5c61c419be7c331. It installs into a project of any language.

# fune: before property.rent-review

# fune: after property.rent-review

# fune: replace math.round-div in property.rent-review
# fune: replace money.amount in property.rent-review

# fune: step property.rent-review after <n|label>

More from the author

## How the rent is set

1. The index rent is passing rent × reviewIndex ÷ baseIndex. 2. If a cap is given and the index rises by more than the cap, the rent is passing rent × (1 + cap). 3. Else, if a collar is given and the index rises by less than the collar (or falls), the rent is passing rent × (1 + collar). 4. If upward-only and the result would be below the passing rent, the rent stays at the passing rent.

`appliedBy` says which of these set the rent (`index` when the index lands exactly on the cap or collar). Every comparison is made on exact fractions, and the rent is rounded half-up to the penny once, at the end. The index movement in basis points is returned for display only: applying a rounded percentage (6.42% for a 6.4166…% rise) gives a different rent from applying the index itself, and it is the index that the lease applies.

## Collar and cap are for the whole period

The collar and cap are the total increase allowed over the review period, not a yearly rate. A lease that says "between 1% and 4% a year, compounded, over five years" has a collar of (1.01^5 − 1) = 5.10% and a cap of (1.04^5 − 1) = 21.67%; work those out as the lease specifies (it may say how to round them) and pass the totals.

## Edge cases

- A collar above the cap is an error. A negative collar (a maximum fall) is allowed; so is a collar with no cap and a cap with no collar. - Upward-only with a falling index and no collar leaves the rent unchanged. - Leases that round the reviewed rent to the nearest pound, or to a multiple of £50, need that rounding applied to `newRent` afterwards.

## Limits

Passing rent up to £10,000,000 (1,000,000,000 minor units), indices from 1 to 1,000,000, collar and cap from −9,999 to 100,000 basis points, which keeps all the arithmetic exact in every language.

## Before you rely on this

**Not professional advice.** This capability calculates property figures from published rules. It is a software component for developers, not legal or 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 conveyancer or tax adviser 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 conveyancer or tax adviser 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