perpbrain-read 0.1.0__py3-none-any.whl

perpbrain_read/__init__.py

@@ -0,0 +1,5 @@
+"""Read-only and simulation toolkit. No order or guard imports."""
+
+from perpbrain_read._dist import distribution_name
+
+__all__ = ["distribution_name"]

perpbrain_read/_dist.py

@@ -0,0 +1,30 @@
+"""Distribution name, configured in pyproject.toml."""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+
+def distribution_name(pyproject: Path | None = None) -> str:
+    """Return the configured distribution name for the read package."""
+    path = pyproject if pyproject is not None else _default_pyproject()
+    data = tomllib.loads(path.read_text(encoding="utf-8"))
+    tool = data.get("tool")
+    project = data.get("project")
+    if not isinstance(tool, dict) or not isinstance(project, dict):
+        raise RuntimeError("pyproject is missing tool or project tables")
+    configured_table = tool.get("perpbrain")
+    if not isinstance(configured_table, dict):
+        raise RuntimeError("pyproject is missing tool.perpbrain")
+    configured = configured_table.get("dist-name")
+    project_name = project.get("name")
+    if not isinstance(configured, str) or not isinstance(project_name, str):
+        raise RuntimeError("dist-name and project.name must be strings")
+    if configured != project_name:
+        raise RuntimeError("tool.perpbrain.dist-name must match project.name")
+    return configured
+
+
+def _default_pyproject() -> Path:
+    return Path(__file__).resolve().parents[2] / "pyproject.toml"

perpbrain_read/read/__init__.py

@@ -0,0 +1,5 @@
+"""Read models. Live queries live in queries.py and do not replace these stubs."""
+
+from perpbrain_read.read.markets import book, funding, liquidations, open_interest
+
+__all__ = ["book", "funding", "liquidations", "open_interest"]

perpbrain_read/read/age.py

@@ -0,0 +1,45 @@
+"""Data age from the exchange timestamp on a payload, else the receipt time."""
+
+from __future__ import annotations
+
+import time
+from typing import TypedDict
+
+STALE_AFTER_MS = 20_000
+
+
+class DataAge(TypedDict):
+    age_ms: int
+    stale: bool
+    as_of_ms: int
+
+
+def wall_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def message_time(payload: object) -> int | None:
+    if not isinstance(payload, dict):
+        return None
+    raw = payload.get("time")
+    if isinstance(raw, bool) or not isinstance(raw, int):
+        return None
+    return raw
+
+
+def make_age(as_of_ms: int, now_ms: int) -> DataAge:
+    elapsed = now_ms - as_of_ms
+    if elapsed < 0:
+        elapsed = 0
+    return {
+        "age_ms": elapsed,
+        "stale": elapsed >= STALE_AFTER_MS,
+        "as_of_ms": as_of_ms,
+    }
+
+
+def resolve_as_of(payload: object, received_ms: int) -> int:
+    stamped = message_time(payload)
+    if stamped is None:
+        return received_ms
+    return stamped