Quick Reference¶

This section gives a summary of the bitformat module’s classes, functions and attributes.

Class Overview¶

Objects in bitformat that can be parsed and built are constructed from the FieldType objects that are listed in the table below. Some of these types will usually be used as part of a larger structure, where they can be optionally constructed from strings - for these types a string example is given in the description.

Class	String format?	Description
FieldType	n/a	The abstract base class for the other classes listed here.
Field	✓	A single data type, with optional name and value.
		`'name: dtype = value'`
FieldArray	✓	An array of a single fixed-length data type, with optional name and value.
		`'name: [dtype; items] = value'`
Format	×	A sequence of other FieldTypes, with optional name.
		`Format([field1, field2, ...], 'name'])`
Repeat	×	Repeat another field type a number of times, with optional name.
		`Repeat(10, 'float64', 'a_name')`

FieldType¶

A FieldType is an abstract base class for all of the other classes in this section. It could represent a single piece of data, it could be a container for other FieldType objects or it could represent an action or decision. You shouldn’t need to deal with this type directly but its methods are available for all of the other field types.

Methods¶

build: Given positional and keyword values, fill in the any empty field(s) and build a Bits object.
parse: Takes a Bits object, parses it according to the field structure and returns the number of bits used.
flatten: Removes any nesting of fields and returns a flat list of FieldsTypes.
tobits: Converts the contents to a Bits bit literal.
tobytes: Converts the contents to a bytes object.
vars: Returns the positional and keyword values that are contained in the field.
clear: Sets the value of everything that is not a marked as const to None.

Properties¶

name: A string that can be used to refer to the FieldType.
value: A property to get and set the value of the field.

Field¶

The Field is the fundamental building block in bitformat. It represents a well-defined amount of binary data with a single data type.

Field(dtype: Dtype | str, name: str = '', value: Any = None, const: bool | None = None)

Additional methods¶

frombits: Construct from bytes, bytearray, a Bits object or a string that can be used to construct a Bits object.
frombytes: Construct from a bytes or bytearray object.
fromstring: Construct from a formatted string to set the dtype, name, value and const parameters.

Additional properties¶

dtype: The data type of the field.
const: Whether the field is a constant bit literal.

FieldArray¶

A FieldArray has a single data type like Field, but instead holds an array of that type. The dtype must have a fixed length to be used in a FieldArray.

FieldArray(dtype: Dtype | str, items: str | int, name: str = '', value: Any = None, const: bool | None = None)

Additional methods¶

fromstring: Construct from a formatted string to set the dtype, items, name, value and const parameters.

Additional properties¶

const: Whether the field is a constant bit literal.
dtype: The data type of the field.
items: The number of items in the array.

Format¶

The Format type is central to creating useful objects in bitformat. It contains a sequence of other FieldType objects, which can include nested Format objects.

Format(fieldtypes: Sequence[FieldType | str], name: str = '')

Additional methods¶

flatten: Returns a flat list of FieldType objects.
append: Add a FieldType object to the end of the Format.
extend: Add a sequence of FieldType objects to the end of the Format.

Special methods¶

__getitem__: Get a FieldType object by index.
__setitem__: Set a FieldType object by index.
__iadd__: Add a FieldType object to the end of the Format.

Repeat¶

A Repeat field repeats another field type a given number of times.