Parameterize HarpMessage by its payload type

[glopesdev]

HarpMessage is now generic over its payload type and ParsedHarpMessage is retired. A frame off the wire is a HarpMessage[Any], and decoding it with a register yields a HarpMessage[P], so read, write and subscribe all deliver one type carrying the frame and the decoded value together. That is what keeps the timestamp, the message type and the error flag reachable from whatever a read returns, instead of having to be recovered separately.

payload names the typed contract

payload is now the decoded value and payload_bytes is the frame bytes, inverting the previous split where payload was the bytes and parsed was the value.

Two things support reading payload as the typed contract rather than the encoding. Bonsai.Harp already uses it that way through its GetPayload() family, and Harp's own schema uses payloadSpec and payloadMember to describe a structured contract rather than bytes. parsed named how the value was obtained rather than what it is. payload_bytes also pairs with the existing bytes property, whole frame against the payload portion of it, which the alternative did not.

One generic class rather than a subclass

Python generics are erased, so HarpMessage[Any] expresses the untyped case on the same class and no second type is needed. A subclass would have needed a name for something with no role in the protocol, since a typed message is not specifically a reply and not specifically an event.

The cost this accepts is that HarpMessage[Any].payload is Any, so an unsafe access on the raw path from parse or subscribe_all is not caught statically. Reading payload before a register has decoded a message raises rather than falling back to the bytes, and has_payload reports which state a message is in, so an explicit check is available where the static type cannot help.

Decoding is bound to the message it came from

The new msg.decode(register) method is the only way to attach a typed payload. It derives the payload from the frame in the same call, so the two cannot disagree. Decoding also checks what parse does not. A U32 frame read through a U16 register, and a four-byte payload read through a scalar register, both raise instead of silently returning the leading bytes. The address is deliberately not checked, since the payload type and byte count decide whether these bytes can be read as this payload at all, while the address says which register the device meant. That keeps a frame decodable by any register describing the same layout.

This also closes a hole that was open in two places. ParsedHarpMessage could be constructed with any parsed value, and ParsedHarpMessage.from_message(msg, parsed) would wrap any message with any value, so nothing checked that a payload came from the bytes beside it.

Note

typing-extensions rises to >=4.14 since Sentinel arrives in 4.14 and three modules on main already import it.