Runtime API

For incremental parsing in context, see 4. Try partial input. For mapping-based operation examples, see How to compile mapping-based schemas. rustruct.compile() produces a rustruct.Codec; a rustruct.Struct subclass compiles and holds one internally.

Compilation and codec

rustruct.compile(fields, *, byteorder='big', max_default=67108864, max_count=16777216)

Compile a schema in the documented (name, kind, opts) form.

This is rustruct.compile. The parsing it does is generated from the kind table in parse.rs, so the set of options a kind accepts and the code that reads them come out of one declaration.

class rustruct.Codec

min_size

Lower bound of the size.

pack_into(buf, offset, values)

Writes into an existing writable buffer, returns the new position.

parse(buf, offset=0)

Streaming parse: a data shortage yields Incomplete, not an exception.

static_size

Exact size, if the schema is static.

unpack(buf)

Requires the buffer to be fully consumed; a tail raises InvalidDataError with kind=”trailing”.

unpack_from(buf, offset=0)

A trailing tail is allowed; returns (dict, new position).

Streaming result

class rustruct.Incomplete

The result of parse() when data is missing: falsy.

needed

Minimum bytes missing beyond the end of the buffer (a lower bound).

Incomplete is falsy and exposes needed.

Errors

PackError and InvalidDataError carry kind and path, and InvalidDataError also carries offset.

exception rustruct.RustructError

Base of every error this package raises.

exception rustruct.SchemaError

A schema compile() cannot accept.

Raised while the schema is being read, before any data is touched – an unknown kind or option, a reference to a field that is not in scope, a byte order the core refuses.

exception rustruct.PackError

Values that cannot be written as the schema describes them.

Raised by pack and pack_into. There is no offset: the failure is found before anything is written.

exception rustruct.InvalidDataError

Wire data that does not match the schema.

Raised by unpack, unpack_from and parse.