Skip to main content
tif1 runs inside Pyodide, the CPython build for WebAssembly behind JupyterLite, PyScript, and marimo. The browser fetches the data, and the SQLite cache lives in the memory of the page. await session.load_async() loads a session through the same concurrent pipeline as a native install.

Overview

A browser runtime differs from a native interpreter in three ways. tif1 detects Pyodide at import time (sys.platform == "emscripten") and adapts to each one:

Installation

Install tif1 with micropip. The Pyodide distribution provides pandas, numpy, pyarrow, orjson, pydantic, matplotlib, scipy, and urllib3. micropip downloads the pure Python packages from PyPI.
The polars backend, rapidfuzz, and niquests have no WebAssembly build, so micropip does not install them. Sessions use the pandas backend. Event-name resolution uses a pure Python matcher that gives the same scores as rapidfuzz.

Loading a Session

get_session() works as on a native install. Load the data with load_async(), the async twin of load(). It fetches the session tables in one concurrent wave per phase through the fetch API of the browser.
Pyodide
The other async methods work the same way: laps_async(), get_fastest_laps_async(), get_fastest_laps_tels_async(), get_fastest_lap_tel_async(), fetch_driver_laps_parallel(), and fetch_all_laps_telemetry_async(). Data in the session memo or in the cache is served synchronously. After load_async(), session.laps needs no event loop.

The Synchronous API and JSPI

session.load() and the lazy properties block until the data arrives. In the browser they can only block when the runtime has JavaScript Promise Integration (JSPI) and the code was entered through runPythonAsync or a notebook cell. Chrome 137 and later enable JSPI by default. Firefox keeps it behind the javascript.options.wasm_js_promise_integration flag. Node 24 needs --experimental-wasm-jspi. Without JSPI, the synchronous entry points raise AsyncRequiredError. The message names the coroutine to await instead:
tif1 recommends load_async() in browser code. It works in each browser and keeps the page responsive.

Network

All requests go through the browser, so the CORS policy of each CDN applies. jsDelivr, the Hugging Face bucket, and StaticDelivr answer with Access-Control-Allow-Origin headers. The live schedule source on GitHub does the same. A mirror that the page cannot reach counts as a failed source, and tif1 tries the next CDN. Timeouts, retries, and the circuit breaker work as on a native install. The browser owns redirects, compression, and TLS. The HTTP/2, DNS resolver, and connection pool settings have no effect.

Cache

The SQLite cache opens in the Emscripten file system of the page (~/.tif1) with an in-memory rollback journal. The memory of the page is lost on reload. To keep the cache across reloads, mount the cache directory on IndexedDB before the first get_session(). Write it back after the loads that must survive:
Pyodide
Browsers never run atexit hooks, so persist_cache() is the only point where the cache reaches IndexedDB. After a reload, enable_persistent_cache() loads the stored cache before the first session.

Limitations

  • The polars backend is not available. lib="polars" falls back to pandas with a warning.
  • The tif1 command line tool does not run in the browser.
  • Streaming responses, HTTP/2 multiplexing, DNS-over-HTTPS resolvers, and connection statistics belong to the browser and are not configurable.
  • tif1.plotting.load_custom_font() needs a font URL with CORS headers.

Browser API

PyodideTransport, enable_persistent_cache(), and persist_cache().

Jupyter Integration

HTML cards for sessions, drivers, and laps in notebook front ends.

Caching Strategy

The cache tiers behind each load.

Exceptions

AsyncRequiredError and the rest of the hierarchy.
Last modified on October 28, 2026