Metadata-Version: 2.4
Name: aionlslivetiming
Version: 0.1.0
Summary: Async-first Python client for the Nürburgring Langstrecken-Serie livetiming service
Project-URL: Repository, https://github.com/akentner/aionlslivetiming
Project-URL: Issues, https://github.com/akentner/aionlslivetiming/issues
Author: akentner
License: MIT
License-File: LICENSE
Keywords: async,livetiming,nls,nuerburgring,websocket
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: httpx<0.29,>=0.28
Requires-Dist: pydantic==2.13.4
Requires-Dist: websockets<17,>=15.0.1
Provides-Extra: dev
Requires-Dist: freezegun>=1.5; extra == 'dev'
Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
Requires-Dist: mkdocs>=1.6; extra == 'dev'
Requires-Dist: mkdocstrings[python]>=0.27; extra == 'dev'
Requires-Dist: mypy<2.2,>=1.1; extra == 'dev'
Requires-Dist: pytest-asyncio<2,>=1.4; extra == 'dev'
Requires-Dist: pytest-cov<8,>=7; extra == 'dev'
Requires-Dist: pytest>=9.0; extra == 'dev'
Requires-Dist: respx>=0.23; extra == 'dev'
Requires-Dist: ruff>=0.15; extra == 'dev'
Requires-Dist: twine>=6.0; extra == 'dev'
Provides-Extra: orjson
Requires-Dist: orjson<4,>=3.11; extra == 'orjson'
Description-Content-Type: text/markdown

# aionlslivetiming

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

[![PyPI](https://img.shields.io/pypi/v/aionlslivetiming.svg)](https://pypi.org/project/aionlslivetiming/)
[![Python](https://img.shields.io/pypi/pyversions/aionlslivetiming.svg)](https://pypi.org/project/aionlslivetiming/)
[![License](https://img.shields.io/pypi/l/aionlslivetiming.svg)](LICENSE)
[![Status](https://img.shields.io/badge/status-alpha-yellow.svg)](.planning/ROADMAP.md)

`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

```bash
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)

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

```python
from aionlslivetiming import NLSClient

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

### Filter (5 lines)

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

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

Captures a live race to JSONL for offline replay.

## Documentation

Full documentation: [docs/quickstart.md](docs/quickstart.md)

- [Quickstart](docs/quickstart.md) — full walkthrough (live + replay + record + filter)
- [Examples](examples/) — three worked examples
- [API Reference](docs/api/) — auto-generated from docstrings
- [Changelog](CHANGELOG.md)
- [Contributing](CONTRIBUTING.md)
- [License](LICENSE) — MIT

## License

MIT — see [LICENSE](LICENSE).

## Acknowledgements

Race data is published by the
[Nürburgring Langstrecken-Serie](https://www.nuerburgring-langstrecken-serie.de/).
This library is a community wrapper; it is not affiliated with or endorsed
by the NLS organization.
