property.service-charge-apportion Unreviewed

def apportion_service_charge(total: Money, units: Sequence[ServiceChargeUnit], basis: ApportionBasis) -> List[ServiceChargeLine]

ApportionBasis = Literal["fraction", "floor-area", "percentage"]

@dataclass(frozen=True)
class ServiceChargeUnit:
    """One unit and its share, as its lease states it."""

    #: the flat or unit's name
    unit: str
    #: fraction: the numerator; floor-area: the area in any one integer unit; percentage: basis points
    share: int
    #: fraction: the denominator; null for floor-area and percentage
    of: Optional[int]

@dataclass(frozen=True)
class ServiceChargeLine:
    """What one unit pays."""

    unit: str
    charge: Money

from fune.property.service_charge_apportion import apportion_service_charge  # property.service-charge-apportion@^1

from typing import List, Sequence

from .math_gcd_lcm import lcm  ← from math.gcd-lcm ^1.0.0 · built alongside by fune
from .money_allocate import allocate  ← from money.allocate ^1.0.0 · built alongside by fune
from .money_amount import Money  ← from money.amount ^1.0.0 · built alongside by fune
from .property_service_charge_apportion_types import ApportionBasis, ServiceChargeLine, ServiceChargeUnit

_MAX_SAFE = 2**53 - 1


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


def apportion_service_charge(
    total: Money, units: Sequence[ServiceChargeUnit], basis: ApportionBasis
) -> List[ServiceChargeLine]:
    """Share a service charge between units by lease fraction, floor area or
    fixed percentage. Every share becomes an integer weight, and
    money.allocate does the one split, so the lines always add up to the
    total exactly."""
    if basis not in ("fraction", "floor-area", "percentage"):
        raise ValueError('unknown basis "%s": use fraction, floor-area or percentage' % (basis,))
    if len(units) == 0:
        raise ValueError("units must not be empty")
    for u in units:
        if not _is_int(u.share) or u.share < 0 or u.share > _MAX_SAFE:
            raise ValueError('unit "%s": share must be a whole number, zero or more, received %r' % (u.unit, u.share))
        if basis == "fraction":
            if u.of is None or not _is_int(u.of) or u.of <= 0 or u.of > _MAX_SAFE:
                raise ValueError('unit "%s": a fraction needs a denominator "of" greater than zero' % (u.unit,))
        elif u.of is not None:
            raise ValueError('unit "%s": "of" is only for the fraction basis' % (u.unit,))
    if basis == "fraction":
        common = 1
        for u in units:
            common = lcm(common, u.of)
        weights = [u.share * (common // u.of) for u in units]
        total_weight = sum(weights)
        if total_weight > _MAX_SAFE:
            raise ValueError("the fractions are too fine to apportion exactly")
        if total_weight != common:
            raise ValueError("the fractions add up to %d/%d, not exactly 1" % (total_weight, common))
    else:
        weights = [u.share for u in units]
        total_weight = sum(weights)
        if basis == "percentage" and total_weight != 10000:
            raise ValueError("the percentages add up to %d basis points, not 10000" % (total_weight,))
        if total_weight == 0:
            raise ValueError("the floor areas add up to zero")
    if total_weight > _MAX_SAFE or abs(total.minor) * total_weight > _MAX_SAFE:
        raise ValueError("the fractions are too fine to apportion exactly")
    parts = allocate(total, weights)
    return [ServiceChargeLine(unit=u.unit, charge=parts[i]) for i, u in enumerate(units)]

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 property.service-charge-apportion

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

The whole function, every language, is one file too: property.service-charge-apportion-1.0.1.fune, 26,765 bytes, sha256 5e9bff52e0f5eefba43b53d17b7c1b4ee788f4c0b2362f3c0ed1410b67baeaf1. It installs into a project of any language.

# fune: before property.service-charge-apportion

# fune: after property.service-charge-apportion

# fune: replace math.gcd-lcm in property.service-charge-apportion
# fune: replace money.allocate in property.service-charge-apportion
# fune: replace money.amount in property.service-charge-apportion

# fune: step property.service-charge-apportion after <n|label>

More from the author

- **fraction**: "one-third", "3/20ths". Each unit gives `share` over `of`. The fractions must add up to exactly 1, since a lease scheme that does not recover the whole cost (or recovers more) is something to raise with the landlord, not to paper over. - **floor-area**: each unit's area, in any one integer unit (square feet, square metres, or square metres × 100 for 0.01 m² precision). The share is the unit's area over the total area. - **percentage**: basis points (2500 = 25%), adding up to exactly 10,000.

## Exact to the penny

Each unit's exact share is total × share, and the pennies left over after rounding every share down are given one at a time to the units with the largest remainders (ties to the earlier unit), by `money.allocate`. So a £100.01 charge split 1/3, 1/6, 1/2 is £33.34, £16.67 and £50.00. Rounding each share to the nearest penny separately would give £33.34, £16.67 and £50.01: £100.02, a penny that was never spent.

Fractions are brought to a common denominator exactly (with `math.gcd-lcm`), never converted to decimals.

## Edge cases

- A unit with a zero share pays nothing but still gets a line. - A negative total (a surplus refunded, a credit) is shared the same way. - `of` must be null unless the basis is fraction, and must be given (and be positive) when it is. - The shares' total, times the service charge in minor units, must stay below 2^53, so that every language computes the same split exactly. Denominators whose lowest common multiple is too large to share a charge that precisely are refused rather than approximated.

## What it does not do

It does not weight different cost heads differently (a lift schedule that excludes ground-floor flats is a second call with its own units), cap any unit's contribution, or handle reserve fund contributions separately.

## 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