aioabrp 0.1.0__tar.gz

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

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.14"
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Type check
+        run: uv run mypy
+
+      - name: Test
+        run: uv run pytest

aioabrp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,63 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      # Required for PyPI Trusted Publishing (OIDC).
+      id-token: write
+      # Required to create the GitHub release.
+      contents: write
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+          # Full history + tags so git-cliff can compute release notes.
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.14"
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Type check
+        run: uv run mypy
+
+      - name: Test
+        run: uv run pytest
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      # `uv version --short` cannot read hatchling dynamic versions, so ask
+      # the package itself (src/aioabrp/__init__.py is the single source).
+      - name: Check tag matches project version
+        run: test "v$(uv run python -c 'import aioabrp; print(aioabrp.__version__)')" = "${GITHUB_REF_NAME}"
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Generate release notes from conventional commits
+        run: uv tool run git-cliff --latest --strip all -o "${RUNNER_TEMP}/RELEASE_NOTES.md"
+
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: >-
+          gh release create "${GITHUB_REF_NAME}" dist/*
+          --title "${GITHUB_REF_NAME}"
+          --notes-file "${RUNNER_TEMP}/RELEASE_NOTES.md"

aioabrp-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Byte-compiled / caches
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Virtual environments
+.venv/
+venv/
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+
+# Coverage
+.coverage
+.coverage.*
+htmlcov/
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/

aioabrp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martin Andersson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aioabrp-0.1.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: aioabrp
+Version: 0.1.0
+Summary: Async Python client for the A Better Routeplanner (ABRP) / Iternio telemetry API
+Project-URL: Homepage, https://github.com/mtandersson/aioabrp
+Project-URL: Repository, https://github.com/mtandersson/aioabrp
+Project-URL: Changelog, https://github.com/mtandersson/aioabrp/releases
+Project-URL: Issues, https://github.com/mtandersson/aioabrp/issues
+Author: Martin Andersson
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: aiohttp
+Description-Content-Type: text/markdown
+
+# aioabrp
+
+Async Python client for the [A Better Routeplanner](https://abetterrouteplanner.com)
+(ABRP) / Iternio telemetry API. The library mirrors ABRP's API points 1:1 and
+has no Home Assistant dependency: a stateless request/response `AbrpClient`
+(garage, vehicle catalog, one-shot telemetry snapshot) and a resilient
+`TelemetryStream` (server-sent events with reconnect/backoff/watchdog) that
+delivers extracted, typed metric values — never raw wire dicts — to consumer
+callbacks. Authentication is injected: the consumer owns the token lifecycle
+and hands the library a fresh access token via `AbstractAuth` (or the
+fixed-token `StaticAuth` convenience).
+
+## Installation
+
+```sh
+pip install aioabrp
+```
+
+Requires Python ≥ 3.14. The only runtime dependency is `aiohttp`.
+
+## Usage
+
+A runnable standalone example (fill in a real partner API key and access
+token before running — the calls below hit the live API):
+
+```python
+import asyncio
+
+import aiohttp
+
+from aioabrp import (
+    AbrpClient,
+    ConnectionEvent,
+    StaticAuth,
+    Telemetry,
+    TelemetryStream,
+)
+
+API_KEY = "your-iternio-partner-api-key"
+ACCESS_TOKEN = "your-abrp-access-token"
+
+
+def on_update(vehicle_id: int, telemetry: Telemetry) -> None:
+    for metric, mv in telemetry.items():
+        print(f"vehicle {vehicle_id}: {metric} = {mv.value!r} (time={mv.time})")
+
+
+def on_connection_change(event: ConnectionEvent) -> None:
+    print(f"connection: {event.state.name} (reason={event.reason})")
+
+
+async def main() -> None:
+    async with aiohttp.ClientSession() as session:
+        auth = StaticAuth(ACCESS_TOKEN)
+        client = AbrpClient(session, API_KEY, auth)
+
+        vehicles = await client.async_get_vehicles()
+        for vehicle in vehicles:
+            print(f"{vehicle.vehicle_id}: {vehicle.name or vehicle.vehicle_model}")
+
+        stream = TelemetryStream(
+            session,
+            API_KEY,
+            auth,
+            vehicle_ids=[v.vehicle_id for v in vehicles],
+            on_update=on_update,
+            on_connection_change=on_connection_change,
+        )
+        await stream.start()
+        try:
+            await asyncio.sleep(600)  # stream telemetry for ten minutes
+        finally:
+            await stream.stop()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Get your own API key
+
+The `api_key` constructor argument is an Iternio **partner API key**, not a
+per-user credential. If you are building your own consumer, obtain your own
+key from Iternio — see the
+[Iternio Telemetry API documentation](https://documenter.getpostman.com/view/7396339/SWTK5a8w)
+or contact Iternio for a partner API key. The per-user access token comes
+from your own auth flow and is handed to the library through `AbstractAuth`.
+
+## Consumer contracts
+
+These behaviors are pinned by the test suite; consumers may rely on them.
+
+### Callbacks
+
+- `on_update` and `on_connection_change` are **synchronous** callbacks,
+  delivered on the event loop that ran `start()`. They must be
+  non-blocking — a slow callback stalls the stream (and every other stream
+  on the same loop).
+- A raising callback is logged with its traceback and swallowed; the stream
+  continues (frame loss beats stream death).
+
+### Connection events
+
+- `CONNECTED` fires on the **first frame** of a connection, not on the HTTP
+  connect — a connection that opens but never produces a frame keeps
+  reading as down until proven healthy.
+- `DISCONNECTED` is **steady-state, not exceptional**: the ABRP server
+  unilaterally closes idle streams at roughly 200 s and the stream
+  reconnects with backoff. Do not treat a `DISCONNECTED` event as an
+  outage. Events are status reports, not strict state transitions — a
+  `DISCONNECTED` MAY arrive before the first `CONNECTED` (for example when
+  the very first connection attempt fails).
+- `AUTH_FAILED` is **terminal**: the stream stops itself and will not
+  retry. The consumer decides whether/when to restart with fresh
+  credentials.
+- A transient (non-`AbrpAuthError`) failure from the token getter emits
+  **no** `ConnectionEvent` at all (debug log only) — no connection attempt
+  was made, so consumers keep seeing the last known state during a
+  token-endpoint outage.
+
+### Lifecycle
+
+- `stop()` is idempotent and cancel-based (never a graceful join). No
+  callbacks fire after `stop()` returns.
+- `stop()` propagates the **caller's own** cancellation: if you wrap it in
+  `asyncio.wait_for(stream.stop(), timeout)` and that times out, the
+  resulting `TimeoutError` means the stream **may still be running** — the
+  stop was interrupted, not completed.
+- `start()` after `stop()` restarts the stream.
+
+### Monotonicity gate
+
+Each stream keeps one piece of state: a per-`(vehicle_id, Metric)` map of
+the last adopted block timestamp.
+
+- A block whose `time` is **strictly older** than the last adopted time for
+  that `(vehicle, metric)` is dropped.
+- An **equal-time** block re-emits **by design**: every reconnect
+  re-delivers a full-state snapshot with unchanged block times, and
+  consumers rely on that backfill.
+- A **time-less** block (missing/malformed/naive `time`) is adopted and
+  **clears** the gate for that metric — it carries no ordering claim, so it
+  also stops gating subsequent values.
+- A block whose `time` is in the **future** is rewritten to "now" before
+  delivery (and before gating), so a clock-skewed upstream stamp can neither
+  be delivered to the consumer nor become an unreachable high-water mark that
+  silently stalls the metric. `AbrpClient.async_get_current_telemetry` applies
+  the same clamp (it does not gate).
+- **Known limitation:** a legitimately backdated server correction (an
+  older timestamp that really is a newer truth) is suppressed for the
+  stream's lifetime.
+
+The gate can be **pre-warmed** across process restarts: pass
+`TelemetryStream(..., seed=Mapping[int, Mapping[Metric, datetime]])` — a
+per-vehicle map of metric to its last wire-block time (e.g. derived from the
+consumer's last persisted snapshot) — and the stream seeds its high-water marks
+from those times, each clamped not-future. Only times are needed; no typed
+values. The clock is the `aioabrp._clock._now` seam (the monkeypatch target in
+tests).
+
+### Logging
+
+Enable the `aioabrp` logger at `DEBUG` for triage. Connect/disconnect and
+reasons log at `INFO`, watchdog stalls at `WARNING`, per-frame activity at
+`DEBUG`. Frames are logged as keys and sizes only — frame bodies, header
+values, and tokens (including GPS coordinates and other PII) are never
+logged. Pass `name=` to `TelemetryStream` to prefix its log lines when
+running multiple streams.
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv sync
+uv run ruff format . && uv run ruff check . && uv run mypy && uv run pytest
+```
+
+Note: the locked dev environment constrains `aiohttp<3.14` because the
+latest `aioresponses` release is incompatible with aiohttp ≥ 3.14
+([aioresponses#289](https://github.com/pnuckowski/aioresponses/issues/289));
+the published runtime dependency stays unpinned.
+
+### Releases
+
+Commits follow [Conventional Commits](https://www.conventionalcommits.org/);
+there is no CHANGELOG file — release notes are generated from the commit
+history by [git-cliff](https://git-cliff.org/) (`cliff.toml`) and published
+as GitHub Releases. Pushing a `v*` tag runs the quality gate, builds the
+sdist + wheel, verifies the tag matches `aioabrp.__version__`, publishes to
+PyPI via [Trusted Publishing](https://docs.pypi.org/trusted-publishers/)
+(OIDC), and creates the GitHub Release.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

aioabrp-0.1.0/README.md

@@ -0,0 +1,196 @@
+# aioabrp
+
+Async Python client for the [A Better Routeplanner](https://abetterrouteplanner.com)
+(ABRP) / Iternio telemetry API. The library mirrors ABRP's API points 1:1 and
+has no Home Assistant dependency: a stateless request/response `AbrpClient`
+(garage, vehicle catalog, one-shot telemetry snapshot) and a resilient
+`TelemetryStream` (server-sent events with reconnect/backoff/watchdog) that
+delivers extracted, typed metric values — never raw wire dicts — to consumer
+callbacks. Authentication is injected: the consumer owns the token lifecycle
+and hands the library a fresh access token via `AbstractAuth` (or the
+fixed-token `StaticAuth` convenience).
+
+## Installation
+
+```sh
+pip install aioabrp
+```
+
+Requires Python ≥ 3.14. The only runtime dependency is `aiohttp`.
+
+## Usage
+
+A runnable standalone example (fill in a real partner API key and access
+token before running — the calls below hit the live API):
+
+```python
+import asyncio
+
+import aiohttp
+
+from aioabrp import (
+    AbrpClient,
+    ConnectionEvent,
+    StaticAuth,
+    Telemetry,
+    TelemetryStream,
+)
+
+API_KEY = "your-iternio-partner-api-key"
+ACCESS_TOKEN = "your-abrp-access-token"
+
+
+def on_update(vehicle_id: int, telemetry: Telemetry) -> None:
+    for metric, mv in telemetry.items():
+        print(f"vehicle {vehicle_id}: {metric} = {mv.value!r} (time={mv.time})")
+
+
+def on_connection_change(event: ConnectionEvent) -> None:
+    print(f"connection: {event.state.name} (reason={event.reason})")
+
+
+async def main() -> None:
+    async with aiohttp.ClientSession() as session:
+        auth = StaticAuth(ACCESS_TOKEN)
+        client = AbrpClient(session, API_KEY, auth)
+
+        vehicles = await client.async_get_vehicles()
+        for vehicle in vehicles:
+            print(f"{vehicle.vehicle_id}: {vehicle.name or vehicle.vehicle_model}")
+
+        stream = TelemetryStream(
+            session,
+            API_KEY,
+            auth,
+            vehicle_ids=[v.vehicle_id for v in vehicles],
+            on_update=on_update,
+            on_connection_change=on_connection_change,
+        )
+        await stream.start()
+        try:
+            await asyncio.sleep(600)  # stream telemetry for ten minutes
+        finally:
+            await stream.stop()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Get your own API key
+
+The `api_key` constructor argument is an Iternio **partner API key**, not a
+per-user credential. If you are building your own consumer, obtain your own
+key from Iternio — see the
+[Iternio Telemetry API documentation](https://documenter.getpostman.com/view/7396339/SWTK5a8w)
+or contact Iternio for a partner API key. The per-user access token comes
+from your own auth flow and is handed to the library through `AbstractAuth`.
+
+## Consumer contracts
+
+These behaviors are pinned by the test suite; consumers may rely on them.
+
+### Callbacks
+
+- `on_update` and `on_connection_change` are **synchronous** callbacks,
+  delivered on the event loop that ran `start()`. They must be
+  non-blocking — a slow callback stalls the stream (and every other stream
+  on the same loop).
+- A raising callback is logged with its traceback and swallowed; the stream
+  continues (frame loss beats stream death).
+
+### Connection events
+
+- `CONNECTED` fires on the **first frame** of a connection, not on the HTTP
+  connect — a connection that opens but never produces a frame keeps
+  reading as down until proven healthy.
+- `DISCONNECTED` is **steady-state, not exceptional**: the ABRP server
+  unilaterally closes idle streams at roughly 200 s and the stream
+  reconnects with backoff. Do not treat a `DISCONNECTED` event as an
+  outage. Events are status reports, not strict state transitions — a
+  `DISCONNECTED` MAY arrive before the first `CONNECTED` (for example when
+  the very first connection attempt fails).
+- `AUTH_FAILED` is **terminal**: the stream stops itself and will not
+  retry. The consumer decides whether/when to restart with fresh
+  credentials.
+- A transient (non-`AbrpAuthError`) failure from the token getter emits
+  **no** `ConnectionEvent` at all (debug log only) — no connection attempt
+  was made, so consumers keep seeing the last known state during a
+  token-endpoint outage.
+
+### Lifecycle
+
+- `stop()` is idempotent and cancel-based (never a graceful join). No
+  callbacks fire after `stop()` returns.
+- `stop()` propagates the **caller's own** cancellation: if you wrap it in
+  `asyncio.wait_for(stream.stop(), timeout)` and that times out, the
+  resulting `TimeoutError` means the stream **may still be running** — the
+  stop was interrupted, not completed.
+- `start()` after `stop()` restarts the stream.
+
+### Monotonicity gate
+
+Each stream keeps one piece of state: a per-`(vehicle_id, Metric)` map of
+the last adopted block timestamp.
+
+- A block whose `time` is **strictly older** than the last adopted time for
+  that `(vehicle, metric)` is dropped.
+- An **equal-time** block re-emits **by design**: every reconnect
+  re-delivers a full-state snapshot with unchanged block times, and
+  consumers rely on that backfill.
+- A **time-less** block (missing/malformed/naive `time`) is adopted and
+  **clears** the gate for that metric — it carries no ordering claim, so it
+  also stops gating subsequent values.
+- A block whose `time` is in the **future** is rewritten to "now" before
+  delivery (and before gating), so a clock-skewed upstream stamp can neither
+  be delivered to the consumer nor become an unreachable high-water mark that
+  silently stalls the metric. `AbrpClient.async_get_current_telemetry` applies
+  the same clamp (it does not gate).
+- **Known limitation:** a legitimately backdated server correction (an
+  older timestamp that really is a newer truth) is suppressed for the
+  stream's lifetime.
+
+The gate can be **pre-warmed** across process restarts: pass
+`TelemetryStream(..., seed=Mapping[int, Mapping[Metric, datetime]])` — a
+per-vehicle map of metric to its last wire-block time (e.g. derived from the
+consumer's last persisted snapshot) — and the stream seeds its high-water marks
+from those times, each clamped not-future. Only times are needed; no typed
+values. The clock is the `aioabrp._clock._now` seam (the monkeypatch target in
+tests).
+
+### Logging
+
+Enable the `aioabrp` logger at `DEBUG` for triage. Connect/disconnect and
+reasons log at `INFO`, watchdog stalls at `WARNING`, per-frame activity at
+`DEBUG`. Frames are logged as keys and sizes only — frame bodies, header
+values, and tokens (including GPS coordinates and other PII) are never
+logged. Pass `name=` to `TelemetryStream` to prefix its log lines when
+running multiple streams.
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv sync
+uv run ruff format . && uv run ruff check . && uv run mypy && uv run pytest
+```
+
+Note: the locked dev environment constrains `aiohttp<3.14` because the
+latest `aioresponses` release is incompatible with aiohttp ≥ 3.14
+([aioresponses#289](https://github.com/pnuckowski/aioresponses/issues/289));
+the published runtime dependency stays unpinned.
+
+### Releases
+
+Commits follow [Conventional Commits](https://www.conventionalcommits.org/);
+there is no CHANGELOG file — release notes are generated from the commit
+history by [git-cliff](https://git-cliff.org/) (`cliff.toml`) and published
+as GitHub Releases. Pushing a `v*` tag runs the quality gate, builds the
+sdist + wheel, verifies the tag matches `aioabrp.__version__`, publishes to
+PyPI via [Trusted Publishing](https://docs.pypi.org/trusted-publishers/)
+(OIDC), and creates the GitHub Release.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

aioabrp-0.1.0/cliff.toml

@@ -0,0 +1,35 @@
+# git-cliff configuration — release notes are generated from Conventional
+# Commits (https://www.conventionalcommits.org) by the release workflow.
+# https://git-cliff.org/docs/configuration
+
+[changelog]
+header = ""
+body = """
+{% for group, commits in commits | group_by(attribute="group") %}
+### {{ group | striptags | trim | upper_first }}
+{% for commit in commits %}
+- {{ commit.message | split(pat="\n") | first | upper_first }} ({{ commit.id | truncate(length=7, end="") }})
+{%- endfor %}
+{% endfor %}
+"""
+footer = ""
+trim = true
+
+[git]
+conventional_commits = true
+# Unconventional commits still land in release notes (under "Other") rather
+# than vanishing silently.
+filter_unconventional = false
+protect_breaking_commits = true
+tag_pattern = "v[0-9].*"
+sort_commits = "oldest"
+commit_parsers = [
+  { message = "^feat", group = "<!-- 0 -->Features" },
+  { message = "^fix", group = "<!-- 1 -->Bug fixes" },
+  { message = "^perf", group = "<!-- 2 -->Performance" },
+  { message = "^docs?", group = "<!-- 3 -->Documentation" },
+  { message = "^refactor", group = "<!-- 4 -->Refactoring" },
+  { message = "^test", group = "<!-- 5 -->Testing" },
+  { message = "^(build|ci|chore)", group = "<!-- 6 -->Maintenance" },
+  { message = ".*", group = "<!-- 7 -->Other" },
+]

aioabrp-0.1.0/pyproject.toml

@@ -0,0 +1,100 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aioabrp"
+dynamic = ["version"]
+description = "Async Python client for the A Better Routeplanner (ABRP) / Iternio telemetry API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Martin Andersson" }]
+requires-python = ">=3.14"
+dependencies = ["aiohttp"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/mtandersson/aioabrp"
+Repository = "https://github.com/mtandersson/aioabrp"
+Changelog = "https://github.com/mtandersson/aioabrp/releases"
+Issues = "https://github.com/mtandersson/aioabrp/issues"
+
+[dependency-groups]
+dev = [
+    "aioresponses",
+    "mypy",
+    "pytest",
+    "pytest-asyncio",
+    "ruff",
+]
+
+[tool.uv]
+# aioresponses 0.7.8 (latest) is incompatible with aiohttp >= 3.14, which made
+# ClientResponse.__init__'s `stream_writer` argument required
+# (https://github.com/pnuckowski/aioresponses/issues/289). Constrain the locked
+# dev environment until an aioresponses release supports aiohttp 3.14; the
+# published runtime dependency stays unpinned.
+constraint-dependencies = ["aiohttp<3.14"]
+
+[tool.hatch.version]
+path = "src/aioabrp/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aioabrp"]
+
+[tool.hatch.build.targets.sdist]
+# Local-only planning files are untracked via .git/info/exclude, which
+# hatchling (unlike .gitignore) does not honor — exclude them explicitly
+# so they never ship in the sdist.
+exclude = ["PLAN.md", "docs/"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py314"
+
+[tool.ruff.lint]
+select = [
+    "A",     # flake8-builtins
+    "ASYNC", # flake8-async
+    "B",     # flake8-bugbear
+    "C4",    # flake8-comprehensions
+    "D",     # pydocstyle
+    "E",     # pycodestyle errors
+    "F",     # pyflakes
+    "I",     # isort
+    "ISC",   # flake8-implicit-str-concat
+    "N",     # pep8-naming
+    "PIE",   # flake8-pie
+    "PT",    # flake8-pytest-style
+    "RET",   # flake8-return
+    "RUF",   # ruff-specific rules
+    "SIM",   # flake8-simplify
+    "T20",   # flake8-print
+    "UP",    # pyupgrade
+    "W",     # pycodestyle warnings
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D1"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "pep257"
+
+[tool.mypy]
+python_version = "3.14"
+strict = true
+files = ["src", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"