marketmyna 0.2.0__py3-none-any.whl

marketmyna/services/dcf_model.py

@@ -0,0 +1,194 @@
+"""The DCF as an Excel workbook with live formulas, so the model can be
+audited and changed outside MarketMyna.
+
+Follows the model-builder conventions of anthropics/financial-services
+(Apache-2.0): every calculation cell is a formula, never a typed number;
+inputs are blue and labelled with their source or as an assumption; a check
+row flags an impossible set-up; a sensitivity grid recomputes the value per
+share for other discount and terminal rates (plain formulas, no Excel data
+table, so LibreOffice and Google Sheets read it too).
+
+Same two-stage model as services/dcf.py and frontend/src/lib/dcf.ts: free
+cash flow grows at the chosen rate for 5 years, fades in a straight line to
+the terminal rate by year 10, then a Gordon-growth terminal value.
+"""
+
+from __future__ import annotations
+
+import io
+from datetime import date
+from typing import Optional
+
+from openpyxl import Workbook
+from openpyxl.styles import Alignment, Font, PatternFill
+from openpyxl.utils import get_column_letter
+
+BLUE = Font(color="1F4FBF")  # inputs
+BOLD = Font(bold=True)
+HEAD = Font(bold=True, color="FFFFFF")
+HEAD_FILL = PatternFill("solid", fgColor="2F3E57")
+KEY_FILL = PatternFill("solid", fgColor="EAF1FB")
+MONEY = '#,##0;[Red]-#,##0'
+PER_SHARE = '#,##0.00;[Red]-#,##0.00'
+PCT = '0.0%'
+
+YEARS = 10
+HIGH = 5
+COLS = [get_column_letter(c) for c in range(3, 3 + YEARS)]  # C..L = years 1..10
+
+
+def _row(ws, r: int, label: str, value, fmt: Optional[str] = None, note: str = "", font=None):
+    ws.cell(r, 1, label)
+    c = ws.cell(r, 2, value)
+    if fmt:
+        c.number_format = fmt
+    if font:
+        c.font = font
+    if note:
+        ws.cell(r, 3, note).font = Font(italic=True, color="666666")
+    return c
+
+
+def _grid_formula(w: str, t: str, high: str) -> str:
+    """Value per share at discount w and terminal growth t: years 1-5 are as
+    projected; years 6-10 fade to *this* terminal rate (as the page's sliders
+    do), then the terminal value."""
+    pv = [f"SUMPRODUCT($C$16:${high}$16/(1+{w})^$C$14:${high}$14)"]
+    flow = f"${high}$16"
+    fade = YEARS - HIGH
+    for k in range(1, fade + 1):
+        flow = f"{flow}*(1+$B$7+({t}-$B$7)*{k}/{fade})"
+        pv.append(f"{flow}/(1+{w})^{HIGH + k}")
+    pv.append(f"{flow}*(1+{t})/({w}-{t})/(1+{w})^{YEARS}")
+    return f"=IF({w}>{t},({'+'.join(pv)}+$B$10)/$B$11,\"n/a\")"
+
+
+def build(data: dict, growth: Optional[float] = None, discount: Optional[float] = None,
+          terminal: Optional[float] = None) -> bytes:
+    """data: services/dcf.build() output with a "dcf" block. Rates default to the page's defaults."""
+    d = data.get("dcf")
+    if not d:
+        raise ValueError(data.get("note") or "No DCF for this stock")
+    dflt = d["defaults"]
+    growth = dflt["growth"] if growth is None else growth
+    discount = dflt["discount"] if discount is None else discount
+    terminal = dflt["terminal"] if terminal is None else terminal
+    ccy = data.get("currency") or ""
+
+    wb = Workbook()
+    ws = wb.active
+    ws.title = "DCF"
+    ws.column_dimensions["A"].width = 34
+    ws.column_dimensions["B"].width = 20
+    for col in COLS:
+        ws.column_dimensions[col].width = 15
+
+    ws["A1"] = f"{data.get('name') or data['symbol']} ({data['symbol']}) - discounted cash flow"
+    ws["A1"].font = Font(bold=True, size=14)
+    ws["A2"] = (f"Built by MarketMyna on {date.today().isoformat()} from {data.get('source', 'company filings')}. "
+                f"Amounts in {ccy}. Blue cells are inputs: change them and everything recalculates.")
+    ws["A3"] = "A model, not a forecast or a recommendation: the result is only as good as the assumptions."
+    ws["A3"].font = Font(italic=True, color="666666")
+
+    # ---------------------------------------------------------------- inputs (rows 5-11)
+    ws["A5"] = "Inputs"
+    ws["A5"].font = BOLD
+    conv = f", converted from {d['converted_from']}" if d.get("converted_from") else ""
+    _row(ws, 6, f"Base free cash flow ({ccy})", d["base_fcf"], MONEY,
+         f"Operating cash flow minus capex and stock-based compensation, {d.get('base_label', 'latest year')}{conv}", BLUE)
+    _row(ws, 7, f"Growth a year, years 1-{HIGH}", growth, PCT,
+         "[ASSUMPTION] page default = recent revenue growth, capped 0-15%", BLUE)
+    _row(ws, 8, "Discount rate", discount, PCT, "[ASSUMPTION] the return you require a year", BLUE)
+    _row(ws, 9, "Terminal growth", terminal, PCT, "[ASSUMPTION] growth a year after year 10, for ever", BLUE)
+    _row(ws, 10, f"Net cash: cash and investments minus debt ({ccy})", d["net_cash"], MONEY,
+         "Latest balance sheet: cash, short-term and long-term investments, minus total debt", BLUE)
+    _row(ws, 11, "Shares outstanding", d["shares"], '#,##0', "Market data feed", BLUE)
+    _row(ws, 12, f"Share price ({ccy})", data.get("price"), PER_SHARE, "Market data feed, when the model was built", BLUE)
+
+    # ---------------------------------------------------------------- projection (rows 14-18)
+    ws["A14"] = "Year"
+    ws["A15"] = "Growth"
+    ws["A16"] = f"Free cash flow ({ccy})"
+    ws["A17"] = "Discount factor"
+    ws["A18"] = f"Present value ({ccy})"
+    for c in ("A14", "A15", "A16", "A17", "A18"):
+        ws[c].font = BOLD
+    ws["A14"].font, ws["A14"].fill = HEAD, HEAD_FILL
+    for i, col in enumerate(COLS, start=1):
+        head = ws[f"{col}14"]
+        head.value, head.font, head.fill = i, HEAD, HEAD_FILL
+        head.alignment = Alignment(horizontal="center")
+        if i <= HIGH:
+            ws[f"{col}15"] = "=$B$7"
+        else:  # straight-line fade to the terminal rate by year 10
+            ws[f"{col}15"] = f"=$B$7+($B$9-$B$7)*({col}$14-{HIGH})/({YEARS}-{HIGH})"
+        prev = "$B$6" if i == 1 else f"{COLS[i - 2]}16"
+        ws[f"{col}16"] = f"={prev}*(1+{col}15)"
+        ws[f"{col}17"] = f"=1/(1+$B$8)^{col}$14"
+        ws[f"{col}18"] = f"={col}16*{col}17"
+        ws[f"{col}15"].number_format = PCT
+        ws[f"{col}16"].number_format = MONEY
+        ws[f"{col}17"].number_format = '0.0000'
+        ws[f"{col}18"].number_format = MONEY
+    last = COLS[-1]
+
+    # ---------------------------------------------------------------- valuation (rows 20-28)
+    ws["A20"] = "Valuation"
+    ws["A20"].font = BOLD
+    _row(ws, 21, "Present value, years 1-10", f"=SUM(C18:{last}18)", MONEY)
+    _row(ws, 22, "Terminal value at year 10", f"={last}16*(1+$B$9)/($B$8-$B$9)", MONEY, "Gordon growth")
+    _row(ws, 23, "Present value of the terminal value", f"=B22*{last}17", MONEY)
+    _row(ws, 24, "Enterprise value", "=B21+B23", MONEY)
+    _row(ws, 25, "Equity value (+ net cash)", "=B24+B10", MONEY)
+    v = _row(ws, 26, f"Value per share ({ccy})", "=B25/B11", PER_SHARE, font=BOLD)
+    v.fill = KEY_FILL
+    _row(ws, 27, "Price against the value", "=IF(B26>0,B12/B26-1,\"n/a\")", PCT,
+         "Above 0 = the price is higher than this value")
+    _row(ws, 28, "Terminal value share of the total", "=B23/(B21+B23)", PCT,
+         "Above ~75%: the answer rests mostly on the far future")
+    _row(ws, 29, "Check", "=IF($B$8>$B$9,\"OK\",\"Discount rate must be above terminal growth\")")
+
+    # ---------------------------------------------------------------- sensitivity (rows 31-38)
+    ws["A31"] = f"Value per share ({ccy}): discount rate (rows) x terminal growth (columns)"
+    ws["A31"].font = BOLD
+    steps = (-0.01, -0.005, 0.0, 0.005, 0.01)
+    ws["B32"] = "Disc. \\ term."
+    ws["B32"].font = HEAD
+    ws["B32"].fill = HEAD_FILL
+    tcols = COLS[:len(steps)]
+    for col, step in zip(tcols, steps):
+        c = ws[f"{col}32"]
+        c.value = f"=$B$9+{step}" if step else "=$B$9"
+        c.number_format, c.font, c.fill = PCT, HEAD, HEAD_FILL
+    high = COLS[HIGH - 1]  # year 5: the last cash flow the rates don't change
+    for r, step in enumerate((-0.02, -0.01, 0.0, 0.01, 0.02), start=33):
+        w = ws[f"B{r}"]
+        w.value = f"=$B$8+{step}" if step else "=$B$8"
+        w.number_format, w.font, w.fill = PCT, HEAD, HEAD_FILL
+        for col in tcols:
+            cell = ws[f"{col}{r}"]
+            cell.value = _grid_formula(f"$B{r}", f"{col}$32", high)
+            cell.number_format = PER_SHARE
+            if step == 0 and col == tcols[2]:
+                cell.fill, cell.font = KEY_FILL, BOLD
+
+    # ---------------------------------------------------------------- history sheet
+    hs = wb.create_sheet("History")
+    hs.column_dimensions["A"].width = 16
+    hs.column_dimensions["B"].width = 22
+    hs["A1"] = "Year ending"
+    hs["B1"] = f"Free cash flow ({ccy})"
+    for c in ("A1", "B1"):
+        hs[c].font, hs[c].fill = HEAD, HEAD_FILL
+    for i, (period, value) in enumerate(zip(data.get("periods") or [], d.get("fcf_history") or []), start=2):
+        hs.cell(i, 1, period)
+        cell = hs.cell(i, 2, value)
+        cell.number_format, cell.font = MONEY, BLUE
+    hs.cell(len(d.get("fcf_history") or []) + 3, 1,
+            f"Source: {data.get('source', 'company filings')}. Operating cash flow minus capital expenditure "
+            "and stock-based compensation.")
+
+    ws.freeze_panes = "B5"
+    buf = io.BytesIO()
+    wb.save(buf)
+    return buf.getvalue()

marketmyna/services/delivery.py

@@ -0,0 +1,142 @@
+"""Delivery % for NSE shares: of the shares traded in a session, how many
+were taken for delivery (kept) rather than squared off intraday.
+
+The exchange publishes one file per session after the close
+(sec_bhavdata_full_DDMMYYYY.csv, ~400 KB, every symbol). It is fetched in
+the background at most once per CHECK_SECONDS and saved to disk, so a page
+never waits on the exchange and a restart doesn't fetch it again.
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import json
+import logging
+import os
+import threading
+import time
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Optional
+from zoneinfo import ZoneInfo
+
+from marketmyna.core.home import app_home
+
+logger = logging.getLogger(__name__)
+
+URL = "https://nsearchives.nseindia.com/products/content/sec_bhavdata_full_{day:%d%m%Y}.csv"
+CHECK_SECONDS = 30 * 60  # look for a newer session file at most this often
+DAYS_BACK = 7  # weekends + holidays
+IST = ZoneInfo("Asia/Kolkata")
+
+_lock = threading.Lock()
+_state: dict = {"date": None, "rows": {}, "checked": 0.0, "busy": False}
+
+
+def _cache_file() -> Path:
+    base = Path(os.environ.get("DELIVERY_CACHE_DIR") or app_home() / "cache")
+    return base / "nse_delivery.json"
+
+
+def _num(text: str) -> Optional[float]:
+    try:
+        return float(text.strip().replace(",", ""))
+    except (AttributeError, ValueError):
+        return None
+
+
+def parse(text: str) -> dict[str, dict]:
+    """Symbol -> session figures, normal (EQ / BE) series only."""
+    reader = csv.DictReader(io.StringIO(text))
+    reader.fieldnames = [f.strip() for f in reader.fieldnames or []]
+    out: dict[str, dict] = {}
+    for r in reader:
+        r = {k: (v or "").strip() for k, v in r.items() if k}
+        sym, series = r.get("SYMBOL", "").upper(), r.get("SERIES", "")
+        if not sym or series not in ("EQ", "BE", "BZ", "SM", "ST"):
+            continue
+        if sym in out and series != "EQ":
+            continue
+        out[sym] = {
+            "traded": _num(r.get("TTL_TRD_QNTY", "")),
+            "delivered": _num(r.get("DELIV_QTY", "")),
+            "percent": _num(r.get("DELIV_PER", "")),
+            "trades": _num(r.get("NO_OF_TRADES", "")),
+            "avg_price": _num(r.get("AVG_PRICE", "")),
+        }
+    return out
+
+
+def _download() -> tuple[str, dict[str, dict]]:
+    from ..data.listings import _get
+
+    day = datetime.now(IST)
+    last_error: Optional[Exception] = None
+    for _ in range(DAYS_BACK):
+        try:
+            rows = parse(_get(URL.format(day=day)).text)
+            if rows:
+                return day.date().isoformat(), rows
+        except Exception as exc:  # 404 before the close and on holidays
+            last_error = exc
+        day -= timedelta(days=1)
+    raise RuntimeError(f"No delivery file in the last {DAYS_BACK} days: {last_error}")
+
+
+def _load_disk() -> None:
+    try:
+        saved = json.loads(_cache_file().read_text(encoding="utf-8"))
+        _state.update(date=saved["date"], rows=saved["rows"])
+    except (OSError, ValueError, KeyError, TypeError):
+        pass
+
+
+def _refresh() -> None:
+    try:
+        date, rows = _download()
+        with _lock:
+            _state.update(date=date, rows=rows)
+        try:
+            path = _cache_file()
+            path.parent.mkdir(parents=True, exist_ok=True)
+            tmp = path.with_suffix(".tmp")
+            tmp.write_text(json.dumps({"date": date, "rows": rows}), encoding="utf-8")
+            tmp.replace(path)
+        except OSError as exc:
+            logger.debug("Could not save the delivery file: %s", exc)
+    except Exception as exc:
+        logger.info("Delivery file not loaded: %s", exc)
+    finally:
+        with _lock:
+            _state["busy"] = False
+
+
+def _newer_due(date: Optional[str], now: Optional[datetime] = None) -> bool:
+    """A newer file can exist: none saved yet, or the saved one is older than
+    the latest weekday session whose file is out (published by ~18:00 IST).
+    Holidays only cost a recheck every CHECK_SECONDS that day."""
+    if not date:
+        return True
+    now = now or datetime.now(IST)
+    session = now.date() if now.hour >= 18 else now.date() - timedelta(days=1)
+    while session.weekday() >= 5:  # Saturday / Sunday
+        session -= timedelta(days=1)
+    return date < session.isoformat()
+
+
+def get(symbol: str) -> dict:
+    """Last session's delivery figures for one NSE symbol. Starts a
+    background fetch when due; never blocks."""
+    with _lock:
+        if not _state["rows"] and not _state["checked"]:
+            _load_disk()
+        start = (not _state["busy"] and time.monotonic() - _state["checked"] >= CHECK_SECONDS
+                 and (_newer_due(_state["date"]) or not _state["checked"]))
+        if start:
+            _state.update(busy=True, checked=time.monotonic())
+        row = _state["rows"].get(symbol.upper())
+        date, loading = _state["date"], _state["busy"]
+    if start:
+        threading.Thread(target=_refresh, name="nse-delivery", daemon=True).start()
+    return {"date": date, "loading": loading and not row, **(row or {})}

marketmyna/services/discovery.py

@@ -0,0 +1,146 @@
+"""Market discovery: index snapshot, breadth, top gainers / losers / most
+active, 52-week extremes and sector performance for one market.
+
+Everything except the index quotes comes from the listings store
+(marketmyna/data/listings.py), which already carries each stock's price, day change,
+volume, market cap, sector and 52-week range, so no extra downloads are needed.
+Modeled on the OpenBB equity.discovery endpoints (Apache 2.0).
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from datetime import datetime
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+DISCOVERY_MARKETS = ("india", "us", "china_a", "hong_kong", "crypto")
+INDEX_TTL = 60
+TOP = 50  # rows per leader board (the table scrolls)
+SECTOR_MEMBERS = 8  # stocks listed when a sector is pinned
+
+_index_cache: dict[str, tuple[float, list[dict]]] = {}
+_index_lock = threading.Lock()
+
+
+def _indices(market: str) -> list[dict]:
+    from .analysis_run import market_overview
+
+    now = time.time()
+    with _index_lock:
+        hit = _index_cache.get(market)
+        if hit and now - hit[0] < INDEX_TTL:
+            return hit[1]
+    try:
+        rows = market_overview([market])
+    except Exception as exc:
+        logger.warning("Index snapshot for %s failed: %s", market, exc)
+        rows = []
+    with _index_lock:
+        _index_cache[market] = (now, rows)
+    return rows
+
+
+def _item(r: dict) -> dict:
+    price, volume = r.get("price"), r.get("volume")
+    return {
+        "symbol": r["symbol"], "name": r.get("name"), "price": price, "change_percent": r.get("change_percent"),
+        "volume": volume, "traded_value": price * volume if price and volume else None,
+        "market_cap": r.get("market_cap"), "currency": r.get("currency"), "sector": r.get("sector"),
+        "high_52w": r.get("high_52w"), "low_52w": r.get("low_52w"),
+    }
+
+
+def _priced(r: dict) -> bool:
+    return r.get("price") is not None and r.get("change_percent") is not None and (r.get("volume") or 0) > 0
+
+
+def build(market: str, size: int = 500, rows: Optional[list[dict]] = None, with_indices: bool = True,
+          live: Optional[dict] = None) -> dict:
+    """Discovery payload. `size` = how many of the largest names (by market cap,
+    by volume for crypto) the leader boards rank, so illiquid micro-caps do not
+    flood the gainers list. Breadth always covers every priced stock.
+
+    `live` = live_market.market(): its quotes replace the snapshot prices, and
+    only live-priced names are ranked, so today's moves never mix with an
+    earlier session's."""
+    from ..data.listings import get_store
+    from .live_market import merge
+
+    store = get_store()
+    if rows is None:
+        rows = store.rows(market)
+    quotes = (live or {}).get("quotes") or {}
+    if quotes:
+        rows = merge(rows, quotes, only_live=True)
+    kind = "crypto" if market == "crypto" else "stock"
+    stocks = [r for r in rows if r.get("type") == kind and _priced(r)]
+
+    size_key = "volume" if market == "crypto" else "market_cap"
+    universe = sorted((r for r in stocks if r.get(size_key)), key=lambda r: -r[size_key])[:max(20, size)]
+
+    by_change = sorted(universe, key=lambda r: r["change_percent"])
+    traded = sorted(universe, key=lambda r: -(r["price"] * r["volume"]))
+
+    def near(r: dict, key: str) -> Optional[float]:
+        ref = r.get(key)
+        return (r["price"] / ref - 1) * 100 if ref else None
+
+    with_range = [r for r in universe if r.get("high_52w") and r.get("low_52w")]
+    near_high = sorted((r for r in with_range if near(r, "high_52w") >= -2), key=lambda r: -near(r, "high_52w"))
+    near_low = sorted((r for r in with_range if near(r, "low_52w") <= 2), key=lambda r: near(r, "low_52w"))
+
+    adv = sum(r["change_percent"] > 0 for r in stocks)
+    dec = sum(r["change_percent"] < 0 for r in stocks)
+
+    sectors: dict[str, dict] = {}
+    for r in universe:
+        # Broad category (same taxonomy in every market), not the exchange's fine-grained sector.
+        name = r.get("category")
+        if market == "crypto" or not name or name == "Other":
+            continue
+        s = sectors.setdefault(name, {"sector": name, "count": 0, "advancers": 0, "decliners": 0,
+                                      "_w": 0.0, "_wc": 0.0, "_rows": [], "leader": None, "laggard": None})
+        weight = r.get(size_key) or 0
+        s["count"] += 1
+        s["advancers"] += r["change_percent"] > 0
+        s["decliners"] += r["change_percent"] < 0
+        s["_w"] += weight
+        s["_wc"] += weight * r["change_percent"]
+        s["_rows"].append((weight, r))
+        if s["leader"] is None or r["change_percent"] > s["leader"]["change_percent"]:
+            s["leader"] = {"symbol": r["symbol"], "change_percent": r["change_percent"]}
+        if s["laggard"] is None or r["change_percent"] < s["laggard"]["change_percent"]:
+            s["laggard"] = {"symbol": r["symbol"], "change_percent": r["change_percent"]}
+    sector_rows = []
+    for s in sectors.values():
+        w, wc = s.pop("_w"), s.pop("_wc")
+        s["change_percent"] = wc / w if w else None
+        # Largest stocks first, so a pinned sector shows what drives its number.
+        biggest = sorted(s.pop("_rows"), key=lambda t: -t[0])[:SECTOR_MEMBERS]
+        s["members"] = [{"symbol": r["symbol"], "change_percent": r["change_percent"]} for _, r in biggest]
+        sector_rows.append(s)
+    sector_rows.sort(key=lambda s: -(s["change_percent"] if s["change_percent"] is not None else -1e9))
+
+    if quotes:
+        as_of = datetime.fromtimestamp(live["status"]["updated"]).isoformat(timespec="seconds")
+    else:
+        fetched = [s.get("fetched_at") for s in store.status() if s["market"] == market and s.get("fetched_at")]
+        as_of = max(fetched) if fetched else None
+    return {
+        "market": market,
+        "as_of": as_of,
+        "live": (live or {}).get("status"),
+        "universe": len(universe),
+        "indices": _indices(market) if with_indices else [],
+        "breadth": {"advancers": adv, "decliners": dec, "unchanged": len(stocks) - adv - dec, "total": len(stocks)},
+        "gainers": [_item(r) for r in reversed(by_change[-TOP:]) if r["change_percent"] > 0],
+        "losers": [_item(r) for r in by_change[:TOP] if r["change_percent"] < 0],
+        "active": [_item(r) for r in traded[:TOP]],
+        "near_high": [_item(r) for r in near_high[:TOP]],
+        "near_low": [_item(r) for r in near_low[:TOP]],
+        "sectors": sector_rows,
+    }

marketmyna/services/dividends.py

@@ -0,0 +1,95 @@
+"""Dividend history (OpenBB equity.fundamental.dividends / trailing_dividend_yield).
+
+Computed from the per-payment history Yahoo publishes (split-adjusted), not
+its summary fields, which are often stale for Indian stocks: trailing-12-month
+payout and yield, yearly totals, 5-year growth, the run of years without a
+cut, and how often it pays.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Callable, Optional
+
+import pandas as pd
+
+from ..core.numbers import finite as _f
+from ..data.yahoo_price import fresh_price, info_price
+
+Fetch = Callable[[str], dict]
+
+
+def _yahoo(yf_symbol: str) -> dict:
+    import yfinance as yf
+
+    t = yf.Ticker(yf_symbol)
+    try:
+        info = t.info or {}
+    except Exception:
+        info = {}
+    return {"dividends": t.dividends, "info": info, "price": fresh_price(info, t)}
+
+
+def build(yf_symbol: str, fetch: Fetch = _yahoo, today: Optional[pd.Timestamp] = None) -> dict:
+    raw = fetch(yf_symbol)
+    s: pd.Series = raw.get("dividends")
+    info = raw.get("info") or {}
+    price = _f(raw.get("price")) if "price" in raw else info_price(info)
+    if s is None or len(s) == 0:
+        return {"pays": False, "currency": info.get("currency")}
+    idx = pd.DatetimeIndex(s.index)
+    s = pd.Series(s.to_numpy(dtype=float), index=idx.tz_localize(None) if idx.tz is not None else idx).sort_index()
+    s = s[s > 0]
+    if s.empty:
+        return {"pays": False, "currency": info.get("currency")}
+    today = (today or pd.Timestamp.today()).normalize()
+
+    ttm = float(s[s.index > today - pd.Timedelta(days=365)].sum())
+    yearly = s.groupby(s.index.year).sum()
+    complete = yearly[yearly.index < today.year]
+    if len(complete):  # years with no payment at all count as zero (a cut), not as missing
+        complete = complete.reindex(range(int(complete.index.min()), today.year), fill_value=0.0)
+    years = [{"year": int(y), "total": float(v), "partial": False} for y, v in complete.items() if v > 0]
+    if today.year in yearly.index:
+        years.append({"year": today.year, "total": float(yearly[today.year]), "partial": True})
+
+    cagr = None
+    if len(complete) >= 6 and complete.iloc[-6] > 0:
+        cagr = float(((complete.iloc[-1] / complete.iloc[-6]) ** (1 / 5) - 1) * 100)
+
+    # consecutive complete years without a cut, counting back from the latest
+    streak = 0
+    vals = complete.to_numpy()
+    for i in range(len(vals) - 1, 0, -1):
+        if vals[i - 1] > 0 and vals[i] >= vals[i - 1] * 0.995:
+            streak += 1
+        else:
+            break
+
+    per_year = int((s.index > today - pd.Timedelta(days=365)).sum())
+    freq = {0: None, 1: "Yearly", 2: "Twice a year", 3: "Three times a year", 4: "Quarterly"}.get(per_year, "Monthly" if per_year >= 10 else f"{per_year} times a year")
+
+    next_ex = None
+    if ts := _f(info.get("exDividendDate")):
+        d = datetime.fromtimestamp(ts, tz=timezone.utc).date()
+        if pd.Timestamp(d) >= today:
+            next_ex = d.isoformat()
+
+    return {
+        "pays": True,
+        "currency": info.get("currency"),
+        "ttm": ttm,
+        "ttm_yield": ttm / price * 100 if price and ttm else None,
+        "forward_rate": _f(info.get("dividendRate")),
+        "forward_yield": _f(info.get("dividendRate")) / price * 100 if price and _f(info.get("dividendRate")) else None,
+        "five_year_avg_yield": _f(info.get("fiveYearAvgDividendYield")),
+        "payout_ratio": _f(info.get("payoutRatio")) * 100 if _f(info.get("payoutRatio")) is not None else None,
+        "growth_5y": cagr,
+        "years_without_cut": streak,
+        "frequency": freq,
+        "last": {"date": str(s.index[-1].date()), "amount": float(s.iloc[-1])},
+        "next_ex_date": next_ex,
+        "years": years[-12:],
+        "payments": [{"date": str(d.date()), "amount": float(v)} for d, v in s.iloc[-16:].items()][::-1],
+        "first_year": int(s.index[0].year),
+    }