f1verse 0.3.0__tar.gz

f1verse-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 f1verse contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

f1verse-0.3.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: f1verse
+Version: 0.3.0
+Summary: The story layer for Formula 1 data — zero-dependency race narratives: lead changes, stints, race pace, live championship projection, team radio index. Optional FastF1 adapter.
+Author: f1verse contributors
+License: MIT
+Project-URL: Homepage, https://github.com/f1verse/f1verse
+Keywords: f1,formula1,formula-1,fastf1,openf1,motorsport,racing,telemetry,live-timing,race-analysis,data-analysis,grand-prix
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: fastf1
+Requires-Dist: fastf1>=3.4; extra == "fastf1"
+Dynamic: license-file
+
+# f1verse
+
+**The story layer for Formula 1 data.** Data libraries fetch and tidy —
+f1verse tells you *what happened*: lead changes, laps led, event timelines,
+stint strategy, true race pace, and the live championship projection that
+broadcasts never show.
+
+**Zero dependencies.** Standard library only, seasons 2023+.
+
+```bash
+pip install f1verse
+```
+
+```python
+import f1verse
+
+race = f1verse.load(2026, 12)        # year, round — no other library needed
+
+race.laps_led()      # {'ANT': 32, 'NOR': 31, 'HAM': 9}
+race.leader_runs()   # [{'abbr': 'NOR', 'from': 1, 'to': 4}, ...]
+race.results()[7]    # {'abbr': 'HUL', 'gap': '+1 LAP', ...}
+race.race_pace()     # median pace — pit/SC/VSC laps excluded by default
+race.story()         # one call, whole story, plain JSON
+
+race.championship_prediction()   # per-lap "if it ended now" title projection
+race.team_radio()                # timestamped clip URLs (nothing downloaded)
+```
+
+Using FastF1 already? Keep your workflow — the adapter takes a loaded
+session (`pip install f1verse[fastf1]`, adds telemetry & pre-2023 seasons):
+
+```python
+story = f1verse.analyze(fastf1_session)
+```
+
+## Why this exists
+
+Everyone who builds on FastF1 rediscovers the same traps, and each fixes
+them slightly differently:
+
+- **`results['Time']` is not a gap for lapped cars.** The raw value can be
+  *smaller* than a car that finished ahead (`P7 +1:19.915` vs `P8 +36.049`).
+  No error, no warning — naive tables are silently wrong.
+  → `f1verse.format_gap` applies the broadcast convention (`+1 LAP`).
+- **There is no API for "who led the race".** Lead changes, laps led,
+  overtake-for-the-lead moments — every notebook reinvents them.
+  → `leader_runs`, `laps_led`, `timeline`.
+- **Race pace needs domain rules**, not just a quicklap threshold: in/out
+  laps, SC/VSC laps, and laps failing FastF1's own 4-way accuracy check
+  must go. → `race_pace` applies all of it by default.
+- **numpy scalars break `json.dumps`.** Every f1verse output is plain
+  JSON-safe Python. → pipe results straight into web or video pipelines.
+- **Data-quality warnings are only logged as text.**
+  → `integrity_report` returns them as structured data your pipeline can
+  act on (hold publication, exclude laps, annotate).
+
+## The feeds FastF1 throws away
+
+The official live-timing archive contains more than FastF1 parses.
+f1verse harvests three of the dropped feeds (through FastF1's own cache,
+same rate-limit etiquette):
+
+```python
+f1verse.championship_prediction(session)
+# per-lap "if the race ended now" projection of both championships,
+# including the moments the projected champion changed
+
+f1verse.team_radio(session)
+# timestamped team-radio clips: [{'t', 'utc', 'driver_number', 'url'}]
+# URLs only — nothing is downloaded or redistributed
+
+f1verse.timing_stats(session)
+# personal bests, best sectors, speed-trap figures
+```
+
+## Design rules
+
+1. **Zero required dependencies.** The native loader speaks to public REST
+   endpoints (OpenF1) and the official live-timing archive directly, with
+   its own on-disk cache and polite pacing.
+2. **FastF1 is respected, not replaced** — optional adapter for telemetry,
+   qualifying segments and pre-2023 history.
+3. **Everything returned is plain JSON-safe Python.**
+4. **F1 domain rules are defaults, not options.**
+5. **Cross-checked where possible** — e.g. lapped-car gaps are computed by
+   convention *and* confirmed against a second source.
+6. **Code only.** No timing data, media, or images are bundled or
+   redistributed; data is fetched by the end user.
+
+## Roadmap
+
+- Full cross-validation layer (publish only when two sources agree)
+- Overtake timeline ([OpenF1](https://openf1.org) `/overtakes`) & undercut/overcut detection
+- Circuit & driver metadata joins ([Jolpica](https://github.com/jolpica/jolpica-f1), [f1db](https://github.com/f1db/f1db))
+- Korean localization package (`f1verse-ko`)
+- Chart & vertical-video templates consuming f1verse JSON
+
+---
+
+*Unofficial fan project. Not affiliated with, endorsed by, or associated
+with Formula 1, FIA, FOM, or any F1 team. F1, FORMULA 1 and related marks
+are trademarks of Formula One Licensing BV. This library contains code
+only — no timing data, media, or images are included or redistributed;
+data is fetched by the end user from publicly accessible endpoints,
+subject to the respective providers' terms. Built on
+[FastF1](https://github.com/theOehrly/Fast-F1) (MIT).*

f1verse-0.3.0/README.md

@@ -0,0 +1,106 @@
+# f1verse
+
+**The story layer for Formula 1 data.** Data libraries fetch and tidy —
+f1verse tells you *what happened*: lead changes, laps led, event timelines,
+stint strategy, true race pace, and the live championship projection that
+broadcasts never show.
+
+**Zero dependencies.** Standard library only, seasons 2023+.
+
+```bash
+pip install f1verse
+```
+
+```python
+import f1verse
+
+race = f1verse.load(2026, 12)        # year, round — no other library needed
+
+race.laps_led()      # {'ANT': 32, 'NOR': 31, 'HAM': 9}
+race.leader_runs()   # [{'abbr': 'NOR', 'from': 1, 'to': 4}, ...]
+race.results()[7]    # {'abbr': 'HUL', 'gap': '+1 LAP', ...}
+race.race_pace()     # median pace — pit/SC/VSC laps excluded by default
+race.story()         # one call, whole story, plain JSON
+
+race.championship_prediction()   # per-lap "if it ended now" title projection
+race.team_radio()                # timestamped clip URLs (nothing downloaded)
+```
+
+Using FastF1 already? Keep your workflow — the adapter takes a loaded
+session (`pip install f1verse[fastf1]`, adds telemetry & pre-2023 seasons):
+
+```python
+story = f1verse.analyze(fastf1_session)
+```
+
+## Why this exists
+
+Everyone who builds on FastF1 rediscovers the same traps, and each fixes
+them slightly differently:
+
+- **`results['Time']` is not a gap for lapped cars.** The raw value can be
+  *smaller* than a car that finished ahead (`P7 +1:19.915` vs `P8 +36.049`).
+  No error, no warning — naive tables are silently wrong.
+  → `f1verse.format_gap` applies the broadcast convention (`+1 LAP`).
+- **There is no API for "who led the race".** Lead changes, laps led,
+  overtake-for-the-lead moments — every notebook reinvents them.
+  → `leader_runs`, `laps_led`, `timeline`.
+- **Race pace needs domain rules**, not just a quicklap threshold: in/out
+  laps, SC/VSC laps, and laps failing FastF1's own 4-way accuracy check
+  must go. → `race_pace` applies all of it by default.
+- **numpy scalars break `json.dumps`.** Every f1verse output is plain
+  JSON-safe Python. → pipe results straight into web or video pipelines.
+- **Data-quality warnings are only logged as text.**
+  → `integrity_report` returns them as structured data your pipeline can
+  act on (hold publication, exclude laps, annotate).
+
+## The feeds FastF1 throws away
+
+The official live-timing archive contains more than FastF1 parses.
+f1verse harvests three of the dropped feeds (through FastF1's own cache,
+same rate-limit etiquette):
+
+```python
+f1verse.championship_prediction(session)
+# per-lap "if the race ended now" projection of both championships,
+# including the moments the projected champion changed
+
+f1verse.team_radio(session)
+# timestamped team-radio clips: [{'t', 'utc', 'driver_number', 'url'}]
+# URLs only — nothing is downloaded or redistributed
+
+f1verse.timing_stats(session)
+# personal bests, best sectors, speed-trap figures
+```
+
+## Design rules
+
+1. **Zero required dependencies.** The native loader speaks to public REST
+   endpoints (OpenF1) and the official live-timing archive directly, with
+   its own on-disk cache and polite pacing.
+2. **FastF1 is respected, not replaced** — optional adapter for telemetry,
+   qualifying segments and pre-2023 history.
+3. **Everything returned is plain JSON-safe Python.**
+4. **F1 domain rules are defaults, not options.**
+5. **Cross-checked where possible** — e.g. lapped-car gaps are computed by
+   convention *and* confirmed against a second source.
+6. **Code only.** No timing data, media, or images are bundled or
+   redistributed; data is fetched by the end user.
+
+## Roadmap
+
+- Full cross-validation layer (publish only when two sources agree)
+- Overtake timeline ([OpenF1](https://openf1.org) `/overtakes`) & undercut/overcut detection
+- Circuit & driver metadata joins ([Jolpica](https://github.com/jolpica/jolpica-f1), [f1db](https://github.com/f1db/f1db))
+- Korean localization package (`f1verse-ko`)
+- Chart & vertical-video templates consuming f1verse JSON
+
+---
+
+*Unofficial fan project. Not affiliated with, endorsed by, or associated
+with Formula 1, FIA, FOM, or any F1 team. F1, FORMULA 1 and related marks
+are trademarks of Formula One Licensing BV. This library contains code
+only — no timing data, media, or images are included or redistributed;
+data is fetched by the end user from publicly accessible endpoints,
+subject to the respective providers' terms. Built on
+[FastF1](https://github.com/theOehrly/Fast-F1) (MIT).*

f1verse-0.3.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "f1verse"
+version = "0.3.0"
+description = "The story layer for Formula 1 data — zero-dependency race narratives: lead changes, stints, race pace, live championship projection, team radio index. Optional FastF1 adapter."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "f1verse contributors" }]
+keywords = [
+  "f1", "formula1", "formula-1", "fastf1", "openf1", "motorsport", "racing",
+  "telemetry", "live-timing", "race-analysis", "data-analysis", "grand-prix",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = []
+
+[project.optional-dependencies]
+fastf1 = ["fastf1>=3.4"]
+
+[project.urls]
+Homepage = "https://github.com/f1verse/f1verse"
+
+[tool.setuptools.packages.find]
+where = ["src"]

f1verse-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

f1verse-0.3.0/src/f1verse/__init__.py

@@ -0,0 +1,45 @@
+"""f1verse — the story layer for Formula 1 data.
+
+Native (no FastF1 required, seasons 2023+):
+
+>>> import f1verse
+>>> race = f1verse.load(2026, 12)
+>>> race.laps_led()              # {'NOR': 31, 'ANT': 32, ...}
+>>> race.story()                 # whole race as JSON-safe dict
+>>> race.championship_prediction()   # the feed everyone throws away
+
+FastF1 adapter (``pip install f1verse[fastf1]``) for telemetry, qualifying
+segments and pre-2023 seasons:
+
+>>> story = f1verse.analyze(fastf1_session)
+"""
+from . import http
+from ._json import jsonsafe
+from .feeds import championship_prediction, team_radio, timing_stats
+from .gaps import format_gap
+from .crosscheck import crosscheck
+from .race import Race, load
+
+__version__ = "0.3.0"
+_FASTF1_API = {"analyze", "leader_runs", "laps_led", "timeline", "stints",
+               "race_pace", "results", "interruption_bands",
+               "integrity_report"}
+
+
+def __getattr__(name):
+    if name in _FASTF1_API:
+        try:
+            from . import integrity, story
+        except ImportError as e:
+            raise ImportError(
+                f"f1verse.{name} needs the FastF1 adapter: "
+                "pip install f1verse[fastf1]") from e
+        mod = integrity if name == "integrity_report" else story
+        return getattr(mod, name)
+    raise AttributeError(name)
+
+
+enable_cache = http.enable_cache
+__all__ = ["load", "Race", "format_gap", "jsonsafe", "enable_cache",
+           "championship_prediction", "team_radio", "timing_stats",
+           "crosscheck", *sorted(_FASTF1_API)]

f1verse-0.3.0/src/f1verse/_json.py

@@ -0,0 +1,52 @@
+"""JSON-safe conversion — every public f1verse output passes through here.
+
+Works with or without numpy/pandas installed: the native loader returns
+plain Python already; the FastF1 adapter returns numpy scalars and pandas
+timestamps that ``json.dumps`` rejects.
+"""
+import datetime
+import math
+
+try:
+    import numpy as _np
+except ImportError:          # zero-dep native install
+    _np = None
+try:
+    import pandas as _pd
+except ImportError:
+    _pd = None
+
+
+def jsonsafe(obj):
+    """Recursively convert *obj* to plain JSON-serializable Python types."""
+    if obj is None or isinstance(obj, (bool, str)):
+        return obj
+    if _np is not None and isinstance(obj, _np.integer):
+        return int(obj)
+    if isinstance(obj, int):
+        return obj
+    if (_np is not None and isinstance(obj, _np.floating)) or isinstance(obj, float):
+        f = float(obj)
+        return None if math.isnan(f) else f
+    if isinstance(obj, datetime.timedelta):
+        return obj.total_seconds()
+    if isinstance(obj, (datetime.datetime, datetime.date)):
+        return obj.isoformat()
+    if _pd is not None:
+        if isinstance(obj, _pd.Timedelta):
+            return None if obj is _pd.NaT else obj.total_seconds()
+        if isinstance(obj, _pd.Timestamp):
+            return obj.isoformat()
+        if obj is _pd.NaT:
+            return None
+    if isinstance(obj, dict):
+        return {str(k): jsonsafe(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple, set)):
+        return [jsonsafe(v) for v in obj]
+    if _np is not None and isinstance(obj, _np.ndarray):
+        return [jsonsafe(v) for v in obj.tolist()]
+    if _pd is not None and isinstance(obj, _pd.Series):
+        return [jsonsafe(v) for v in obj.tolist()]
+    if _pd is not None and _pd.isna(obj):
+        return None
+    return str(obj)

f1verse-0.3.0/src/f1verse/crosscheck.py

@@ -0,0 +1,110 @@
+"""Cross-validation layer — publish only when independent sources agree.
+
+One wrong number costs a data project its credibility. ``crosscheck`` runs
+a race through independent checks and returns a machine-readable verdict a
+publishing pipeline can gate on:
+
+- **sector_sum** — s1+s2+s3 must equal the lap time within 3 ms
+  (the same tolerance FastF1 uses internally, recomputed natively).
+- **lap_count** — winner's classified lap count vs the lap table.
+- **gap_monotonic** — classified numeric gaps must increase with position;
+  this is the check that catches the classic lapped-car corruption
+  (``P8 +36.049`` printed above ``P7 +1:19.915``).
+- **lapped_convention** — every ``+N LAP`` row completed fewer laps.
+- **leader_vs_overtakes** — every on-track pass for P1 (independent
+  ``/overtakes`` endpoint) must appear in the position-stream lead changes.
+  The two are *not* equal by design: leads gained through pit cycles are
+  lead changes but not overtakes.
+- **stints_vs_pits** — stint splits explained by pit stops (red-flag tyre
+  changes legitimately add stints without a pit stop; reported, not failed).
+"""
+
+from .sources import openf1
+
+
+def _check(name, ok, detail):
+    return {"name": name, "status": "ok" if ok else "mismatch",
+            "detail": detail}
+
+
+def crosscheck(race) -> dict:
+    checks = []
+
+    # -- lap_count ----------------------------------------------------------
+    winner = next((r for r in race.result if r.get("position") == 1), {})
+    table_max = race.total_laps
+    ok = winner.get("number_of_laps") == table_max
+    checks.append(_check("lap_count", ok,
+                         f"winner classified {winner.get('number_of_laps')} laps,"
+                         f" lap table max {table_max}"))
+
+    # -- sector_sum (FastF1's 3 ms tolerance, recomputed natively) ----------
+    bad = total = 0
+    for l in race.laps:
+        s = (l.get("duration_sector_1"), l.get("duration_sector_2"),
+             l.get("duration_sector_3"), l.get("lap_duration"))
+        if all(x is not None for x in s):
+            total += 1
+            if abs(s[0] + s[1] + s[2] - s[3]) > 0.003:
+                bad += 1
+    checks.append(_check("sector_sum", bad / max(total, 1) < 0.02,
+                         f"{bad}/{total} laps off by >3ms"))
+
+    # -- gap_monotonic (the lapped-car trap, as an invariant) ---------------
+    prev, breaks = None, []
+    for r in race.results():
+        g = r["gap"]
+        if g.startswith("+") and "LAP" not in g:
+            sec = (lambda s: sum(float(x) * m for x, m in
+                                 zip(reversed(s.rstrip("s").lstrip("+").split(":")),
+                                     (1, 60))))(g)
+            if prev is not None and sec < prev:
+                breaks.append(r["abbr"])
+            prev = sec
+    checks.append(_check("gap_monotonic", not breaks,
+                         f"out-of-order gaps: {breaks or 'none'}"))
+
+    # -- lapped_convention --------------------------------------------------
+    wrong = [r["abbr"] for r in race.results()
+             if "LAP" in r["gap"] and (r.get("laps") or 0) >= table_max]
+    checks.append(_check("lapped_convention", not wrong,
+                         f"'+N LAP' rows with full distance: {wrong or 'none'}"))
+
+    # -- leader_vs_overtakes (independent endpoint) -------------------------
+    runs = [r["abbr"] for r in race.leader_runs()]
+    ot = sorted(openf1.get("overtakes", session_key=race.session_key,
+                           position=1), key=lambda o: o["date"])
+    seq, prev_n = [], None
+    for o in ot:
+        n = o["overtaking_driver_number"]
+        if n != prev_n:
+            seq.append(race.abbr(n))
+            prev_n = n
+    # on-track P1 passes must be a subsequence of all lead changes —
+    # pit-cycle lead changes legitimately have no matching overtake
+    changes = [b for a, b in zip([None] + runs, runs) if a != b][1:]
+    passes = [b for a, b in zip([None] + seq, seq) if a != b]
+    it = iter(changes)
+    ok = all(any(p == c for c in it) for p in passes)
+    checks.append(_check(
+        "leader_vs_overtakes", ok,
+        f"on-track P1 passes {passes} ⊆ lead changes {changes}"
+        + ("" if ok else " — FAILED")))
+
+    # -- stints_vs_pits (informational) -------------------------------------
+    pit_per = {}
+    for p in race.pits:
+        pit_per[p["driver_number"]] = pit_per.get(p["driver_number"], 0) + 1
+    unexplained = []
+    for num, sts in ((n, [s for s in race.stints_raw
+                          if s["driver_number"] == n])
+                     for n in race.drivers):
+        extra = (len(sts) - 1) - pit_per.get(num, 0)
+        if extra > 1:  # >1 non-pit stint split is suspicious even with a red flag
+            unexplained.append(race.abbr(num))
+    checks.append(_check("stints_vs_pits", not unexplained,
+                         f"suspicious stint splits: {unexplained or 'none'}"))
+
+    mismatches = [c["name"] for c in checks if c["status"] != "ok"]
+    return {"checks": checks, "mismatches": mismatches,
+            "publishable": not mismatches}

f1verse-0.3.0/src/f1verse/feeds.py

@@ -0,0 +1,72 @@
+"""Harvest live-timing feeds that FastF1 knows about but never parses.
+
+The official archive names 21 topics; FastF1 parses ~13. Three of the
+dropped feeds are genuinely valuable:
+
+- ``ChampionshipPrediction`` — per-lap "if the race ended now" projection.
+- ``TeamRadio`` — timestamped team-radio clip paths (URLs only, no media).
+- ``TimingStats`` — personal bests and speed-trap figures.
+
+Every function accepts either a loaded FastF1 ``Session`` or an
+``f1verse.Race`` — anything exposing ``.api_path``.
+"""
+import copy
+
+from ._json import jsonsafe
+from .sources.livetiming import BASE, deepmerge, fetch_stream
+
+
+def _path(session) -> str:
+    p = getattr(session, "api_path", None)
+    if not p:
+        raise TypeError("expected a FastF1 Session or f1verse.Race")
+    return p
+
+
+def championship_prediction(session) -> dict:
+    """Live championship projection through the race.
+
+    Returns ``{"series", "final", "leader_changes"}`` where
+    ``leader_changes`` are the moments the *projected champion* changed —
+    the moments no broadcast graphic shows.
+    """
+    series, state = [], {}
+    for t, patch in fetch_stream(_path(session), "ChampionshipPrediction.jsonStream"):
+        state = deepmerge(state, patch)
+        if state.get("Drivers"):
+            series.append({"t": t, "state": copy.deepcopy(state)})
+    changes, prev = [], None
+    for snap in series:
+        drivers = snap["state"].get("Drivers", {})
+        leader = min((d for d in drivers.values() if d.get("PredictedPosition")),
+                     key=lambda d: d["PredictedPosition"], default=None)
+        num = leader and leader.get("RacingNumber")
+        if num and num != prev:
+            if prev is not None:
+                changes.append({"t": snap["t"], "to": num, "from": prev})
+            prev = num
+    return jsonsafe({"series": series,
+                     "final": series[-1]["state"] if series else {},
+                     "leader_changes": changes})
+
+
+def team_radio(session) -> list:
+    """Timestamped team-radio clips: URLs only, nothing downloaded."""
+    clips, path = [], _path(session)
+    for t, patch in fetch_stream(path, "TeamRadio.jsonStream"):
+        caps = patch.get("Captures")
+        items = caps.values() if isinstance(caps, dict) else (caps or [])
+        for c in items:
+            if isinstance(c, dict) and c.get("Path"):
+                clips.append({"t": t, "utc": c.get("Utc"),
+                              "driver_number": c.get("RacingNumber"),
+                              "url": BASE + path + c["Path"]})
+    return jsonsafe(clips)
+
+
+def timing_stats(session) -> dict:
+    """Final personal bests / best sectors / speed-trap figures per driver."""
+    state = {}
+    for _, patch in fetch_stream(_path(session), "TimingStats.jsonStream"):
+        state = deepmerge(state, patch)
+    return jsonsafe(state.get("Lines", {}))

f1verse-0.3.0/src/f1verse/gaps.py

@@ -0,0 +1,43 @@
+"""Broadcast-convention gap formatting.
+
+FastF1's ``results['Time']`` is **not** a gap for lapped cars — the raw value
+can be *smaller* than a car that finished ahead on the lead lap::
+
+    P7  LAW  +1:19.915   Status=Finished
+    P8  HUL    +36.049   Status=Lapped    <- looks ahead of P7!
+
+No error, no warning — naive tables are silently wrong. ``format_gap``
+applies the convention every broadcast uses instead.
+"""
+import math
+
+
+def _seconds(td):
+    if td is None:
+        return None
+    try:
+        s = td.total_seconds()
+    except AttributeError:
+        s = float(td)
+    return None if math.isnan(s) else s
+
+
+def format_seconds(total: float) -> str:
+    if total >= 60:
+        return f"+{int(total // 60)}:{total % 60:06.3f}"
+    return f"+{total:.3f}s"
+
+
+def format_gap(status, time_delta, position=None, laps_down=None) -> str:
+    """Human gap string for one classified result row (broadcast convention)."""
+    if position == 1:
+        return "WINNER"
+    if status == "Lapped":
+        n = int(laps_down) if laps_down else 1
+        return f"+{n} LAP" if n == 1 else f"+{n} LAPS"
+    if status == "Disqualified":
+        return "DSQ"
+    if status != "Finished":
+        return "DNF"
+    s = _seconds(time_delta)
+    return "" if s is None else format_seconds(s)

f1verse-0.3.0/src/f1verse/http.py

@@ -0,0 +1,49 @@
+"""Tiny cached HTTP layer — standard library only, zero dependencies.
+
+One on-disk cache, BOM-safe JSON, polite pacing, gzip support.
+Completed-session responses are immutable, so caching is aggressive.
+"""
+import gzip
+import hashlib
+import json
+import time
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+_UA = "f1verse (+https://github.com/jinsim/f1verse)"
+_cache_dir = Path.home() / ".cache" / "f1verse"
+_last_request = 0.0
+
+
+def enable_cache(path) -> None:
+    """Override the cache directory (default ``~/.cache/f1verse``)."""
+    global _cache_dir
+    _cache_dir = Path(path)
+
+
+def get_text(url: str, params: dict | None = None) -> str:
+    global _last_request
+    if params:
+        url = url + "?" + urllib.parse.urlencode(params)
+    f = _cache_dir / hashlib.sha256(url.encode()).hexdigest()[:24]
+    if f.exists():
+        return f.read_text()
+    wait = 0.5 - (time.monotonic() - _last_request)
+    if wait > 0:
+        time.sleep(wait)
+    req = urllib.request.Request(
+        url, headers={"User-Agent": _UA, "Accept-Encoding": "gzip"})
+    with urllib.request.urlopen(req, timeout=60) as r:
+        raw = r.read()
+        if r.headers.get("Content-Encoding") == "gzip":
+            raw = gzip.decompress(raw)
+    _last_request = time.monotonic()
+    text = raw.decode("utf-8-sig")  # livetiming serves BOM-prefixed JSON
+    _cache_dir.mkdir(parents=True, exist_ok=True)
+    f.write_text(text)
+    return text
+
+
+def get_json(url: str, params: dict | None = None):
+    return json.loads(get_text(url, params))