FieldTypes¶

The FieldType class is an abstract base class for ‘field-like’ types that must support some basic operations to be used in a Format.

You shouldn’t usually need to deal with this type directly, but its methods are available for all of the other field types.

The concrete field-type classes are:

Field: An amount of binary data with a single data type, and optionally a name.
Format: A sequence of FieldType objects, such as Field or other Format instances.
If: Uses a condition to choose between a pair of FieldType objects.
Repeat: Used to repeat another FieldType a number of times.
Let: Creates or modifies a variable.
Pass: An empty FieldType object, used as a placeholder.

class FieldType¶

Bases: ABC

abstract clear()¶

Clear the value of the field, unless it is a constant.

Return type:: None

abstract classmethod from_params(*args, **kwargs)¶

Return type:: FieldType

classmethod from_string(s)¶

Create a FieldType instance from a string.

The type is inferred from the string, so it can be a Field, Format, or other FieldType.

Parameters:: s (str) – The string to parse.
Return type:: FieldType
Returns:: The FieldType instance.

abstract has_dynamic_size()¶

Returns whether this FieldType can stretch to fit the available data.

Return type:: bool

info()¶

Return a descriptive string with information about the FieldType.

Note that the output is designed to be helpful to users and is not considered part of the API. You should not use the output programmatically as it may change even between point versions.

Return type:: str

abstract is_const()¶

Returns whether this FieldType is a constant, so doesn’t need any values to be packed.

Return type:: bool

pack(values, /, **kwargs)¶

Pack with values for each non-const field.

Parameters:

values (Union[Sequence[Any], Any]) – The values to pack.
kwargs – Additional keyword arguments.

Return type:

Bits

Returns:

The packed data as a Bits.

parse(b=None, /, **kwargs)¶

Parse the field type from the supplied bits.

The parsing is done lazily, so any values might not be calculated at this point, instead waiting until they are explicitly asked for.

Parameters:: b (BitsType | None) – The bits to parse.
Return type:: int
Returns:: The number of bits used.

pp(stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, indent=None, depth=None)¶

Pretty-print the fieldtype to a stream (or stdout by default).

Parameters:

stream (TextIO) – The stream to write to.
indent (int | None) – The number of spaces for each level of indentation. Defaults to Options().indent_size which defaults to 4.
depth (int | None) – The maximum depth to print, or None for no limit.

Return type:

None

abstract to_bits()¶

Return the bits that represent the field.

Return type:: Bits
Returns:: The bits that represent the field.

to_bytes()¶

Return the bytes that represent the field. Pads with up to 7 zero bits if necessary.

Return type:: bytes
Returns:: The bytes that represent the field.

unpack(b=None, **kwargs)¶

Unpack the field type from bits.

Parameters:: b (BitsType | None) – The bits to unpack.
Return type:: Any | list[Any]
Returns:: The unpacked value.

property bit_length: int¶

property name: str | None¶

property value: Any¶

class Field(s: str)¶

Bases: FieldType

clear()¶

Clear the value of the field, unless it is a constant.

Return type:: None

classmethod from_bits(b, /, name='', const=False)¶

Create a Field instance of dtype Bits.

Parameters:

b (Union[Bits, str, Iterable, bytearray, bytes, memoryview]) – The Bits or something that can be converted to Bits (such as a formatted string).
name (str) – The name of the field, optional.
const (bool) – Whether the field is constant, defaults to False.

Return type:

Self

Returns:

The Field instance.

classmethod from_bytes(b, /, name='', const=False)¶

Create a Field instance of dtype bytes.

Parameters:

b (bytes | bytearray) – The bytes or bytearray value to use.
name (str) – The name of the field, optional.
const (bool) – Whether the field is constant, defaults to False.

Return type:

Field

Returns:

The Field instance.

classmethod from_params(dtype, name='', value=None, const=False)¶

Create a Field instance from parameters.

Parameters:

dtype (Dtype | str) – The data type of the field.
name (str) – The name of the field, optional.
value (Any) – The value of the field, optional.
const (bool) – Whether the field is constant, optional.

Return type:

Self

Returns:

The Field instance.

classmethod from_string(s, /)¶

Create a FieldType instance from a string.

The type is inferred from the string, so it can be a Field, Format, or other FieldType.

Parameters:: s (str) – The string to parse.
Return type:: Self
Returns:: The FieldType instance.

has_dynamic_size()¶

Returns whether this FieldType can stretch to fit the available data.

Return type:: bool

info()¶

Return a descriptive string with information about the FieldType.

Note that the output is designed to be helpful to users and is not considered part of the API. You should not use the output programmatically as it may change even between point versions.

Return type:: str

is_const()¶

Returns whether this FieldType is a constant, so doesn’t need any values to be packed.

Return type:: bool

pack(values, /, **kwargs)¶

Pack with values for each non-const field.

Parameters:

values (Union[Sequence[Any], Any]) – The values to pack.
kwargs – Additional keyword arguments.

Return type:

Bits

Returns:

The packed data as a Bits.

parse(b=None, /, **kwargs)¶

Parse the field type from the supplied bits.

The parsing is done lazily, so any values might not be calculated at this point, instead waiting until they are explicitly asked for.

Parameters:: b (BitsType | None) – The bits to parse.
Return type:: int
Returns:: The number of bits used.

pp(stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, indent=None, depth=None)¶

Pretty-print the fieldtype to a stream (or stdout by default).

Parameters:

stream (TextIO) – The stream to write to.
indent (int | None) – The number of spaces for each level of indentation. Defaults to Options().indent_size which defaults to 4.
depth (int | None) – The maximum depth to print, or None for no limit.

Return type:

None

to_bits()¶

Return the bits that represent the field.

Return type:: Bits
Returns:: The bits that represent the field.

to_bytes()¶

Return the bytes that represent the field. Pads with up to 7 zero bits if necessary.

Return type:: bytes
Returns:: The bytes that represent the field.

unpack(b=None, **kwargs)¶

Unpack the field type from bits.

Parameters:: b (BitsType | None) – The bits to unpack.
Return type:: Any | list[Any]
Returns:: The unpacked value.

property bit_length: int¶

property dtype: Dtype¶

property name: str | None¶

property value: Any¶

class Format(s: str | None = None)¶

Bases: FieldType

A sequence of FieldType objects, used to group fields together.

append(value)¶

Append a field to the format.

Parameters:: value (Any) – The field to append.
Return type:: None

clear()¶

Clear the value of the field, unless it is a constant.

Return type:: None

extend(values)¶

Extend the format with multiple fields.

Parameters:: values (Iterable) – The fields to add.
Return type:: None

classmethod from_params(fields=None, name='')¶

Create a Format instance.

Parameters:

fields (Optional[Sequence[FieldType | str]]) – The field types to include in the format, optional.
name (str) – The name of the format, optional.

Return type:

Self

Returns:

The Format instance.

classmethod from_string(s, /)¶

Create a Format instance from a string.

The string should be of the form '(field1, field2, ...)' or 'name: (field1, field2, ...)', with commas separating strings that will be used to create other FieldType instances.

Parameters:: s (str) – The string to parse.
Return type:: Self
Returns:: The Format instance.

f1 = Format.from_string('(u8, bool=True, val: i7)')
f2 = Format.from_string('my_format: (float16,)')
f3 = Format.from_string('(u16, another_format: ([u8; 64], [bool; 8]))')

has_dynamic_size()¶

Returns whether this FieldType can stretch to fit the available data.

Return type:: bool

info()¶

Return a descriptive string with information about the FieldType.

Note that the output is designed to be helpful to users and is not considered part of the API. You should not use the output programmatically as it may change even between point versions.

Return type:: str

is_const()¶

Returns whether this FieldType is a constant, so doesn’t need any values to be packed.

Return type:: bool

pack(values, /, **kwargs)¶

Pack with values for each non-const field.

Parameters:

values (Union[Sequence[Any], Any]) – The values to pack.
kwargs – Additional keyword arguments.

Return type:

Bits

Returns:

The packed data as a Bits.

parse(b=None, /, **kwargs)¶

Parse the field type from the supplied bits.

The parsing is done lazily, so any values might not be calculated at this point, instead waiting until they are explicitly asked for.

Parameters:: b (BitsType | None) – The bits to parse.
Return type:: int
Returns:: The number of bits used.

pp(stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, indent=None, depth=None)¶

Pretty-print the fieldtype to a stream (or stdout by default).

Parameters:

stream (TextIO) – The stream to write to.
indent (int | None) – The number of spaces for each level of indentation. Defaults to Options().indent_size which defaults to 4.
depth (int | None) – The maximum depth to print, or None for no limit.

Return type:

None

to_bits()¶

Return the bits that represent the field.

Return type:: Bits
Returns:: The bits that represent the field.

to_bytes()¶

Return the bytes that represent the field. Pads with up to 7 zero bits if necessary.

Return type:: bytes
Returns:: The bytes that represent the field.

unpack(b=None, **kwargs)¶

Unpack the field type from bits.

Parameters:: b (BitsType | None) – The bits to unpack.
Return type:: Any | list[Any]
Returns:: The unpacked value.

property bit_length: int¶

property name: str | None¶

property value: Any¶

vars: dict[str, Any]¶

class If(s: str)¶

Bases: FieldType

clear()¶

Clear the value of the field, unless it is a constant.

Return type:: None

classmethod from_params(condition, then_, else_=None, /)¶

The else_ parameter is optional, and defaults to a Pass field if not provided.

Note that only a single FieldType can be provided for each of the then_ and else_ clauses. If you need to provide multiple fields, use a Format.

Return type:: If

classmethod from_string(s, /)¶

Create an If field from a string.

The string should be in the format:

Return type:: If

if {expression}:: then_field
else:: else_field

The else clause is optional, and defaults to a Pass field if not provided.

has_dynamic_size()¶

Returns whether this FieldType can stretch to fit the available data.

Return type:: bool

is_const()¶

Returns whether this FieldType is a constant, so doesn’t need any values to be packed.

Return type:: bool

to_bits()¶

Return the bits that represent the field.

Return type:: Bits
Returns:: The bits that represent the field.

condition: Expression¶

condition_value: bool | None¶

else_: FieldType¶

then_: FieldType¶

class Repeat(s: str)¶

Bases: FieldType

clear()¶

Clear the value of the field, unless it is a constant.

Return type:: None

classmethod from_params(count, fieldtype, value=None)¶

Create a Repeat instance.

Parameters:

count (int | str | Expression) – An Expression or int giving the number of repetitions to do.
fieldtype (FieldType | str) – The FieldType to repeat.
value (Optional[Iterable[Any]]) – The list of values for the FieldType, one for each repetition.

Return type:

Repeat

Returns:

The Repeat instance.

classmethod from_string(s)¶

Create a Repeat instance from a string.

The string should be of the form 'repeat {expression}: fieldtype'. The fieldtype can be a Format to group multiple fields together.

Parameters:: s (str) – The string to parse.
Return type:: Repeat
Returns:: The Repeat instance.

r1 = Repeat.from_string('repeat {5}: u8')
r2 = Repeat.from_string('repeat {3}: f32 = [0.0, 13.5, -5.05]')
r3 = Repeat.from_string('repeat {x + 1}: (bool, f64)')

has_dynamic_size()¶

Returns whether this FieldType can stretch to fit the available data.

Return type:: bool

is_const()¶

Returns whether this FieldType is a constant, so doesn’t need any values to be packed.

Return type:: bool

to_bits()¶

Return the bits that represent the field.

Return type:: Bits
Returns:: The bits that represent the field.

property count: Expression¶

The count of the Repeat field.

Returns:: The count of the Repeat field.

field: FieldType¶

class Let(s: str)¶

Bases: FieldType

A FieldType that assigns expression results to variables.

This is only useful within a Format where other fields can refer to the variable.

clear()¶

Clearing a Let field has no effect.

Return type:: None

classmethod from_params(name, expr)¶

Create a Let instance.

Parameters:

name (str) – The variable name to assign to.
expr (str | int | Expression) – The Expression to evaluate.

Return type:

Let

Returns:

The Let instance.

increment_x = Let.from_params('x', '{x + 1}')

has_dynamic_size()¶

Returns False for a Let field.

Return type:: bool

is_const()¶

Returns True for a Let field.

Return type:: bool

to_bits()¶

Returns an empty Bits.

Return type:: Bits

class Pass¶

Bases: FieldType

An empty placeholder FieldType.

A Pass field has zero bit_length and no value. It can be used in conditionals when no action is required. When used elsewhere in a Format it may be removed as an optimisation. All Pass fields are identical, so they are implemented as a singleton.

It is usually created implicitly, for example in an If field when no else field is provided.

cond = If.from_params('{ x > 0 }', Pass(), 'bool')

clear()¶

Clearing a Pass field has no effect.

Return type:: None

classmethod from_params(*args, **kwargs)¶

Returns the singleton Pass instance. The args and kwargs are ignored.

Return type:: FieldType

has_dynamic_size()¶

Returns False for a Pass field.

Return type:: bool

is_const()¶

Returns True for a Pass field.

Return type:: bool

to_bits()¶

Returns an empty Bits.

Return type:: Bits