bpack.descriptors module

Descriptors for binary records.

class bpack.descriptors.BinFieldDescriptor(type: Type | None = None, size: int | None = None, offset: int | None = None, signed: bool | None = None, repeat: int | None = None)

Bases: object

Descriptor for bpack fields.

See also

bpack.descriptors.field() for a description of the attributes.

is_enum_type() → bool

Return True if the field is an enum.

is_int_type() → bool

Return True if the field is an integer or a sub-type of integer.

is_sequence_type() → bool

Return True if the field is a sequence.

update_from_type(type_: Type)

Update the field descriptor according to the specified type.

validate()

Perform validity check on the BinFieldDescriptor instance.

offset: int | None = None

repeat: int | None = None

number of items

signed: bool | None = None

size: int | None = None

item size

property total_size

Total size in bytes of the field (considering all item).

type: Type | None = None

class bpack.descriptors.Field(default, default_factory, init, repr, hash, compare, metadata, kw_only)

Bases: object

compare

default

default_factory

hash

init

kw_only

metadata

name

repr

type

bpack.descriptors.asdict(obj, *, dict_factory=<class 'dict'>) → dict

Return the fields of a record as a new dictionary.

The returned dictionary maps field names to field values.

If given, ‘dict_factory’ will be used instead of built-in dict. The function applies recursively to field values that are dataclass instances. This will also look into built-in containers: tuples, lists, and dicts.

bpack.descriptors.astuple(obj, *, tuple_factory=<class 'tuple'>) → Sequence

Return the fields of a dataclass instance as new tuple of field values.

If given, ‘tuple_factory’ will be used instead of built-in tuple. The function applies recursively to field values that are dataclass instances. This will also look into built-in containers: tuples, lists, and dicts.

bpack.descriptors.baseunits(obj) → EBaseUnits

Return the base units of a binary record descriptor.

bpack.descriptors.bitorder(obj) → EBitOrder | None

Return the bit order of a binary record descriptor.

bpack.descriptors.byteorder(obj) → EByteOrder

Return the byte order of a binary record descriptor (endianness).

bpack.descriptors.calcsize(obj, units: EBaseUnits | None = None) → int

Return the size of the obj record.

If the units parameter is not specified (default) then the returned size is expressed in the same base units of the descriptor.

bpack.descriptors.descriptor(cls, *, size: int | None = None, byteorder: str | EByteOrder = EByteOrder.DEFAULT, bitorder: str | EBitOrder | None = None, baseunits: EBaseUnits = EBaseUnits.BYTES, **kwargs)

Class decorator to define descriptors for binary records.

It converts a dataclass into a descriptor object for binary records.

• ensures that all fields are bpack.descriptor.Field descriptors

• offsets are automatically computed if necessary

• consistency checks on offsets and sizes are performed

Parameters:

• cls – class to be decorated

• size – the size (expressed in base units) of the binary record

• byteorder – the byte-order of the binary record

• bitorder – the bit-order of the binary record (must be None if the base units are bytes). If set to none in bit-based records it is assumed bpack.enums.EBitOrder.DEFAULT which corresponds to bpack.enums.EBitOrder.MSB in all decoders currently implemented.

• baseunits – the base units (bpack.enums.EBaseUnits.BITS or bpack.enums.EBaseUnits.BYTES) used to specify the binary record descriptor

It is also possible to specify as additional keyword arguments all the parameters accepted by dataclasses.dataclass().

bpack.descriptors.field(*, size: int | None = None, offset: int | None = None, signed: bool | None = None, repeat: int | None = None, metadata=None, **kwargs) → Field

Initialize a field descriptor.

Returned object is a Field instance with metadata properly initialized to describe the field of a binary record.

Parameters:

• size – int size of the field in bpack.enums.EBaseUnits

• offset – int offset of the field w.r.t. the beginning of the record (expressed in bpack.enums.EBaseUnits)

• signed – bool True if an int field is signed, False otherwise. This parameter must not be specified for non int fields.

• repeat – int length of the sequence for sequence fields, i.e. fields consisting in multiple items having the same data type. This parameter must not be specified if the data type is not a sequence type (e.g. typing.List).

• metadata – additional metadata to be attached the the field descriptor.

• kwargs – additional keyword arguments for the dataclasses.field() function.

bpack.descriptors.field_descriptors(descriptor, pad: bool = False) → Iterator[BinFieldDescriptor]

Iterate the input record descriptor and return binary field descriptors.

Returned items are instances of the BinFieldDescriptor class describing characteristics of each field of the input binary record descriptor.

If the pad parameter is set to True then also generate dummy field descriptors for padding elements necessary to take into account offsets between fields.

bpack.descriptors.fields(obj) → Sequence[Field]

Return a tuple describing the fields of this descriptor.

bpack.descriptors.flat_fields_iterator(descriptor, offset: int = 0) → Iterator[Field]

Recursively iterate on fields of a record descriptor.

The behavior of this function is similar to the one of bpack.descriptors.fields() if the input descriptor do not contain fields that are descriptors (nested). The main difference is that this one is an iterator while bpack.descriptors.fields() returns a tuple.

If the input descriptor is nested (i.e. has fields that are descriptors), then a the it is visited recursively to return all the fields belonging to the main descriptor and to the nested ones.

The nested descriptors are replaced by their fields and the returned sequence of fields is flat.

Note

please note that in case of nested descriptors, the returned fields are copy of the original ones, with the offset attribute adjusted to the relative to the beginning of the root descriptor.

bpack.descriptors.get_field_descriptor(field: Field, validate: bool = True) → BinFieldDescriptor

Return the field descriptor attached to a Field.

bpack.descriptors.is_descriptor(obj) → bool

Return true if obj is a descriptor or a descriptor instance.

bpack.descriptors.is_field(obj) → bool

Return true if an obj can be considered is a field descriptor.

bpack.descriptors.set_field_descriptor(field: Field, descriptor: BinFieldDescriptor, validate: bool = True) → Field

Set the field metadata according to the specified descriptor.