BACKLOG.md

Backlog

P0 — Critical

[x] Expand unittest coverage

• Add shared unittest helpers for mocking X-Plane REST/WebSocket responses
• Fill remaining coverage gaps for Dataref, Command, Cache, XPRestAPI, XPWebsocketAPI, XPUDPAPI, XPBeaconMonitor
• Keep uv run python -m unittest discover -v as the test workflow

[x] Fix LSP violations in dataref_value / execute_command / write_dataref

• API.dataref_value returns DatarefReadResult with scalar, array, bytes, and None support
• Standardize write/execute return types with APIResult across the abstract base and overrides
• Verify override compatibility with the type checker

[x] Custom exception hierarchy

• XPWebAPIError(Exception) as base
• XPConnectionError, XPTimeoutError, XPVersionError, XPBeaconError
• Replace bare raise XPlaneNoBeacon() / raise XPlaneTimeout with typed exceptions carrying context

P1 — High

[x] Async support via httpx.AsyncClient

• Add AsyncXPRestAPI (or async mixin) using httpx.AsyncClient
• Async variants of dataref_value, write_dataref, execute_command
• Keep sync API as default; async is opt-in

[x] Separate DatarefCache and CommandCache

• Replace Cache.meta() union return (DatarefMeta | CommandMeta) with two typed classes
• Eliminates isinstance checks in rest.py and ws.py
• Fix get_dataref_meta_* / get_command_meta_* to return precise types from the cache layer

[x] Context manager support

• with xpwebapi.ws_api() as api: for automatic connect/disconnect
• __enter__ / __exit__ on XPRestAPI, XPWebsocketAPI, XPUDPAPI
• Ensure socket/thread cleanup on exit

P2 — Medium

[x] Use Protocol instead of ABC for API

• Replace class API(ABC) with a Protocol for structural subtyping
• Removes need for abstract method stubs that return False

[x] Modernize type annotations

• Replace List, Dict, Tuple from typing with built-in list, dict, tuple
• Replace Optional[X] with X | None
• Use Self from typing where appropriate

[x] Structured logging

• Add JSON log formatter option
• Separate request/response traffic logging from application logging
• Configurable log levels per component via JSON configuration

[x] WebSocket library evaluation

• Evaluate websockets as replacement for simple-websocket
• Better async support, more active maintenance
• Benchmark and migrate if beneficial

P3 — Low

[x] CI/CD pipeline

• GitHub Actions: lint (ruff check), format (ruff format --check), type check (ty check), test (python -m unittest discover -v), and package build validation (uv build)
• Publish version 4.0.0 to PyPI from the tagged release workflow
• Pre-commit hooks for local development
• Preserve MkDocs deployment on pushes to main

[x] Documentation improvements

• Type-annotate all examples
• Add usage patterns (connection lifecycle, monitoring datarefs, executing commands)
• Generate and publish API docs via mkdocstrings

[x] Batch dataref request optimization

• WebSocket API supports bulk subscribe/unsubscribe
• Add monitor_datarefs() batch helper with single round-trip
• Document performance characteristics

[x] Connection pooling

• Reuse httpx.Client across XPRestAPI instances when possible
• Pool configuration options (max connections, timeouts)