vlrdevapi 2.1.0__tar.gz → 2.2.0__tar.gz

{vlrdevapi-2.1.0 → vlrdevapi-2.2.0}/.gitattributes

@@ -4,4 +4,8 @@ docs-py/** linguist-vendored
 
 # Exclude test fixtures
 tests/test_html/** linguist-vendored
-tests/test_html/** linguist-detectable=false
+tests/test_html/** linguist-detectable=false
+
+# Normalize workflow YAML line endings
+*.yml text eol=lf
+*.yaml text eol=lf

vlrdevapi-2.2.0/.github/workflows/cleanup-caches.yml

@@ -0,0 +1,31 @@
+name: Cleanup docs-check caches on closed PRs
+
+on:
+  pull_request:
+    types:
+      - closed
+
+permissions:
+  actions: write
+
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Delete PR caches
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          BRANCH: refs/pull/${{ github.event.pull_request.number }}/merge
+        run: |
+          echo "Fetching list of cache keys"
+          cacheKeysForPR=$(gh cache list --ref $BRANCH --limit 100 --json id --jq '.[].id')
+
+          ## Setting this to not fail the workflow while deleting cache keys.
+          set +e
+          echo "Deleting caches..."
+          for cacheKey in $cacheKeysForPR
+          do
+            gh cache delete $cacheKey
+          done
+          echo "Done"

vlrdevapi-2.2.0/.github/workflows/docs-check.yml

@@ -0,0 +1,102 @@
+name: Docs Check
+
+on:
+  pull_request:
+    paths:
+      - 'official-docs/**'
+      - 'docs-py/**'
+  push:
+    branches: [main]
+    paths:
+      - 'official-docs/**'
+      - 'docs-py/**'
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b
+        with:
+          python-version: '3.12'
+
+      - name: Install package
+        run: uv sync --group dev
+
+      # main always validates live against fresh vlr.gg data; never uses the
+      # cache. Branch/PR runs reuse fixtures cached by earlier runs in the
+      # same PR (within a 2h TTL), falling back to live fetches for anything
+      # missing, so the check is correct even with a partially-stale cache.
+      - name: Run MDX examples check (main, live)
+        if: github.ref_name == 'main'
+        run: uv run scripts/check_mdx_examples.py --live
+
+      # actions/cache v6.1.0, pinned to a reviewed commit SHA.
+      - name: Restore fixture cache (branch)
+        id: mdx-fixtures
+        if: github.ref_name != 'main'
+        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9
+        with:
+          path: fixtures.tar.gz
+          key: mdx-fixtures-${{ github.ref_name }}-run-${{ github.run_id }}
+          restore-keys: |
+            mdx-fixtures-${{ github.ref_name }}-
+
+      - name: Unpack fixtures (branch)
+        if: github.ref_name != 'main'
+        run: |
+          if [ -f fixtures.tar.gz ]; then
+            mkdir -p .cache
+            tar -C .cache -xzf fixtures.tar.gz
+          fi
+
+      - name: Check fixture cache age (branch, 2h TTL)
+        id: cache-age
+        if: github.ref_name != 'main'
+        run: |
+          matched="${{ steps.mdx-fixtures.outputs.cache-matched-key }}"
+          now=$(date +%s)
+          if [ -n "$matched" ]; then
+            epoch="${matched##*-}"
+            age=$(( now - epoch ))
+          else
+            age=999999
+          fi
+          if [ "$age" -gt 7200 ]; then
+            rm -rf .cache/mdx-html
+            rm -f fixtures.tar.gz
+            mkdir -p .cache/mdx-html
+            echo "fresh=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "fresh=true" >> "$GITHUB_OUTPUT"
+          fi
+          echo "now=$now" >> "$GITHUB_OUTPUT"
+
+      - name: Run MDX examples check (branch)
+        if: github.ref_name != 'main'
+        run: |
+          if [ "${{ steps.cache-age.outputs.fresh }}" == "true" ]; then
+            uv run scripts/check_mdx_examples.py --skip-warm
+          else
+            uv run scripts/check_mdx_examples.py
+          fi
+
+      # always(): a run that fails validation still saved its warm fixtures,
+      # so the next fix commit restores and validates fast instead of warming.
+      - name: Package fixtures (branch)
+        if: always() && github.ref_name != 'main' && steps.cache-age.outputs.fresh == 'false'
+        run: |
+          mkdir -p .cache/mdx-html
+          if [ -n "$(ls -A .cache/mdx-html)" ]; then
+            tar -C .cache -czf fixtures.tar.gz mdx-html
+          else
+            rm -f fixtures.tar.gz
+          fi
+
+      - name: Save fixture cache (branch)
+        if: always() && github.ref_name != 'main' && steps.cache-age.outputs.fresh == 'false'
+        uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9
+        with:
+          path: fixtures.tar.gz
+          key: mdx-fixtures-${{ github.ref_name }}-${{ steps.cache-age.outputs.now }}

{vlrdevapi-2.1.0 → vlrdevapi-2.2.0}/.gitignore

@@ -9,6 +9,8 @@ wheels/
 # Virtual environments
 .venv
 tests/test_html/
+.cache/mdx-html/
+fixtures.tar.gz
 
 nul
 .pytest_cache/

{vlrdevapi-2.1.0 → vlrdevapi-2.2.0}/CHANGELOG.md

@@ -5,7 +5,7 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
-## [Unreleased]
+## [2.2.0] - 2026-08-11
 
 ### Changed
 
@@ -14,6 +14,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
   sentinel year of `2019` instead of the current year. Any parsed date with
   `year < 2020` means the source omitted the year, so guard with
   `event.start_date.year < 2020` before relying on it.
+- **Series performance field renames (breaking)** — `AdvStatsEntry` fields
+  were renamed to descriptive names: `econ` → `economy`, `pl` → `plants`,
+  and `de` → `defuses`. Update any code referencing the old field names.
+  The series performance reference docs were updated to match.
 
 ### Fixed
 
@@ -22,6 +26,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
   change behavior in Python 3.15). All such parses now supply an explicit
   year derived from context (reference date, page-header year, or the
   sentinel above).
+- **Series per-game stats by game number** — `players()`, `rounds()`,
+  `performance()`, and `economy()` game identifiers can now be a 1-based
+  game number within the series, resolved to the real VLR game ID from the
+  page's game nav tabs. A real VLR game ID is still accepted unchanged;
+  previously passing a game number produced empty results.
+- **Series economy and rounds scope** — economy and round-by-round data are
+  now parsed from the selected game's section only. The economy parser
+  previously collected tables from the whole page, so a per-game request
+  could include data from other maps.
+- **Series performance player IDs** — the performance tab renders player
+  cells without links, leaving player IDs as `0`. IDs are now recovered from
+  the series overview tab (keyed by team abbreviation and player name) and
+  attached to kill-matrix entries, advanced stats, and notable-round victims.
 
 ## [2.1.0] - 2026-08-07
 
@@ -125,6 +142,7 @@ The API surface, module structure, and type system are all new.
 - `aiohttp` and `asyncio` dependencies.
 - v1.x match/event/team parsing modules.
 
+[2.2.0]: https://github.com/Vanshbordia/vlrdevapi/compare/v2.1.0...v2.2.0
 [2.1.0]: https://github.com/Vanshbordia/vlrdevapi/compare/v2.0.1...v2.1.0
 [2.0.1]: https://github.com/Vanshbordia/vlrdevapi/compare/v2.0.0...v2.0.1
 [2.0.0]: https://github.com/Vanshbordia/vlrdevapi/compare/v1.6.2...v2.0.0

{vlrdevapi-2.1.0 → vlrdevapi-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vlrdevapi
-Version: 2.1.0
+Version: 2.2.0
 Summary: A Python library to scrape data from vlr.gg
 Project-URL: Homepage, https://vlrdevapi.pages.dev/
 Project-URL: Repository, https://github.com/Vanshbordia/vlrdevapi

{vlrdevapi-2.1.0 → vlrdevapi-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vlrdevapi"
-version = "2.1.0"
+version = "2.2.0"
 description = "A Python library to scrape data from vlr.gg"
 readme = "README.md"
 requires-python = ">=3.11"

{vlrdevapi-2.1.0 → vlrdevapi-2.2.0}/scripts/check_mdx_examples.py

@@ -2,31 +2,44 @@
 
 Extracts every Python code block from official-docs/content/ (docs,
 blog, guides, etc.), checks syntax validity, import resolution, then
-executes examples against the live vlr.gg API.
+executes examples. An ``httpx.Client.get`` interceptor de-duplicates
+fetches within a run and can replay validation offline against HTML
+fixtures saved under ``.cache/mdx-html/`` (gitignored).
 
 CI/CD usage:
-    python scripts/check_mdx_examples.py              # syntax + imports + run
-    python scripts/check_mdx_examples.py --timeout 60  # custom per-example timeout
+    python scripts/check_mdx_examples.py              # warm + offline replay
+    python scripts/check_mdx_examples.py --skip-warm  # offline replay only
+    python scripts/check_mdx_examples.py --live       # single live pass
+    python scripts/check_mdx_examples.py --timeout 60 # custom per-example timeout
 """
 
 from __future__ import annotations
 
 import ast
 import asyncio
+import hashlib
 import importlib
 import io
 import os
 import re
 import sys
 import textwrap
+import threading
 import time
 import traceback
-from contextlib import redirect_stdout, redirect_stderr
+from contextlib import redirect_stderr, redirect_stdout
 from pathlib import Path
 from typing import NamedTuple
 
+import httpx
+
+from vlrdevapi.fetcher import DEFAULT_RATE_LIMIT, RateLimiter
+
 REPO_ROOT = Path(__file__).resolve().parent.parent
 DOCS_DIR = REPO_ROOT / "official-docs" / "content"
+DEFAULT_FIXTURES_DIR = REPO_ROOT / ".cache" / "mdx-html"
+
+DYNAMIC_PATHS = frozenset({"/matches", "/matches/results", "/events"})
 
 
 class Result(NamedTuple):
@@ -41,6 +54,142 @@ class Result(NamedTuple):
     duration: float
 
 
+# ---------------------------------------------------------------------------
+# HTTP cache (dedup + offline replay)
+# ---------------------------------------------------------------------------
+
+class HTTPCache:
+    """Thread-safe HTTP response cache that intercepts ``httpx.Client.get``.
+
+    Patched at the class level so every library request — sync, parallel
+    worker threads, enrichment, and the dark-mode team info double fetch —
+    funnels through it (all go via ``fetcher.fetch_sync`` ->
+    ``client.get``). Keys are sha256 of the resolved URL + sorted headers,
+    so the same path fetched with a different ``Cookie`` header (dark mode)
+    gets a distinct cache entry.
+
+    Modes:
+        record: disk hit -> reuse (no network); miss -> live fetch + cache.
+        replay: hit -> reuse; miss -> live fallback (no disk writes).
+        live:   in-memory only; miss -> live fetch + memory cache.
+
+    Time-varying listing pages (``/matches``, ``/matches/results``,
+    ``/events``) are treated as dynamic: always fetched live, deduplicated
+    in memory only, and never persisted to disk. Serving a stale cached
+    fixture for these could silently validate examples against outdated
+    match data.
+    """
+
+    def __init__(self, fixtures_dir: Path | None, mode: str) -> None:
+        self.fixtures_dir = fixtures_dir
+        self.mode = mode
+        self._lock = threading.Lock()
+        self._mem: dict[str, str] = {}
+        self._orig_get = None
+        self.total_requests = 0
+        self.live_fetches = 0
+        self.hits_mem = 0
+        self.hits_disk = 0
+        self.misses = 0
+        self.live_fallbacks = 0
+        self.unique_pages: set[str] = set()
+
+    def install(self) -> None:
+        """Patch ``httpx.Client.get`` at the class level."""
+        if self._orig_get is None:
+            self._orig_get = httpx.Client.get
+            cache = self
+            orig_get = self._orig_get
+
+            def _intercept(client: httpx.Client, url: str, **kwargs) -> httpx.Response:
+                return cache._handle(client, url, orig_get, **kwargs)
+
+            httpx.Client.get = _intercept  # type: ignore[method-assign]
+
+    def restore(self) -> None:
+        """Restore the original ``httpx.Client.get``."""
+        if self._orig_get is not None:
+            httpx.Client.get = self._orig_get  # type: ignore[method-assign]
+            self._orig_get = None
+
+    def _key(self, request: httpx.Request, headers: dict[str, str] | None) -> str:
+        header_items = sorted((headers or {}).items())
+        payload = f"{request.url}|{header_items!r}".encode()
+        return hashlib.sha256(payload).hexdigest()
+
+    def _lookup(self, key: str, allow_disk: bool = True) -> str | None:
+        with self._lock:
+            html = self._mem.get(key)
+            if html is not None:
+                self.hits_mem += 1
+                return html
+            if allow_disk and self.fixtures_dir is not None:
+                fixture = self.fixtures_dir / f"{key}.html"
+                if fixture.exists():
+                    try:
+                        html = fixture.read_text(encoding="utf-8")
+                    except OSError:
+                        html = None
+                    if html is not None:
+                        self._mem[key] = html
+                        self.hits_disk += 1
+                        return html
+            return None
+
+    def _store(self, key: str, html: str, to_disk: bool = True) -> None:
+        with self._lock:
+            self._mem[key] = html
+            if to_disk and self.mode == "record" and self.fixtures_dir is not None:
+                try:
+                    self.fixtures_dir.mkdir(parents=True, exist_ok=True)
+                    fixture = self.fixtures_dir / f"{key}.html"
+                    if not fixture.exists():
+                        fixture.write_text(html, encoding="utf-8")
+                except OSError:
+                    pass
+
+    def _throttle(self) -> None:
+        if DEFAULT_RATE_LIMIT > 0:
+            time.sleep(1.0 / DEFAULT_RATE_LIMIT)
+
+    def _handle(
+        self,
+        client: httpx.Client,
+        url: str,
+        orig_get,
+        **kwargs,
+    ) -> httpx.Response:
+        self.total_requests += 1
+        headers = kwargs.get("headers")
+        request = client.build_request("GET", url, headers=headers)
+        key = self._key(request, headers)
+        self.unique_pages.add(key)
+        dynamic = request.url.path in DYNAMIC_PATHS
+
+        cached = self._lookup(key, allow_disk=not dynamic)
+        if cached is not None:
+            return httpx.Response(200, text=cached, request=request)
+
+        self.misses += 1
+        if self.mode == "replay":
+            self.live_fallbacks += 1
+            self._throttle()
+        self.live_fetches += 1
+        resp = orig_get(client, url, **kwargs)
+        if resp.status_code == 200 and self.mode in ("record", "live"):
+            self._store(key, resp.text, to_disk=not dynamic)
+        return resp
+
+
+class RunStats:
+    """Durations for each phase, reported in the summary footer."""
+
+    def __init__(self) -> None:
+        self.phase1 = 0.0
+        self.warm = 0.0
+        self.replay = 0.0
+
+
 # ---------------------------------------------------------------------------
 # Extractors
 # ---------------------------------------------------------------------------
@@ -96,10 +245,7 @@ def is_signature_block(code: str) -> bool:
 
     # Last line: ")" or ") -> ReturnType"
     last = lines[-1].strip()
-    if not re.match(r"^\s*\)\s*(->\s*\S+)?\s*$", last):
-        return False
-
-    return True
+    return bool(re.match(r"^\s*\)\s*(->\s*\S+)?\s*$", last))
 
 
 def normalize_code(code: str) -> str:
@@ -190,7 +336,7 @@ async def exec_async(code: str, timeout: float) -> tuple[bool, str, float]:
             wrapped = "async def __example():\n" + textwrap.indent(code, "    ")
 
         compiled = compile(wrapped, "<doc_example>", "exec")
-        exec(compiled, namespace)
+        exec(compiled, namespace)  # noqa: S102
         out = io.StringIO()
         err = io.StringIO()
         with redirect_stdout(out), redirect_stderr(err):
@@ -205,9 +351,9 @@ async def exec_async(code: str, timeout: float) -> tuple[bool, str, float]:
             output += "\n[stderr]\n" + err.getvalue().strip()
         return True, output, elapsed
 
-    except asyncio.TimeoutError:
+    except TimeoutError:
         return False, f"TIMEOUT after {time.monotonic() - start:.1f}s", time.monotonic() - start
-    except Exception as e:
+    except Exception as e:  # noqa: BLE001
         tb = traceback.format_exc()
         return False, f"{type(e).__name__}: {e}\n{tb}", time.monotonic() - start
 
@@ -229,7 +375,7 @@ async def exec_sync(code: str, timeout: float) -> tuple[bool, str, float]:
         out = io.StringIO()
         err = io.StringIO()
         with redirect_stdout(out), redirect_stderr(err):
-            exec(compiled, namespace)
+            exec(compiled, namespace)  # noqa: S102
         return out.getvalue().strip() or "(no output)"
 
     loop = asyncio.get_running_loop()
@@ -241,9 +387,9 @@ async def exec_sync(code: str, timeout: float) -> tuple[bool, str, float]:
         if not ok:
             return False, msg, time.monotonic() - start
         return True, output, time.monotonic() - start
-    except asyncio.TimeoutError:
+    except TimeoutError:
         return False, f"TIMEOUT after {time.monotonic() - start:.1f}s", time.monotonic() - start
-    except Exception as e:
+    except Exception as e:  # noqa: BLE001
         return False, f"{type(e).__name__}: {e}", time.monotonic() - start
 
 
@@ -255,12 +401,67 @@ def has_skip_marker(code: str) -> bool:
     return any(line.strip().startswith("# doc-check: skip") for line in code.splitlines())
 
 
-async def run_all(timeout: float) -> list[Result]:
+async def execute_blocks(
+    results: list[Result],
+    timeout: float,
+    cache: HTTPCache,
+    label: str,
+    *,
+    record_results: bool,
+) -> None:
+    """Execute every runnable block against the current cache mode.
+
+    In warm mode (``record_results=False``) execution is best-effort: the
+    point is to populate the cache/fixtures and de-duplicate fetches, so
+    failures do not affect the run. In replay/live mode (``record_results=True``)
+    results are recorded and validated.
+    """
+    print(f"=== Phase: {label} ===")
+    for i, r in enumerate(results):
+        code = r.code
+
+        # Skip non-runnable blocks
+        if not is_runnable(code):
+            continue
+
+        # Skip user-marked blocks
+        if has_skip_marker(code):
+            continue
+
+        if is_async(code):
+            run_ok, run_msg, dur = await exec_async(code, timeout)
+        else:
+            run_ok, run_msg, dur = await exec_sync(code, timeout)
+
+        if record_results:
+            results[i] = Result(
+                r.file, r.code, r.syntax_ok, r.syntax_error, r.imports_ok,
+                r.import_errors, run_ok, run_msg, dur,
+            )
+            tag = "OK" if run_ok else "FAIL"
+        else:
+            tag = "warm-ok" if run_ok else "warm-err"
+
+        print(f"  {tag} ({dur:.1f}s)  {r.file}")
+        if record_results:
+            msg_short = run_msg[:200].replace("\n", "\\n")
+            print(f"    -> {msg_short}")
+
+
+async def run_all(
+    timeout: float,
+    cache: HTTPCache,
+    *,
+    skip_warm: bool,
+    live: bool,
+) -> tuple[list[Result], RunStats]:
+    stats = RunStats()
     results: list[Result] = []
 
     print("=== Phase 1: Syntax & Import Check ===")
+    phase1_start = time.monotonic()
     for path in sorted(all_doc_files()):
-        with open(path, encoding="utf-8") as f:
+        with open(path, encoding="utf-8") as f:  # noqa: ASYNC230
             text = f.read()
         blocks = extract_blocks(text)
         rel = os.path.relpath(path, REPO_ROOT)
@@ -297,37 +498,39 @@ async def run_all(timeout: float) -> list[Result]:
             results.append(Result(rel, code, True, "", True, [], None, "", 0.0))
             print(f"  OK  {rel}")
 
+    stats.phase1 = time.monotonic() - phase1_start
     print(f"\n  >> Phase 1 complete: all {len(results)} block(s) OK\n")
 
-    print(f"=== Phase 2: Live Execution ({timeout}s timeout per block) ===")
-    for i, r in enumerate(results):
-        code = r.code
-
-        # Skip non-runnable blocks
-        if not is_runnable(code):
-            print(f"  SKIP (no function call)  {r.file}")
-            continue
-
-        # Skip user-marked blocks
-        if has_skip_marker(code):
-            print(f"  SKIP (marker)  {r.file}")
-            continue
-
-        if is_async(code):
-            run_ok, run_msg, dur = await exec_async(code, timeout)
-        else:
-            run_ok, run_msg, dur = await exec_sync(code, timeout)
-
-        results[i] = Result(r.file, r.code, r.syntax_ok, r.syntax_error, r.imports_ok, r.import_errors, run_ok, run_msg, dur)
-        tag = "OK" if run_ok else "FAIL"
-        print(f"  {tag} ({dur:.1f}s)  {r.file}")
-        msg_short = run_msg[:200].replace("\n", "\\n")
-        print(f"    -> {msg_short}")
+    if live:
+        cache.mode = "live"
+        print(f"=== Live execution ({timeout}s timeout per block, in-memory dedup) ===")
+        replay_start = time.monotonic()
+        await execute_blocks(results, timeout, cache, "Live (validated)", record_results=True)
+        stats.replay = time.monotonic() - replay_start
+        return results, stats
+
+    if not skip_warm:
+        cache.mode = "record"
+        warm_start = time.monotonic()
+        await execute_blocks(results, timeout, cache, "Warm (record fixtures)", record_results=False)
+        stats.warm = time.monotonic() - warm_start
+        print(f"\n  >> Warm phase complete: fixtures ready in {cache.fixtures_dir}\n")
+
+    cache.mode = "replay"
+    print(f"=== Replay execution ({timeout}s timeout per block, offline against fixtures) ===")
+    orig_acquire = RateLimiter.acquire
+    RateLimiter.acquire = lambda self: None  # type: ignore[method-assign]
+    try:
+        replay_start = time.monotonic()
+        await execute_blocks(results, timeout, cache, "Replay (validated)", record_results=True)
+        stats.replay = time.monotonic() - replay_start
+    finally:
+        RateLimiter.acquire = orig_acquire  # type: ignore[method-assign]
 
-    return results
+    return results, stats
 
 
-def print_report(results: list[Result]) -> int:
+def print_report(results: list[Result], cache: HTTPCache | None = None, stats: RunStats | None = None) -> int:
     run_attempts = [r for r in results if r.run_ok is not None]
     run_oks = sum(1 for r in run_attempts if r.run_ok is True)
     run_fails = [r for r in results if r.run_ok is False]
@@ -340,6 +543,23 @@ def print_report(results: list[Result]) -> int:
         print(f"  EMPTY OUTPUT FAILURES: {no_output} (prints were silently skipped)")
     print(f"{'='*60}")
 
+    if cache is not None:
+        saved = cache.total_requests - cache.live_fetches
+        print("\nHTTP CACHE STATS:")
+        print(f"  Requests intercepted: {cache.total_requests}")
+        print(f"  Unique pages touched: {len(cache.unique_pages)}")
+        print(f"  Live fetches:         {cache.live_fetches}  (dedup saved {max(saved, 0)})")
+        print(f"  Cache hits:           {cache.hits_mem} mem / {cache.hits_disk} disk")
+        print(f"  Cache misses:         {cache.misses}")
+        if cache.live_fallbacks:
+            print(f"  Live fallbacks:       {cache.live_fallbacks}")
+    if stats is not None:
+        print("\nPHASE DURATIONS:")
+        print(f"  Phase 1 (static): {stats.phase1:.1f}s")
+        if stats.warm:
+            print(f"  Warm  (record):   {stats.warm:.1f}s")
+        print(f"  Replay/validate:  {stats.replay:.1f}s")
+
     if run_fails:
         print(f"\nRUNTIME FAILURES ({len(run_fails)}):")
         for r in run_fails:
@@ -371,8 +591,26 @@ def main():
     parser = argparse.ArgumentParser(description="Check MDX doc examples")
     parser.add_argument("--timeout", type=float, default=60.0, help="Per-example timeout (s)")
     parser.add_argument("--log", type=str, default="", help="Path to save verbose output log")
+    parser.add_argument(
+        "--fixtures-dir", type=str, default=str(DEFAULT_FIXTURES_DIR),
+        help="Directory for cached HTML fixtures (default: .cache/mdx-html)",
+    )
+    parser.add_argument(
+        "--skip-warm", action="store_true",
+        help="Skip the warm (record) phase; replay against existing fixtures",
+    )
+    parser.add_argument(
+        "--live", action="store_true",
+        help="Single live pass with in-memory dedup (no disk fixtures)",
+    )
     args = parser.parse_args()
 
+    fixtures_dir = None
+    if not args.live and args.fixtures_dir:
+        fixtures_dir = Path(args.fixtures_dir)
+    cache = HTTPCache(fixtures_dir=fixtures_dir, mode="replay")
+    stats = RunStats()
+
     log_lines: list[str] = []
 
     # Override print in the check module's namespace
@@ -392,15 +630,18 @@ def main():
     builtins.print = tee_print  # type: ignore
 
     try:
-        results = asyncio.run(run_all(args.timeout))
-        exit_code = print_report(results)
+        cache.install()
+        results, stats = asyncio.run(
+            run_all(args.timeout, cache, skip_warm=args.skip_warm, live=args.live)
+        )
+        exit_code = print_report(results, cache=cache, stats=stats)
     finally:
+        cache.restore()
         builtins.print = orig_print
 
     if args.log:
         with open(args.log, "w", encoding="utf-8") as f:
-            for line in _log_lines:
-                f.write(line + "\n")
+            f.writelines(line + "\n" for line in _log_lines)
         orig_print(f"\nLog saved to: {args.log}")
 
     sys.exit(exit_code)

{vlrdevapi-2.1.0 → vlrdevapi-2.2.0}/src/vlrdevapi/__init__.py

@@ -45,7 +45,7 @@ if TYPE_CHECKING:
     matches: MatchesNamespace
     client: type[VLRClient]
 
-__version__ = "2.1.0"
+__version__ = "2.2.0"
 
 _default_client: "VLRClient | None" = None