pykoreader 0.2.0

KOReader telemetry snapshot model and Home Assistant command protocol (parsing, command builders, coalescing command queue).

pykoreader

Pure-Python model of the KOReader telemetry snapshot and the Home Assistant command protocol: snapshot parsing, command builders, and a coalescing, capped command queue. No Home Assistant or network dependencies.

Used by the ha-koreader Home Assistant integration, but usable standalone.

Install

pip install pykoreader

Usage

from pykoreader import Snapshot, CommandQueue, parse_payload, commands

# Parse an incoming webhook body (a decoded JSON object) into a typed snapshot.
snap = parse_payload({"battery_level": 80, "reading": True, "book_title": "Foundation"})
print(snap.battery_level, snap.book_title)   # 80 Foundation

# Build and queue commands for the device's next check-in.
queue = CommandQueue()
queue.add(commands.set_frontlight(40))
queue.add(commands.set_frontlight(60))       # idempotent: replaces the previous one
queue.add(commands.show_message("Time to sleep", timeout=10))
print(queue.drain())                         # returns pending commands and clears

API

• Snapshot / Snapshot.from_payload(mapping) — typed telemetry fields; unknown keys kept in .extra.
• parse_payload(raw) — validate a decoded body is an object and return a Snapshot (raises ValueError otherwise).
• commands — builders: set_frontlight, set_warmth, set_frontlight_power, set_wifi, page_turn, goto_page, goto_chapter, toggle_bookmark, set_dark_mode, suspend, restart, refresh, sync_now, show_message; plus type constants and COALESCE_TYPES.
• CommandQueue — add(command), drain(), pending, len(). Coalesces idempotent types (last-write-wins), caps at MAX_QUEUED_COMMANDS.

License

MIT