invest.portfolio-weights Unreviewed

def portfolio_weights(holdings: Sequence[PortfolioHolding]) -> PortfolioWeights

@dataclass(frozen=True)
class PortfolioHolding:
    """One position and the share of the portfolio it should be."""

    #: a fund code, ticker or asset class; unique
    id: str
    #: market value now, 0 or more
    value: Money
    #: the intended weight, 0 to 10000
    target_basis_points: int

@dataclass(frozen=True)
class HoldingWeight:
    """Where one holding stands against its target."""

    id: str
    value: Money
    #: value / total, half-up to a whole basis point
    weight_basis_points: int
    target_basis_points: int
    #: weight minus target from the exact values, half away from zero; positive is overweight
    drift_basis_points: int
    #: total x target, half-up to a minor unit
    target_value: Money
    #: value minus targetValue; positive is overweight
    drift_value: Money

@dataclass(frozen=True)
class PortfolioWeights:
    """The portfolio total and every holding against its target."""

    total: Money
    holdings: List[HoldingWeight]
    #: the largest drift either way, for threshold rebalancing
    max_abs_drift_basis_points: int

from fune.invest.portfolio_weights import portfolio_weights  # invest.portfolio-weights@^1

from typing import List, Sequence, Set

from .invest_portfolio_weights_types import HoldingWeight, PortfolioHolding, PortfolioWeights
from .money_amount import money  ← from money.amount ^1.0.0 · built alongside by fune


def _round_half_away(n: int, d: int) -> int:
    """n / d rounded half away from zero; d > 0."""
    a = -n if n < 0 else n
    q, r = divmod(a, d)
    if 2 * r >= d:
        q += 1
    return -q if n < 0 else q


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


def portfolio_weights(holdings: Sequence[PortfolioHolding]) -> PortfolioWeights:
    """Each holding's weight, target and drift. Everything is derived from the
    integer values and rounded once at the end, so a weight is never computed
    from another rounded figure."""
    if len(holdings) == 0:
        raise ValueError("holdings must not be empty")
    currency = holdings[0].value.currency
    seen: Set[str] = set()
    total = 0
    targets = 0
    for h in holdings:
        if h.id in seen:
            raise ValueError('duplicate holding id "%s"' % h.id)
        seen.add(h.id)
        if h.value.currency != currency:
            raise ValueError("currency mismatch: %s and %s" % (currency, h.value.currency))
        if not _is_int(h.value.minor) or h.value.minor < 0:
            raise ValueError(
                'holding values must be whole minor units, 0 or more; received %s for "%s"' % (h.value.minor, h.id)
            )
        t = h.target_basis_points
        if not _is_int(t) or t < 0 or t > 10000:
            raise ValueError(
                'targetBasisPoints must be a whole number from 0 to 10000; received %s for "%s"' % (t, h.id)
            )
        total += h.value.minor
        targets += t
    if targets != 10000:
        raise ValueError("targets must sum to 10000 basis points, received %d" % targets)
    if total == 0:
        raise ValueError("the portfolio total must be greater than zero")

    max_abs = 0
    rows: List[HoldingWeight] = []
    for h in holdings:
        value = h.value.minor
        target = h.target_basis_points
        drift = _round_half_away(value * 10000 - target * total, total)
        target_value = _round_half_away(total * target, 10000)
        max_abs = max(max_abs, abs(drift))
        rows.append(
            HoldingWeight(
                id=h.id,
                value=money(value, currency),
                weight_basis_points=_round_half_away(value * 10000, total),
                target_basis_points=target,
                drift_basis_points=drift,
                target_value=money(target_value, currency),
                drift_value=money(value - target_value, currency),
            )
        )
    return PortfolioWeights(total=money(total, currency), holdings=rows, max_abs_drift_basis_points=max_abs)

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 1 dependency, 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 invest.portfolio-weights

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

The whole function, every language, is one file too: invest.portfolio-weights-1.0.1.fune, 35,377 bytes, sha256 71b36d3c97468580a8343302d7f638bdd4a8437780e9831038a47dd616f9607e. It installs into a project of any language.

# fune: before invest.portfolio-weights

# fune: after invest.portfolio-weights

# fune: replace money.amount in invest.portfolio-weights

# fune: step invest.portfolio-weights after <n|label>

More from the author

- **Integer arithmetic throughout.** Values are `Money` in minor units and every ratio is computed from them exactly (with 128-bit or arbitrary-size integers inside, so a portfolio of billions does not overflow), then rounded once. - **Each weight is rounded on its own**, half-up to a whole basis point. The weights therefore need not add up to exactly 10000: three equal holdings are 3333 bp each. Forcing them to sum (largest remainder) would move one holding's weight by a basis point it does not have, and the drift of that holding would be wrong. If you need weights that sum for a pie chart, use `money.allocate` on the values. - **Drift is computed from the exact values**, (value x 10000 - target x total) / total, and rounded once, half away from zero. At an exact half basis point this can differ by one from `weightBasisPoints - targetBasisPoints`, which rounds twice. - **`driftValue` is the money to sell (positive) or buy (negative)** to hit the target exactly, before any whole-unit or minimum-trade constraint; `invest.rebalance` applies those.

## Edge cases

- Targets must sum to exactly 10000. A holding may have a target of 0 (something to sell out of) and a holding may be worth 0 (something to buy). - A portfolio worth nothing has no weights and is an error, as are negative values (short positions are out of scope), duplicate ids, mixed currencies and an empty list.

## Before you rely on this

**Not professional advice.** This capability calculates investment 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 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 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