timingtower 0.1.0__tar.gz

timingtower-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+          allow-prereleases: true
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - run: uv sync
+
+      - run: uv tool install ruff
+      - run: uv tool install basedpyright
+
+      - name: Format check
+        run: ruff format --check src tests
+
+      - name: Lint
+        run: ruff check src tests
+
+      - name: Type check
+        run: basedpyright
+
+      - name: Test
+        run: uv run pytest

timingtower-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build
+        run: uv build
+
+      - name: Upload dist
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download dist
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

timingtower-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+.env
+
+.pytest_cache/
+.ruff_cache/
+
+# Marimo
+__marimo__/

timingtower-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,6 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.6
+    hooks:
+      - id: ruff-format
+        args: [src, tests]

timingtower-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

timingtower-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,66 @@
+# Contributing to timingtower
+
+Thanks for your interest in contributing! timingtower is in early development (`0.x`), so the API is still evolving - but that also means there's plenty of room to shape things.
+
+## Setup
+Ensure that [uv](https://docs.astral.sh/uv/) and [just](https://just.systems/man/en/installation.html) are installed.
+
+```bash
+git clone https://github.com/bfoley12/timingtower.git
+cd timingtower
+just setup
+```
+
+## Development
+Run tests, lint, and type check before submitting anything:
+
+```bash
+just check
+```
+
+Or individually:
+
+```bash
+ruff format
+ruff check
+basedpyright
+uv run pytest
+```
+
+Both must pass clean.
+
+## What to work on
+
+Check [open issues](https://github.com/bfoley12/timingtower/issues) for anything tagged `good first issue` or `help wanted`. Some areas where contributions are especially useful:
+
+- **Test coverage** for existing feeds
+- **Documentation** of existing classes and functions
+- **Examples** of loading and basic transformations/uses
+
+If you want to tackle something not listed, open an issue first so we can discuss the approach.
+
+## Pull requests
+
+- Keep PRs focused - one feed, one fix, one feature.
+- Include tests for new feeds or changed behavior.
+- All tests and basedpyright must pass.
+- Use clear commit messages. No strict format required, just be descriptive.
+
+## Code conventions
+
+- **Pydantic v2** models for all feed .json.
+- **Polars** for all DataFrames - no Pandas - especially in feed .jsonStream.
+- **httpx** for HTTP.
+  - This will change to niquest when I have time to read up on it. Stay with httpx for now.
+- Store raw strings at ingest (e.g., timestamps as `pl.String`). Parsing and casting belong in the transformation layer.
+- Fail loudly on malformed data rather than silently skipping.
+
+## Architecture quick reference
+
+- `fetch()` is a thin HTTP/URL-builder layer. It does not resolve sessions or meetings.
+- `get()` handles all domain resolution (meeting, session, folder lookup) and calls `fetch()` with fully resolved paths.
+- Feed models live in their own modules and are registered for class-based `client.get(F1DataContainer)` calls.
+
+## Questions?
+
+Open a GitHub issue or discussion. There's no Discord/Slack yet.

timingtower-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: timingtower
+Version: 0.1.0
+Summary: A thin, unopinionated wrapper of the F1 livetiming API. Provides typed values on a modern data stack.
+Project-URL: Homepage, https://github.com/bfoley12/timingtower
+Project-URL: Repository, https://github.com/bfoley12/timingtower
+Author-email: Brendan Foley <brendanfoley1214@proton.me>
+License: MIT
+Requires-Python: >=3.14
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: polars>=1.39.0
+Requires-Dist: pydantic-settings>=2.13.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: tenacity>=9.1.4
+Description-Content-Type: text/markdown
+
+# timingtower
+## Motivation
+The F1 livetiming API at https://livetiming.formula1.com exposes a rich set of data feeds - car telemetry, position data, timing, tyre stints, race control messages, weather, pit lane times, and more - going back to 2018. Existing tools access parts of this API but make tradeoffs that aren't right for every use case.
+
+[FastF1](https://github.com/theOehrly/Fast-F1) is an excellent analysis-first library, but it consumes raw feeds internally and surfaces its own higher-level abstractions built on Pandas. While they deliver high quality, processed views of the data, some power-analysts may want to handle the raw data directly.
+
+[OpenF1](https://github.com/br-g/openf1) is a hosted REST API that proxies a subset of the feed data into simplified JSON endpoints. It's convenient for quick queries but only covers 2023 onward and restructures the data into its own schema.
+
+timingtower takes a different approach. It maps the livetiming feeds directly, preserving their original structure while wrapping them in Pydantic V2 models and Polars DataFrames. The raw data stays intact - timingtower doesn't decide what's relevant or how fields should be combined. It gives you typed, validated access to the feeds as they exist, on a modern stack that's faster and more ergonomic than Pandas.
+
+Like its namesake, timingtower sits close to the action - just one layer above the raw data.
+
+
+## Data Model
+The livetiming API is a hierarchical API that progressively provides more information. The base of the API is https://livetiming.formula1.com/static (from here on, we will refer to that as root - '/' and reference the API layers as starting from '/'). Most layers provide an Index.json that we can learn about the available endpoints to dive deeper into. For example, /Index.json shows the current year (why it doesn't show every available year is not known to me). /{year}/Index.json provides a list of meetings (race or testing weekends) with their relevant sessions (FP1, Qualifying, etc.). Oddly, /{year}/{meeting} does not provide an Index.json file. /{year}/{meeting}/{session}/Index.json displays all available 'feeds' for a session. A 'feed' refers to a single collection of data submitted either as a .json file (a 'keyframe') or a .jsonStream (aka .jsonl) file (a 'stream'). 
+
+A keyframe represents a static json, while streams are dynamic, partial updates throughout the course of a session. This makes Pydantic a natural package to model the keyframe. Streams are timestamped by the session time as a duration. Polars is used to represent the streamed data.
+
+Consistency is prioritized across returned models. Each model contains a 'keyframe' and 'stream' (with the exceptions of Season, Meeting, and Session, which offer only a keyframe since they only have an Index.json file). It is up to the user to determine whether they need the data from the stream or the keyframe, as some feeds are represented better in the stream (ie. CarData and Position keyframes are not useful for many applications). In anticipation of many use cases relying on the stream's dataframe, a property is provided directly on the F1DataContainer object: obj.df.
+
+## Getting Started
+
+### Install
+```bash
+# uv
+uv add timingtower
+
+# pip
+pip install timingtower
+```
+
+### Data Exploration
+```python
+from timingtower import DirectClient
+
+with DirectClient() as client:
+    # Available seasons
+    client.get_available_seasons()
+
+    # Get meetings from specific year
+    season = client.get_season(year=2026) # Using convenience method
+    season.meetings # Aliases season.keyframe.meetings for convenience
+
+    # Get sessions from specific meeting
+    meeting = season.get_meeting(meeting="Australia")
+    meeting.sessions
+
+    # Get a specific session
+    meeting.get_session(name="Qualifying")
+    # Using convenience properties
+    meeting.q # Qualifying
+
+    # Get session directly from client and look at available data
+    session_index = client.get(year=2026, meeting="Australia", session="Qualifying")
+    session_index.available_feeds
+```
+
+### Get data
+#### Synchronously
+```python
+from timingtower import DirectClient
+
+
+# Can also use DirectClient as a long-lived instance:
+# client = DirectClient()
+# val = client.get(...)
+
+with DirectClient() as client:
+    # Request CarData and Position from livetiming API
+    car_data = client.get(model="CarData", year=2026, meeting="Shanghai", session="Race") # Returns a Keyframe+Stream of CarData
+    position = client.get(model="Position", year=2026, meeting="Shanghai", session="Race") # Returns a Keyframe+Stream of Position
+
+car_df = car_data.df
+position_df = position.df
+
+joined_df = car_df.join_asof(
+    position_df, on="timestamp", by="racing_number", strategy="nearest"
+)
+```
+#### Asynchronously
+
+```python
+import asyncio
+from timingtower import AsyncDirectClient
+
+# Use the async client as a context manager
+async with AsyncDirectClient() as client:
+    # Launch multiple jobs at the same time (this sends 4 requests - 1 for keyframe and 1 for stream in each client.get)
+    car_data, position = await asyncio.gather(
+        client.get(model="CarData", year=2024, meeting="Monza", session="Race"),
+        client.get(model="Position", year=2024, meeting="Monza", session="Race"),
+    )
+car_df = car_data.df # Alias to car_data.stream.data
+position_df = position.df
+
+joined_df = car_df.join_asof(
+    position_df, on="timestamp", by="racing_number", strategy="nearest"
+)
+```
+
+### Modify (Async)DirectClient settings
+Since your connection to livetiming may be different from the testing environment, we allow for customization of ClientSettings. Check settings::ClientSettings for what can be changed.
+```python
+from timingtower import AsyncDirectClient, ClientSettings
+
+settings = ClientSettings(
+    total_timeout = 10, # Set max allowed time to wait for client to 10s
+    request_timeout = 2 # Set max allowed time to wait per request to 2s
+)
+
+async_client = AsyncDirectClient(settings=settings)
+# Note: For DirectClient, total_timeout does not have any effect at the moment.
+# Each request is still limited to request timeout, so the max waited for is 3x request_timeout
+sync_client = DirectClient(settings=settings)
+
+sync_client.get(year=2026)
+```
+
+## Supported Feeds
+<details>
+<summary>Supported Feeds (32/32)</summary>
+
+| Feed | Keyframe (`.json`) | Stream (`.jsonStream`) |
+|------|:-----:|:-----:|
+| [TimingDataF1](src/timingtower/api_handler/models/timing_data.py) | ✅ | ✅ |
+| [TimingStats](src/timingtower/api_handler/models/timing_stats.py) | ✅ | ✅ |
+| [TimingAppData](src/timingtower/api_handler/models/timing_app_data.py) | ✅ | ✅ |
+| [LapSeries](src/timingtower/api_handler/models/lap_series.py) | ✅ | ✅ |
+| [TyreStintSeries](src/timingtower/api_handler/models/tyre_stint_series.py) | ✅ | ✅ |
+| [DriverTracker](src/timingtower/api_handler/models/driver_tracker.py) | ✅ | ✅ |
+| [OvertakeSeries](src/timingtower/api_handler/models/overtake_series.py) | ✅ | ✅ |
+| [PitStop](src/timingtower/api_handler/models/pit_stop.py) | ✅ | ✅ |
+| [PitStopSeries](src/timingtower/api_handler/models/pit_stop_series.py) | ✅ | ✅ |
+| [CurrentTyres](src/timingtower/api_handler/models/current_tyres.py) | ✅ | ✅ |
+| [TimingData](src/timingtower/api_handler/models/timing_data.py) | ✅ | ✅ |
+| [LapCount](src/timingtower/api_handler/models/lap_count.py) | ✅ | ✅ |
+| [TopThree](src/timingtower/api_handler/models/top_three.py) | ✅ | ✅ |
+| [CarData.z](src/timingtower/api_handler/models/car_data.py) | ✅ | ✅ |
+| [Position.z](src/timingtower/api_handler/models/position.py) | ✅ | ✅ |
+| [RaceControlMessages](src/timingtower/api_handler/models/race_control_messages.py) | ✅ | ✅ |
+| [TrackStatus](src/timingtower/api_handler/models/track_status.py) | ✅ | ✅ |
+| [TlaRcm](src/timingtower/api_handler/models/tla_rcm.py) | ✅ | ✅ |
+| [TeamRadio](src/timingtower/api_handler/models/team_radio.py) | ✅ | ✅ |
+| [WeatherData](src/timingtower/api_handler/models/weather_data.py) | ✅ | ✅ |
+| [WeatherDataSeries](src/timingtower/api_handler/models/weather_data_series.py) | ✅ | ✅ |
+| [DriverList](src/timingtower/api_handler/models/driver_list.py) | ✅ | ✅ |
+| [PitLaneTimeCollection](src/timingtower/api_handler/models/pit_lane_time_collection.py) | ✅ | ✅ |
+| [ChampionshipPrediction](src/timingtower/api_handler/models/championship_prediction.py) | ✅ | ✅ |
+| [DriverRaceInfo](src/timingtower/api_handler/models/driver_race_info.py) | ✅ | ✅ |
+| [SessionInfo](src/timingtower/api_handler/models/session_info.py) | ✅ | ✅ |
+| [SessionData](src/timingtower/api_handler/models/session_data.py) | ✅ | ✅ |
+| [SessionStatus](src/timingtower/api_handler/models/session_status.py) | ✅ | ✅ |
+| [ArchiveStatus](src/timingtower/api_handler/models/archive_status.py) | ✅ | ✅ |
+| [Heartbeat](src/timingtower/api_handler/models/heartbeat.py) | ✅ | ✅ |
+| [ExtrapolatedClock](src/timingtower/api_handler/models/extrapolated_clock.py) | ✅ | ✅ |
+| [ContentStreams](src/timingtower/api_handler/models/content_streams.py) | ✅ | ✅ |
+| [AudioStreams](src/timingtower/api_handler/models/audio_streams.py) | ✅ | ✅ |
+
+</details>
+
+## Contributing
+timingtower is in early development and contributions are welcome - whether that's new feed implementations, tests, docs, or bug reports. See [CONTRIBUTING.md] for setup instructions and guidelines.
+
+## Disclaimer
+timingtower is an unofficial project and is not affiliated with Formula 1 companies. All F1-related trademarks are owned by Formula One Licensing B.V.

timingtower-0.1.0/README.md

@@ -0,0 +1,165 @@
+# timingtower
+## Motivation
+The F1 livetiming API at https://livetiming.formula1.com exposes a rich set of data feeds - car telemetry, position data, timing, tyre stints, race control messages, weather, pit lane times, and more - going back to 2018. Existing tools access parts of this API but make tradeoffs that aren't right for every use case.
+
+[FastF1](https://github.com/theOehrly/Fast-F1) is an excellent analysis-first library, but it consumes raw feeds internally and surfaces its own higher-level abstractions built on Pandas. While they deliver high quality, processed views of the data, some power-analysts may want to handle the raw data directly.
+
+[OpenF1](https://github.com/br-g/openf1) is a hosted REST API that proxies a subset of the feed data into simplified JSON endpoints. It's convenient for quick queries but only covers 2023 onward and restructures the data into its own schema.
+
+timingtower takes a different approach. It maps the livetiming feeds directly, preserving their original structure while wrapping them in Pydantic V2 models and Polars DataFrames. The raw data stays intact - timingtower doesn't decide what's relevant or how fields should be combined. It gives you typed, validated access to the feeds as they exist, on a modern stack that's faster and more ergonomic than Pandas.
+
+Like its namesake, timingtower sits close to the action - just one layer above the raw data.
+
+
+## Data Model
+The livetiming API is a hierarchical API that progressively provides more information. The base of the API is https://livetiming.formula1.com/static (from here on, we will refer to that as root - '/' and reference the API layers as starting from '/'). Most layers provide an Index.json that we can learn about the available endpoints to dive deeper into. For example, /Index.json shows the current year (why it doesn't show every available year is not known to me). /{year}/Index.json provides a list of meetings (race or testing weekends) with their relevant sessions (FP1, Qualifying, etc.). Oddly, /{year}/{meeting} does not provide an Index.json file. /{year}/{meeting}/{session}/Index.json displays all available 'feeds' for a session. A 'feed' refers to a single collection of data submitted either as a .json file (a 'keyframe') or a .jsonStream (aka .jsonl) file (a 'stream'). 
+
+A keyframe represents a static json, while streams are dynamic, partial updates throughout the course of a session. This makes Pydantic a natural package to model the keyframe. Streams are timestamped by the session time as a duration. Polars is used to represent the streamed data.
+
+Consistency is prioritized across returned models. Each model contains a 'keyframe' and 'stream' (with the exceptions of Season, Meeting, and Session, which offer only a keyframe since they only have an Index.json file). It is up to the user to determine whether they need the data from the stream or the keyframe, as some feeds are represented better in the stream (ie. CarData and Position keyframes are not useful for many applications). In anticipation of many use cases relying on the stream's dataframe, a property is provided directly on the F1DataContainer object: obj.df.
+
+## Getting Started
+
+### Install
+```bash
+# uv
+uv add timingtower
+
+# pip
+pip install timingtower
+```
+
+### Data Exploration
+```python
+from timingtower import DirectClient
+
+with DirectClient() as client:
+    # Available seasons
+    client.get_available_seasons()
+
+    # Get meetings from specific year
+    season = client.get_season(year=2026) # Using convenience method
+    season.meetings # Aliases season.keyframe.meetings for convenience
+
+    # Get sessions from specific meeting
+    meeting = season.get_meeting(meeting="Australia")
+    meeting.sessions
+
+    # Get a specific session
+    meeting.get_session(name="Qualifying")
+    # Using convenience properties
+    meeting.q # Qualifying
+
+    # Get session directly from client and look at available data
+    session_index = client.get(year=2026, meeting="Australia", session="Qualifying")
+    session_index.available_feeds
+```
+
+### Get data
+#### Synchronously
+```python
+from timingtower import DirectClient
+
+
+# Can also use DirectClient as a long-lived instance:
+# client = DirectClient()
+# val = client.get(...)
+
+with DirectClient() as client:
+    # Request CarData and Position from livetiming API
+    car_data = client.get(model="CarData", year=2026, meeting="Shanghai", session="Race") # Returns a Keyframe+Stream of CarData
+    position = client.get(model="Position", year=2026, meeting="Shanghai", session="Race") # Returns a Keyframe+Stream of Position
+
+car_df = car_data.df
+position_df = position.df
+
+joined_df = car_df.join_asof(
+    position_df, on="timestamp", by="racing_number", strategy="nearest"
+)
+```
+#### Asynchronously
+
+```python
+import asyncio
+from timingtower import AsyncDirectClient
+
+# Use the async client as a context manager
+async with AsyncDirectClient() as client:
+    # Launch multiple jobs at the same time (this sends 4 requests - 1 for keyframe and 1 for stream in each client.get)
+    car_data, position = await asyncio.gather(
+        client.get(model="CarData", year=2024, meeting="Monza", session="Race"),
+        client.get(model="Position", year=2024, meeting="Monza", session="Race"),
+    )
+car_df = car_data.df # Alias to car_data.stream.data
+position_df = position.df
+
+joined_df = car_df.join_asof(
+    position_df, on="timestamp", by="racing_number", strategy="nearest"
+)
+```
+
+### Modify (Async)DirectClient settings
+Since your connection to livetiming may be different from the testing environment, we allow for customization of ClientSettings. Check settings::ClientSettings for what can be changed.
+```python
+from timingtower import AsyncDirectClient, ClientSettings
+
+settings = ClientSettings(
+    total_timeout = 10, # Set max allowed time to wait for client to 10s
+    request_timeout = 2 # Set max allowed time to wait per request to 2s
+)
+
+async_client = AsyncDirectClient(settings=settings)
+# Note: For DirectClient, total_timeout does not have any effect at the moment.
+# Each request is still limited to request timeout, so the max waited for is 3x request_timeout
+sync_client = DirectClient(settings=settings)
+
+sync_client.get(year=2026)
+```
+
+## Supported Feeds
+<details>
+<summary>Supported Feeds (32/32)</summary>
+
+| Feed | Keyframe (`.json`) | Stream (`.jsonStream`) |
+|------|:-----:|:-----:|
+| [TimingDataF1](src/timingtower/api_handler/models/timing_data.py) | ✅ | ✅ |
+| [TimingStats](src/timingtower/api_handler/models/timing_stats.py) | ✅ | ✅ |
+| [TimingAppData](src/timingtower/api_handler/models/timing_app_data.py) | ✅ | ✅ |
+| [LapSeries](src/timingtower/api_handler/models/lap_series.py) | ✅ | ✅ |
+| [TyreStintSeries](src/timingtower/api_handler/models/tyre_stint_series.py) | ✅ | ✅ |
+| [DriverTracker](src/timingtower/api_handler/models/driver_tracker.py) | ✅ | ✅ |
+| [OvertakeSeries](src/timingtower/api_handler/models/overtake_series.py) | ✅ | ✅ |
+| [PitStop](src/timingtower/api_handler/models/pit_stop.py) | ✅ | ✅ |
+| [PitStopSeries](src/timingtower/api_handler/models/pit_stop_series.py) | ✅ | ✅ |
+| [CurrentTyres](src/timingtower/api_handler/models/current_tyres.py) | ✅ | ✅ |
+| [TimingData](src/timingtower/api_handler/models/timing_data.py) | ✅ | ✅ |
+| [LapCount](src/timingtower/api_handler/models/lap_count.py) | ✅ | ✅ |
+| [TopThree](src/timingtower/api_handler/models/top_three.py) | ✅ | ✅ |
+| [CarData.z](src/timingtower/api_handler/models/car_data.py) | ✅ | ✅ |
+| [Position.z](src/timingtower/api_handler/models/position.py) | ✅ | ✅ |
+| [RaceControlMessages](src/timingtower/api_handler/models/race_control_messages.py) | ✅ | ✅ |
+| [TrackStatus](src/timingtower/api_handler/models/track_status.py) | ✅ | ✅ |
+| [TlaRcm](src/timingtower/api_handler/models/tla_rcm.py) | ✅ | ✅ |
+| [TeamRadio](src/timingtower/api_handler/models/team_radio.py) | ✅ | ✅ |
+| [WeatherData](src/timingtower/api_handler/models/weather_data.py) | ✅ | ✅ |
+| [WeatherDataSeries](src/timingtower/api_handler/models/weather_data_series.py) | ✅ | ✅ |
+| [DriverList](src/timingtower/api_handler/models/driver_list.py) | ✅ | ✅ |
+| [PitLaneTimeCollection](src/timingtower/api_handler/models/pit_lane_time_collection.py) | ✅ | ✅ |
+| [ChampionshipPrediction](src/timingtower/api_handler/models/championship_prediction.py) | ✅ | ✅ |
+| [DriverRaceInfo](src/timingtower/api_handler/models/driver_race_info.py) | ✅ | ✅ |
+| [SessionInfo](src/timingtower/api_handler/models/session_info.py) | ✅ | ✅ |
+| [SessionData](src/timingtower/api_handler/models/session_data.py) | ✅ | ✅ |
+| [SessionStatus](src/timingtower/api_handler/models/session_status.py) | ✅ | ✅ |
+| [ArchiveStatus](src/timingtower/api_handler/models/archive_status.py) | ✅ | ✅ |
+| [Heartbeat](src/timingtower/api_handler/models/heartbeat.py) | ✅ | ✅ |
+| [ExtrapolatedClock](src/timingtower/api_handler/models/extrapolated_clock.py) | ✅ | ✅ |
+| [ContentStreams](src/timingtower/api_handler/models/content_streams.py) | ✅ | ✅ |
+| [AudioStreams](src/timingtower/api_handler/models/audio_streams.py) | ✅ | ✅ |
+
+</details>
+
+## Contributing
+timingtower is in early development and contributions are welcome - whether that's new feed implementations, tests, docs, or bug reports. See [CONTRIBUTING.md] for setup instructions and guidelines.
+
+## Disclaimer
+timingtower is an unofficial project and is not affiliated with Formula 1 companies. All F1-related trademarks are owned by Formula One Licensing B.V.

timingtower-0.1.0/examples/average_rcm.py

@@ -0,0 +1,112 @@
+import marimo
+
+__generated_with = "0.22.0"
+app = marimo.App(width="full")
+
+
+@app.cell
+def _():
+    import plotly.express as px
+    import polars as pl
+
+    from timingtower import DirectClient
+
+    return (DirectClient,)
+
+
+@app.cell
+def _(DirectClient):
+    client = DirectClient()
+    return (client,)
+
+
+@app.cell
+def _(client):
+    season = client.get_season(year=2026)
+    return (season,)
+
+
+@app.cell
+def _(season) -> None:
+    season.keyframe.meetings[0].sessions[0]
+    return
+
+
+@app.cell
+def _(client) -> None:
+    client.get(year=2026, model="Season").keyframe.meetings
+    return
+
+
+@app.cell
+def _(client, season) -> None:
+    data_list = []
+    for meeting in season.keyframe.meetings:
+        for session in meeting.sessions:
+            print(session)
+            data_list.append(client.get(session=session, model="RaceControlMessages"))
+    return
+
+
+@app.cell
+def _(client) -> None:
+    client.get(year=2026, meeting="Shanghai", session="Race", model="TlaRcm")
+    return
+
+
+@app.cell
+async def _():
+    import asyncio
+
+    from timingtower import AsyncDirectClient
+
+    # Use the async client as a context manager
+    async with AsyncDirectClient() as async_client:
+        # Launch multiple jobs at the same time (this sends 4 requests - 1 for keyframe and 1 for stream in each client.get)
+        car_data, _position = await asyncio.gather(
+            async_client.get("CarData", year=2024, meeting="Monza", session="Race"),
+            async_client.get("Position", year=2024, meeting="Monza", session="Race"),
+        )
+    car_df = car_data.df
+    position_df = car_data.df
+
+    car_df.join_asof(
+        position_df, on="timestamp", by="racing_number", strategy="nearest"
+    )
+    return (AsyncDirectClient,)
+
+
+@app.cell
+async def _(AsyncDirectClient) -> None:
+    from pprint import pprint
+
+    async with AsyncDirectClient() as _client:
+        pprint(await _client.get_available_seasons())
+    return
+
+
+@app.cell
+def _(DirectClient) -> None:
+    with DirectClient() as _client:
+        # Available years
+        _client.get_available_seasons()
+
+        # Get meetings from specific year
+        _season = _client.get_season(year=2026)  # Using convenience method
+        _season.keyframe.meetings
+        _season.meetings  # Aliases season.keyframe.meetings for convenience
+
+        # Get sessions from specific meeting
+        _meeting = _season.get_meeting(name="Australia")
+        _meeting.sessions
+
+        # Get a specific session
+        _meeting.get_session(name="Qualifying")
+        # Using convenience properties
+        _meeting.fp1  # Free Practice 1
+        _meeting.q  # Qualifying
+    return
+
+
+if __name__ == "__main__":
+    app.run()