aionlslivetiming 0.1.0

Async-first Python client for the Nürburgring Langstrecken-Serie livetiming service

aionlslivetiming

Async-first Python client for the Nürburgring Langstrecken-Serie livetiming service.

aionlslivetiming wraps the official NLS livetiming WebSocket feed at livetiming.azurewebsites.net and exposes a clean async Python API. It works equally well in two modes: live (connected to a running race) and replay (driven from a recorded JSONL log). Downstream projects (Discord bots, dashboards, Home Assistant integrations, analytics tools) consume NLS race data without reverse-engineering the Azure WebSocket or the cryptic short-code JSON the server actually emits.

Installation

uv add aionlslivetiming
# or:
pip install aionlslivetiming

Requires Python 3.12+. No Home Assistant-specific dependencies; safe to install anywhere.

60-Second Quickstart

Live (5 lines)

import asyncio
from aionlslivetiming import NLSClient

async def main():
    async with NLSClient(event_id="20") as client:
        async for msg in client.messages():
            print(msg)

asyncio.run(main())

Replay (3 lines)

from aionlslivetiming import NLSClient

async with NLSClient.from_replay("recording.jsonl") as client:
    async for msg in client.messages():
        print(msg)

Filter (5 lines)

async with NLSClient.from_replay("recording.jsonl") as client:
    async for _ in client.messages():
        pass  # populate state
    top3 = client.state.filter().by_position(lo=1, hi=3).cars()
    for car in top3:
        print(car.starting_no, car.driver)

Recording

uv run nls-record 20 /tmp/event.jsonl

Captures a live race to JSONL for offline replay.

Documentation

Full documentation: docs/quickstart.md

• Quickstart — full walkthrough (live + replay + record + filter)
• Examples — three worked examples
• API Reference — auto-generated from docstrings
• Changelog
• Contributing
• License — MIT

License

MIT — see LICENSE.

Acknowledgements

Race data is published by the Nürburgring Langstrecken-Serie. This library is a community wrapper; it is not affiliated with or endorsed by the NLS organization.