Metadata-Version: 2.4
Name: pyf1n-data
Version: 0.0.1
Summary: A Python library for Formula 1 data
Author: Joseph Thomas
Author-email: Joseph Thomas <joemthomas@hotmail.co.uk>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.13
Description-Content-Type: text/markdown

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:

| Source | Intended use |
| --- | --- |
| FOM Results services | Meeting discovery, available datasets, results, and classifications |
| LiveTiming static archive | Detailed data from completed meetings and sessions |
| LiveTiming live feed | Timing, position, telemetry, weather, race control, and other live-session updates |
| Versioned pyf1n reference data | Stable metadata that is absent or inconsistent upstream, such as circuit and location mappings |

`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

| Component | Location | Purpose |
| --- | --- | --- |
| Python package | `src/pyf1n/` | Source clients, normalized models, repositories, and domain services |
| REST API | `apps/api/` | A FastAPI adapter over the Python package |
| Web application | `apps/web/` | A React interface consuming the REST API |

```mermaid
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`:

```python
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:

```http
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

```text
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:

```bash
pip install pyf1n==0.0.1
```

```bash
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](https://docs.astral.sh/uv/) for Python dependency and environment management. From the repository root:

```bash
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](LICENSE) for the project's licence terms.
