Codec

class dsviper.Codec

Bases: object

The registry of named codecs: ask for one by name with query() or check(), or take STREAM_RAW, STREAM_BINARY or STREAM_TOKEN_BINARY directly. It resolves a codec, it does not create one.

Which one to take, and what each keeps:

STREAM_RAW writes each number in the byte order of the host

that wrote it. Its home is a transport that cannot leave the machine - shared memory above all, where both ends are the same host and swapping bytes buys nothing. The cheapest, for exactly that reason.

STREAM_BINARY same size, but the order is fixed little-endian

whoever writes. The one to take the moment the bytes can reach another machine: a file you ship, a socket, a blob a peer will read.

STREAM_TOKEN_BINARY adds one byte in front of each value, naming its

type. That byte is what a reader checks: reading a uint32 back as a uint16 RAISES here, where the two above answer a number built from the wrong bytes and report nothing.

Choosing the wrong one of the first two is not reported, and cannot be: on a little-endian host they write the SAME BYTES, so a stream carries no record of which produced it. The mistake is invisible where it is made and surfaces on the first big-endian peer, which may be years later. The two ends have to agree out of band - or use STREAM_TOKEN_BINARY, whose token makes a mismatched pair fail at the first read instead.

None of the three writes the shape of what you encoded: the reader calls the same reads in the same order, and a token only says a value is not the type asked for. Keep the definitions that describe the data, or use a database, which keeps them for you.

Note: Not directly instantiable.

STREAM_BINARY = StreamBinary

STREAM_RAW = StreamRaw

STREAM_TOKEN_BINARY = StreamTokenBinary

static check(name: str) → StreamCodecInstancing

Return the StreamCodecInstancing of the codec named name, or raise. The names are StreamRaw, StreamBinary and StreamTokenBinary.

static query(name: str) → StreamCodecInstancing | None

Return the StreamCodecInstancing of the codec named name, or None. The names are StreamRaw, StreamBinary and StreamTokenBinary.