installation:

uv python install 3.14 --default

uv venv --seed

pyf1n

A Python-first toolkit for Formula 1 data, from historical results to live timing and session replay.

[!IMPORTANT] pyf1n is in pre-alpha. Version 0.0.1 establishes the package, project boundaries, and development direction. It does not yet provide the complete data client described below, and its interfaces may change without notice.

What pyf1n will be

Formula 1 data is available through several Formula 1-operated services, but each source exposes different identifiers, payload shapes, time ranges, and levels of detail. Building against those sources directly means handling that fragmentation in every application.

pyf1n will provide one consistent Python interface over those sources. It will discover seasons, meetings, and sessions; retrieve historical and live session data; and convert source-specific responses into predictable, typed domain models.

The Python package will also be the shared foundation for a REST API and a web application. These will remain separate applications: installing pyf1n will not install FastAPI, React, or either application's runtime dependencies.

Project goals

• Provide a simple route from a season to a meeting, session, and its data.
• Normalize Formula 1 results and LiveTiming payloads behind stable Python models.
• Cover historical results, classifications, laps, sectors, stints, tyres, weather, race-control messages, telemetry, and car position where the upstream data permits it.
• Subscribe to live sessions and expose incremental updates as coherent session state.
• Persist live events so a session can be reconstructed or replayed from a chosen time or lap.
• Preserve source provenance and make unavailable data explicit instead of silently inventing values.
• Offer the same underlying capabilities through Python, HTTP, and an interactive web interface.

Data sources

The project will prioritize JSON data from Formula 1-controlled sources:

pyf1n will not rely on scraping Formula 1 web pages for HTML content. Formula 1-operated endpoints are upstream dependencies rather than guaranteed public APIs, so their availability and response formats may change.

Delivery surfaces

flowchart TD
    User["Python user"] --> Core["pyf1n package"]
    Web["React web app"] -->|HTTP| API["FastAPI service"]
    API --> Core
    Core --> Sources["FOM and LiveTiming"]
    Core --> Data["Cache and reference data"]

The dependency direction is deliberate: the API depends on pyf1n, while pyf1n knows nothing about the API or web application. This keeps the package independently useful and independently publishable.

Intended interface

The final public interface is still being designed. The following examples show the intended experience rather than an API available in 0.0.1:

from pyf1n import Client

client = Client()

meeting = client.meetings.get(
    season=2026,
    meeting="australia",
)

qualifying = client.sessions.results(
    season=2026,
    meeting="australia",
    session="qualifying",
)

The REST API will expose the same domain using descriptive, navigable routes:

GET /api/v1/seasons/2026/meetings/australia/sessions/qualifying

Package and API models will be designed together so Python and HTTP consumers receive equivalent data without duplicating the source-integration logic.

Repository structure

pyf1n/
├── apps/
│   ├── api/                 # FastAPI application
│   └── web/                 # React application
├── config/                  # Project and source configuration
├── src/
│   └── pyf1n/
│       ├── clients/         # Formula 1 source adapters
│       ├── models/          # Normalized domain models
│       ├── services/        # Cross-source orchestration
│       └── utils/           # Shared package utilities
├── LICENSE
├── pyproject.toml           # Distributable pyf1n package
└── uv.lock

Only the code beneath src/pyf1n/ is part of the distributable Python package.

Installation

After the preview release is published, it can be installed with either command:

pip install pyf1n==0.0.1

uv add pyf1n==0.0.1

Version 0.0.1 is a project preview and should not be used for production integrations.

Development

The project uses uv for Python dependency and environment management. From the repository root:

uv sync

Development will follow a library-first approach: source access, normalization, and domain behavior belong in src/pyf1n/; HTTP-specific behavior belongs in apps/api/; presentation behavior belongs in apps/web/.

Current status

Version 0.0.1 is the starting point. It defines the purpose and boundaries of the project while the first source clients, domain models, and public operations are built. There are no compatibility guarantees before a stable interface is documented.

Disclaimer

pyf1n is an independent project. It is not affiliated with, endorsed by, or associated with Formula 1, the FIA, or Formula One Group. Users are responsible for complying with the terms that apply to upstream services and data.

License

See LICENSE for the project's licence terms.