invest.dividend-yield Unreviewed

def dividend_yield(price: Money, trailing_dividends: Sequence[Money], forward_dividend: Money, payments_per_year: int) -> DividendYield

@dataclass(frozen=True)
class DividendYield:
    """Both yields, and the annual amounts they were computed from."""

    #: the trailing dividends added up
    trailing_annual: Money
    #: forwardDividend x paymentsPerYear
    forward_annual: Money
    #: trailingAnnual / price, half-up; 350 = 3.5%
    trailing_basis_points: int
    #: forwardAnnual / price, half-up
    forward_basis_points: int

from fune.invest.dividend_yield import dividend_yield  # invest.dividend-yield@^1

from typing import Sequence

from .invest_dividend_yield_types import DividendYield
from .money_amount import Money, money  ← from money.amount ^1.0.0 · built alongside by fune


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


def _basis_points(amount: int, price: int) -> int:
    """amount x 10000 / price, half-up; both 0 or more, price > 0."""
    q, r = divmod(amount * 10000, price)
    return q + 1 if 2 * r >= price else q


def dividend_yield(
    price: Money, trailing_dividends: Sequence[Money], forward_dividend: Money, payments_per_year: int
) -> DividendYield:
    """Trailing yield from the dividends paid in the last twelve months, and
    forward yield from the latest regular dividend annualised, both over the
    current price."""
    currency = price.currency
    if not _is_int(price.minor) or price.minor <= 0:
        raise ValueError("price must be whole minor units greater than zero; received %s" % (price.minor,))
    if not _is_int(payments_per_year) or payments_per_year < 1 or payments_per_year > 52:
        raise ValueError("paymentsPerYear must be a whole number from 1 to 52; received %s" % (payments_per_year,))
    for dividend in list(trailing_dividends) + [forward_dividend]:
        if dividend.currency != currency:
            raise ValueError("currency mismatch: %s and %s" % (currency, dividend.currency))
        if not _is_int(dividend.minor) or dividend.minor < 0:
            raise ValueError("dividends must be whole minor units, 0 or more; received %s" % (dividend.minor,))
    trailing = sum(d.minor for d in trailing_dividends)
    forward = forward_dividend.minor * payments_per_year
    return DividendYield(
        trailing_annual=money(trailing, currency),
        forward_annual=money(forward, currency),
        trailing_basis_points=_basis_points(trailing, price.minor),
        forward_basis_points=_basis_points(forward, price.minor),
    )

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.dividend-yield

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

The whole function, every language, is one file too: invest.dividend-yield-1.0.1.fune, 22,396 bytes, sha256 f1cd722e5b8f802d33186c5cc93f3723a0300ae96aaea140bad42be8b9f5fcac. It installs into a project of any language.

# fune: before invest.dividend-yield

# fune: after invest.dividend-yield

# fune: replace money.amount in invest.dividend-yield

# fune: step invest.dividend-yield after <n|label>

More from the author

Both are rounded half-up to a whole basis point, from exact integer arithmetic.

## Pence and fractions of a penny

`Money` holds whole minor units, but UK dividends are often declared in fractions of a penny (11.8p). A yield is a ratio, so give the price and the dividends for a lot instead: per 100 shares, 11.8p is 1180 and a price of 1,234.56p is 123456. The yields are the same; the annual amounts are per lot.

## What it does not do

It does not decide which dividends fall in the last twelve months (pass the ones that do, by ex-dividend or payment date as your policy says), convert currencies, or gross up for tax credits. Price and dividends must be in one currency.

## Errors

A price of 0 or less, a negative or fractional dividend, `paymentsPerYear` outside 1-52, and mixed currencies.

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