vexity 0.1.0__py3-none-any.whl

vexity/__init__.py

@@ -0,0 +1,41 @@
+"""Official Python client for the Vexity options-analytics API."""
+
+__version__ = "0.1.0"
+
+from vexity.client import Response, Vexity
+from vexity.errors import (
+    AuthError,
+    BadRequest,
+    DecodeError,
+    Forbidden,
+    LayoutMismatch,
+    NotFound,
+    PlanError,
+    RateLimited,
+    ServerError,
+    SocketClosed,
+    TransportError,
+    VexityError,
+)
+from vexity.etag_store import EtagStore
+from vexity.windows import Update, Window
+
+__all__ = [
+    "AuthError",
+    "BadRequest",
+    "DecodeError",
+    "EtagStore",
+    "Forbidden",
+    "LayoutMismatch",
+    "NotFound",
+    "PlanError",
+    "RateLimited",
+    "Response",
+    "ServerError",
+    "SocketClosed",
+    "TransportError",
+    "Update",
+    "Vexity",
+    "VexityError",
+    "Window",
+]

vexity/client.py

@@ -0,0 +1,259 @@
+"""The request pipeline: auth, `If-None-Match`, immutable reads from the store, compact bodies at the pinned layout, pacing, retries and typed errors."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import random
+import re
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import TracebackType
+from typing import Any, Literal
+from urllib.parse import quote
+
+import httpx
+
+import vexity
+from vexity.client_contract_gen import COMPACT_LAYOUT_PARAM, COMPACT_MEDIA_TYPE, COMPACT_PARAM, COMPACT_PLUGIN, RateBudget, compact_body_of
+from vexity.client_policy_gen import backoff_base_ms, backoff_cap_ms, backoff_ceiling_ms, classify_http
+from vexity.compact.decode import COMPACT_LAYOUT
+from vexity.compact.layout_gen import COMPACT_LAYOUT_ID, COMPACT_LAYOUTS
+from vexity.errors import ACTION_ERRORS, DecodeError, LayoutMismatch, TransportError, VexityError
+from vexity.etag_store import EtagStore, Stored
+from vexity.pacing import Pacer
+from vexity.windows import Window
+
+DEFAULT_BASE_URL = "https://vexity.net"
+V2_PREFIX = "/api/v2/"
+COMPACT_LAYOUT_ID_PARAM = "layout_id"
+_LAYOUT_ETAG = re.compile(rf'-cpb{COMPACT_LAYOUT}(-[a-z]+)?"$')
+_APP = re.compile(r"[\x21-\x7e][\x20-\x7e]{0,62}[\x21-\x7e]|[\x21-\x7e]")
+_MAX_AGE = re.compile(r"max-age=([0-9]+)")
+_QUERY_SAFE = ",:-._~"
+
+
+@dataclass(frozen=True, slots=True)
+class Response:
+    """One answer. `source` is `network` (200), `revalidated` (304, stored body) or `store` (immutable, no request made). `layout` is the compact layout the body was read at, None for JSON."""
+
+    body: Any
+    status: int
+    source: Literal["network", "revalidated", "store"]
+    etag: str
+    budget: RateBudget | None
+    request_id: str
+    layout: int | None
+
+
+def user_agent(app: str | None) -> str:
+    """`vexity-py/<version>`, then the caller's own `app` name (`myapp/1.2`) so heavy users can be reached."""
+    if app is not None and not _APP.fullmatch(app):
+        raise ValueError("app is 1 to 64 printable ASCII characters, e.g. 'myapp/1.2'")
+    return f"vexity-py/{vexity.__version__}" + (f" {app}" if app else "")
+
+
+def wire_params(params: Mapping[str, Any] | None) -> dict[str, str]:
+    """The query values as the server reads them: a list joins with commas, True is `true`, None drops, `from_` is `from`."""
+    out: dict[str, str] = {}
+    for key, value in (params or {}).items():
+        if value is None:
+            continue
+        if isinstance(value, bool):
+            value = "true" if value else "false"
+        elif isinstance(value, (list, tuple)):
+            value = ",".join(str(v) for v in value)
+        out[key.rstrip("_")] = str(value)
+    return out
+
+
+def canonical_query(params: Mapping[str, Any] | None) -> str:
+    """Sorted, percent-escaped `k=v` pairs of `wire_params`."""
+    return "&".join(f"{k}={quote(v, safe=_QUERY_SAFE)}" for k, v in sorted(wire_params(params).items()))
+
+
+def _fresh_until(headers: httpx.Headers) -> float:
+    cache = headers.get("cache-control", "")
+    found = _MAX_AGE.search(cache)
+    return time.time() + int(found[1]) if found and "immutable" in cache and "no-store" not in cache else 0.0
+
+
+class Vexity:
+    """Synchronous client. Instant reads ride compact protobuf at the pinned layout (every member, freshness pairs included); `compact=False` reads JSON instead."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        compact: bool = True,
+        app: str | None = None,
+        store: EtagStore | None = None,
+        max_retries: int = 3,
+        max_wait_s: float = 120.0,
+        timeout_s: float = 30.0,
+        transport: httpx.BaseTransport | None = None,
+    ):
+        key = api_key or os.environ.get("VEXITY_API_KEY", "")
+        if not key:
+            raise ValueError("no API key: pass api_key= or set VEXITY_API_KEY")
+        self._key = key
+        self.base_url = base_url.rstrip("/")
+        self._key_tag = hashlib.sha256(f"{self.base_url}\n{key}".encode()).hexdigest()[:16]
+        self.compact = compact
+        self.store = store if store is not None else EtagStore()
+        self._max_retries = max_retries
+        self.pacer = Pacer(max_wait_s=max_wait_s)
+        self.user_agent = user_agent(app)
+        self._http = httpx.Client(base_url=self.base_url, timeout=timeout_s, transport=transport, headers={"Authorization": f"Bearer {key}", "User-Agent": self.user_agent})
+
+    @property
+    def api_key(self) -> str:
+        """The credential, for the live socket URL only; never logged and masked in `repr`."""
+        return self._key
+
+    def __repr__(self) -> str:
+        return f"Vexity(base_url={self.base_url!r}, api_key=***)"
+
+    def __enter__(self) -> Vexity:
+        return self
+
+    def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def get(self, path: str, params: Mapping[str, Any] | None = None, *, compact: bool | None = None) -> Response:
+        """GET `path` (a v2 path such as `/api/v2/levels/SPX`) with the efficient defaults."""
+        query = canonical_query(params)
+        resource = path[len(V2_PREFIX) :].split("/", 1)[0] if path.startswith(V2_PREFIX) else ""
+        asked = wire_params(params)
+        body_name = compact_body_of(resource, lambda key: asked.get(key, "")) if (self.compact if compact is None else compact) else None
+        if body_name not in COMPACT_LAYOUTS:
+            body_name = None
+        if body_name is not None:
+            query = canonical_query({**(params or {}), COMPACT_PARAM: COMPACT_PLUGIN, COMPACT_LAYOUT_PARAM: COMPACT_LAYOUT, COMPACT_LAYOUT_ID_PARAM: COMPACT_LAYOUT_ID})
+        url = f"{path}?{query}" if query else path
+        key = f"{self._key_tag}|{url}|{'compact' if body_name else 'json'}"
+        stored = self.store.get(key)
+        if stored is not None and stored.fresh_until > time.time():
+            return self._response(stored, 200, "store", "", body_name)
+        headers = {"Accept": COMPACT_MEDIA_TYPE if body_name else "application/json"}
+        if stored is not None:
+            headers["If-None-Match"] = stored.etag
+        resp = self._send("GET", url, headers)
+        request_id = resp.headers.get("x-request-id", "")
+        if resp.status_code == 304 and stored is not None:
+            return self._response(stored, 304, "revalidated", request_id, body_name)
+        if resp.status_code != 200:
+            raise DecodeError(f"{path} answered {resp.status_code}, which is not an answer to this read", status=resp.status_code, request_id=request_id)
+        if body_name is not None and not _LAYOUT_ETAG.search(resp.headers.get("etag", "")):
+            raise LayoutMismatch(f"asked compact layout {COMPACT_LAYOUT} and the server answered another ({resp.headers.get('etag', '')!r}): upgrade vexity or pass compact=False", status=200, request_id=request_id)
+        fresh = Stored(resp.headers.get("etag", ""), resp.content, resp.headers.get("content-type", ""), _fresh_until(resp.headers), COMPACT_LAYOUT if body_name else None)
+        if fresh.etag and "no-store" not in resp.headers.get("cache-control", ""):
+            self.store.put(key, fresh)
+        return self._response(fresh, resp.status_code, "network", request_id, body_name)
+
+    def post(self, path: str, body: Mapping[str, Any]) -> Any:
+        resp = self._send("POST", path, {"Accept": "application/json"}, json_body=body)
+        try:
+            return resp.json()
+        except ValueError as e:
+            raise DecodeError(f"{path} answered a body that is not JSON", status=resp.status_code) from e
+
+    def read(self, resource: str, ticker: str, /, *, compact: bool | None = None, **params: Any) -> Any:
+        """The body of `/api/v2/{resource}/{ticker}`."""
+        return self.get(f"{V2_PREFIX}{resource}/{ticker}", params, compact=compact).body
+
+    def levels(self, ticker: str, **params: Any) -> Any:
+        return self.read("levels", ticker, **params)
+
+    def frame(self, ticker: str, **params: Any) -> Any:
+        return self.read("frame", ticker, **params)
+
+    def profile(self, ticker: str, **params: Any) -> Any:
+        return self.read("profile", ticker, **params)
+
+    def series(self, ticker: str, **params: Any) -> Any:
+        return self.read("series", ticker, **params)
+
+    def contracts(self, ticker: str, **params: Any) -> Any:
+        return self.read("contracts", ticker, **params)
+
+    def surface(self, ticker: str, **params: Any) -> Any:
+        return self.read("surface", ticker, **params)
+
+    def me(self) -> Any:
+        return self.get(f"{V2_PREFIX}me").body
+
+    def catalogue(self, **params: Any) -> Any:
+        return self.get(f"{V2_PREFIX}catalogue", params).body
+
+    def window(self, resource: str, ticker: str, /, *, span: str | None = None, **params: Any) -> Window:
+        """A live window read once in full, then by tails: see `Window`."""
+        return Window(self, resource, ticker, span=span, params=params)
+
+    def live(self, **options: Any):
+        """A live socket session: see `vexity.live.Live`."""
+        from vexity.live.session import Live
+
+        return Live(self, **options)
+
+    def _response(self, stored: Stored, status: int, source: Literal["network", "revalidated", "store"], request_id: str, body_name: str | None) -> Response:
+        if body_name is None:
+            try:
+                body = json.loads(stored.body)
+            except ValueError as e:
+                raise DecodeError("the answer is not JSON", status=status, request_id=request_id) from e
+        else:
+            from vexity.compact.decode import CompactError, decode_compact
+
+            try:
+                body = decode_compact(body_name, stored.body)
+            except CompactError as e:
+                raise DecodeError(f"the compact answer does not read as {body_name}: {e}", status=status, request_id=request_id) from e
+        return Response(body, status, source, stored.etag, self.pacer.budget, request_id, stored.layout)
+
+    def _send(self, method: str, url: str, headers: dict[str, str], *, json_body: Mapping[str, Any] | None = None) -> httpx.Response:
+        failures = 0
+        while True:
+            self.pacer.wait()
+            resp: httpx.Response | None = None
+            try:
+                resp = self._http.request(method, url, headers=headers, json=json_body)
+            except httpx.TransportError as e:
+                status, reason, detail, request_id, retry_ms = 0, "", str(e) or type(e).__name__, "", 0
+            else:
+                self.pacer.observe({k.lower(): v for k, v in resp.headers.items()})
+                if resp.status_code < 400:
+                    return resp
+                status = resp.status_code
+                reason, detail, request_id = _error_fields(resp)
+                if status == 409 and detail.startswith("layout_mismatch"):
+                    raise LayoutMismatch(f"the server writes another compact layout than this vexity release reads: upgrade vexity or pass compact=False ({detail})", status=409, reason=reason, detail=detail, request_id=request_id)
+                retry_ms = self.pacer.retry_after({k.lower(): v for k, v in resp.headers.items()})
+            decision = classify_http(status, reason, retry_ms, "mint")
+            error_class = ACTION_ERRORS[decision.action] if status else TransportError
+            if decision.action in ("rate", "backoff") and failures < self._max_retries and not self.pacer.too_long(decision.wait_ms):
+                failures += 1
+                delay = decision.wait_ms if decision.action == "rate" else max(decision.wait_ms, int(random.uniform(0, backoff_ceiling_ms(failures, backoff_base_ms(), backoff_cap_ms()))))
+                self.pacer.block(delay)
+                continue
+            raise error_class(f"{method} {url.split('?', 1)[0]} answered {status or 'no status'} {reason}".strip(), status=status, reason=reason, detail=detail, request_id=request_id, retry_after_ms=retry_ms)
+
+
+def _error_fields(resp: httpx.Response) -> tuple[str, str, str]:
+    request_id = resp.headers.get("x-request-id", "")
+    try:
+        body = resp.json()
+    except ValueError:
+        return "", resp.text[:200], request_id
+    if not isinstance(body, dict):
+        return "", "", request_id
+    return str(body.get("reason", "")), str(body.get("detail", "")), str(body.get("request_id", request_id))
+
+
+__all__ = ["Response", "Vexity", "VexityError", "canonical_query"]

vexity/client_contract_gen.py

@@ -0,0 +1,241 @@
+# Generated by integrations/codegen/gen_v2_decoders.py from services/vexity-rs/crates/vx-core/catalogue.json (client_contract). Do not edit.
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+
+RETRY_AFTER_HEADER = "Retry-After"
+RATE_LIMIT_HEADER = "RateLimit"
+RATE_LIMIT_POLICY_HEADER = "RateLimit-Policy"
+COMPACT_PARAM = "compact"
+COMPACT_LAYOUT_PARAM = "compact_layout"
+COMPACT_PLUGIN = "plugin"
+COMPACT_MEDIA_TYPE = "application/x-protobuf"
+FRAME_WINDOW_SLACK = 8
+FRAME_STEP_MS = {"cycle": 30000, "5s": 5000, "10s": 10000, "30s": 30000, "1m": 60000, "5m": 300000, "15m": 900000, "30m": 1800000, "1h": 3600000, "1d": 86400000}
+
+_RETRY_AFTER_MIN_MS = 1000
+_RETRY_AFTER_MAX_MS = 3600000
+_IMF_FIXDATE = re.compile(r"^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), ([0-9]{2}) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) ([12][0-9]{3}) ([0-9]{2}):([0-9]{2}):([0-9]{2}) GMT$")
+_MONTHS = ("Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec")
+_DIGITS = re.compile(r"[0-9]+")
+
+
+def _days_from_civil(y: int, m: int, d: int) -> int:
+    y -= m <= 2
+    era = y // 400
+    yoe = y - era * 400
+    doy = (153 * (m + (-3 if m > 2 else 9)) + 2) // 5 + d - 1
+    doe = yoe * 365 + yoe // 4 - yoe // 100 + doy
+    return era * 146097 + doe - 719468
+
+
+def _clamp(ms: int) -> int:
+    return max(_RETRY_AFTER_MIN_MS, min(_RETRY_AFTER_MAX_MS, ms))
+
+
+def retry_after_ms(value: str | None, now_ms: int) -> int:
+    """A Retry-After as a wait in ms: whole seconds or an IMF-fixdate, clamped to the contract's floor and ceiling; 0 when it is empty or neither."""
+    raw = (value or "").strip(" \t")
+    if raw == "":
+        return 0
+    if _DIGITS.fullmatch(raw):
+        return _clamp(_RETRY_AFTER_MAX_MS if len(raw) > 12 else int(raw) * 1000)
+    m = _IMF_FIXDATE.fullmatch(raw)
+    if m is None:
+        return 0
+    day, hour, minute, second = int(m[1]), int(m[4]), int(m[5]), int(m[6])
+    if day < 1 or day > 31 or hour > 23 or minute > 59 or second > 60:
+        return 0
+    at_ms = (_days_from_civil(int(m[3]), _MONTHS.index(m[2]) + 1, day) * 86400 + hour * 3600 + minute * 60 + second) * 1000
+    return _clamp(-((now_ms - at_ms) // 1000) * 1000 if at_ms > now_ms else 0)
+
+
+@dataclass(frozen=True, slots=True)
+class RateBudget:
+    """The first budget the RateLimit (what is left, the seconds until the window frees a unit) and RateLimit-Policy (quota per window) headers list; a member they omit is None."""
+
+    quota: int | None
+    window_s: int | None
+    left: int | None
+    reset_s: int | None
+
+
+def _first_int(text: str, key: str) -> int | None:
+    m = re.search(rf"\b{key}=([0-9]+)", text)
+    return None if m is None else int(m[1])
+
+
+def rate_budget(ratelimit: str | None, policy: str | None) -> RateBudget | None:
+    state = ratelimit or ""
+    quota = policy or ""
+    if state == "" and quota == "":
+        return None
+    return RateBudget(_first_int(quota, "q"), _first_int(quota, "w"), _first_int(state, "r"), _first_int(state, "t"))
+
+
+def compact_body_of(resource: str, param: Callable[[str], str]) -> str | None:
+    """The compact body a read of `resource` is asked for, or None to stay JSON; `param` is the read's value of a query key, '' when absent. The first matching shape decides."""
+    if resource == "profile":
+        if param("by") == "time":
+            return "ProfileWindowBody"
+        return "ProfileBody"
+    if resource == "frame":
+        if any(param(k) != "" for k in ("from", "to")):
+            return "FrameWindowBody"
+        return "FrameBody"
+    if resource == "levels":
+        return "LevelsBody"
+    if resource == "series":
+        return "SeriesBody"
+    if resource == "surface":
+        return "SurfaceBody"
+    if resource == "contracts":
+        return "ContractsBody"
+    return None
+
+
+def compact_query(body: str) -> str:
+    """The query that asks for `body` in the plugin dialect: the profile, and the layout generation for a shape that needs one."""
+    if body in ("ProfileWindowBody", "FrameWindowBody"):
+        return "compact=plugin&compact_layout=2"
+    return "compact=plugin"
+
+
+_SCOPED = {"frame": True, "levels": True, "profile": True, "series": True, "contracts": False, "curve_quotes": False, "surface": False}
+_SEGMENT_KEYS = ("scope", "view")
+_REST_ONLY_KEYS = ("at", "anchor", "from", "to", "cursor", "sessions")
+_REST_ONLY_BY_RESOURCE = {"frame": ("step", "max_points"), "series": ("step", "max_points"), "profile": ("step", "max_points", "layout", "min_contracts"), "rollup_vol_baseline": ("session",)}
+_REST_ONLY_EXEMPT = ("rollup_level_timeline.sessions",)
+_LOOKBACK_KEY = "lookback"
+_MAX_LOOKBACK_S = 7200
+_LIST_SEP = "+"
+_MAX_TOPIC_LEN = 1024
+_DEFAULT_SCOPE = "full"
+_NONE_PART = "-"
+_MAX_DECIMAL_DIGITS = 15
+_SAFE = re.compile(r"[A-Za-z0-9._-]+")
+_DECIMAL = re.compile(r"([0-9]+)\.([0-9]+)")
+_LOOKBACK = re.compile(r"-([0-9]+)s")
+
+
+def _rest_only(resource: str, key: str) -> bool:
+    if key in _REST_ONLY_KEYS and f"{resource}.{key}" not in _REST_ONLY_EXEMPT:
+        return True
+    return key in _REST_ONLY_BY_RESOURCE.get(resource, ())
+
+
+def _canonical_value(v: str) -> str | None:
+    """The topic spelling of a REST value: a comma list sorted, deduped and joined, an integer without leading zeros, a short decimal without trailing zeros; None where it cannot ride a topic."""
+    if "," in v:
+        members = v.split(",")
+        if not all(_SAFE.fullmatch(m) for m in members):
+            return None
+        return _LIST_SEP.join(sorted(set(members)))
+    if not _SAFE.fullmatch(v):
+        return None
+    if _DIGITS.fullmatch(v):
+        return v.lstrip("0") or "0"
+    d = _DECIMAL.fullmatch(v)
+    if d is None:
+        return v
+    whole = d[1].lstrip("0") or "0"
+    frac = d[2].rstrip("0")
+    if (0 if whole == "0" else len(whole)) + len(frac) > _MAX_DECIMAL_DIGITS:
+        return None
+    return whole if frac == "" else f"{whole}.{frac}"
+
+
+def _lookback_of(from_value: str | None) -> int | None:
+    """`from=-<N>s` as N seconds within the span a socket holds."""
+    m = None if from_value is None else _LOOKBACK.fullmatch(from_value)
+    if m is None or len(m[1]) > 9:
+        return None
+    n = int(m[1])
+    return n if 1 <= n <= _MAX_LOOKBACK_S else None
+
+
+def frame_window_max_points(lookback_s: int, step_ms: int) -> int:
+    """The max_points a frame window of `lookback_s` seconds at `step_ms` asks for."""
+    return lookback_s * 1000 // step_ms + FRAME_WINDOW_SLACK
+
+
+def _render_topic(family: str, ticker: str, scope: str, view: str, params: dict[str, str]) -> str | None:
+    topic = f"{family}:{ticker}:{scope}:{view if view else _NONE_PART}"
+    if params:
+        topic += ":" + ",".join(f"{k}={params[k]}" for k in sorted(params))
+    return topic if len(topic) <= _MAX_TOPIC_LEN else None
+
+
+def v2_topic(path: str) -> str | None:
+    """The topic for a `/api/v2/{resource}/{TICKER}?...` read, or None when the read can only be REST; whether the server pushes it is the hello's call."""
+    pathname, _, query = path.partition("?")
+    if "%" in query or "+" in query or not pathname.startswith("/api/v2/"):
+        return None
+    parts = pathname[len("/api/v2/") :].split("/")
+    if len(parts) != 2:
+        return None
+    resource, ticker = parts
+    scoped = _SCOPED.get(resource)
+    if scoped is None or not _SAFE.fullmatch(ticker):
+        return None
+    q: dict[str, str] = {}
+    for pair in query.split("&") if query else []:
+        key, _, value = pair.partition("=")
+        if key == "" or key in q:
+            return None
+        q[key] = value
+    frame_window = resource == "frame" and "from" in q
+    scope, view = q.get("scope", ""), q.get("view", "")
+    if ("scope" in q and (not scoped or not _SAFE.fullmatch(scope))) or ("view" in q and not _SAFE.fullmatch(view)):
+        return None
+    if "plan" in q and (resource != "levels" or q["plan"] != "saved"):
+        return None
+    params: dict[str, str] = {}
+    for k, raw in q.items():
+        if k in _SEGMENT_KEYS:
+            continue
+        if k == _LOOKBACK_KEY:
+            return None
+        if (resource == "series" or frame_window) and k == "from":
+            continue
+        if frame_window and k in ("step", "max_points"):
+            continue
+        if _rest_only(resource, k) or not _SAFE.fullmatch(k):
+            return None
+        v = _canonical_value(raw)
+        if v is None or (resource == "profile" and k == "by" and v == "time"):
+            return None
+        params[k] = v
+    if resource == "series":
+        secs = _lookback_of(q.get("from"))
+        if secs is None:
+            return None
+        params[_LOOKBACK_KEY] = str(secs)
+    family = resource
+    if frame_window:
+        secs = _lookback_of(q.get("from"))
+        step = q.get("step", "")
+        step_ms = FRAME_STEP_MS.get(step)
+        if secs is None or step_ms is None or q.get("max_points") != str(frame_window_max_points(secs, step_ms)):
+            return None
+        params[_LOOKBACK_KEY] = str(secs)
+        params["step"] = step
+        family = "frame-window"
+    return _render_topic(family, ticker, scope or _DEFAULT_SCOPE, view, params)
+
+
+def profile_tail_topic(ticker: str, scope: str, view: str, lanes: list[str], range_pct: str | None) -> str | None:
+    """The topic that pushes the newest frame of a `profile by=time` window as a one-sample window, in the history read's lanes, scope and strike band (`range_pct`, a fraction of spot; None is the whole ladder); None where a part cannot ride a topic."""
+    if not _SAFE.fullmatch(ticker) or not _SAFE.fullmatch(scope) or (view != "" and not _SAFE.fullmatch(view)) or not lanes:
+        return None
+    lane_list = _canonical_value(",".join(lanes))
+    band = None if range_pct is None else _canonical_value(range_pct)
+    if lane_list is None or (range_pct is not None and band is None):
+        return None
+    params = {"lanes": lane_list}
+    if band is not None:
+        params["range_pct"] = band
+    return _render_topic("profile-tail", ticker, scope, view, params)