Miscellaneous¶

A collection of items that don’t fit into any other category.

Expression: Allows values parsed to be used in an f-string like way elsewhere in a Format.
Options: Used to set and get global options for the module.
Register: Stores information about what data types are supported.
DtypeKind: The kind of data type.
Endianness: The endianness of the data type.

class Expression(code_str: str)¶

A compiled expression that can be evaluated with a dictionary of variables.

Created with a string that starts and ends with braces, e.g. Expression('{x + 1}').

Expressions are usually created when parsing fields such as Format and If, when an Expression will be implicitly created from sections between braces.

e = Expression('{x + 1}')
assert e.evaluate(x=5) == 6

f = Format('(x: u8, data: [u8; {x}])')  # The number of items in data is an Expression.

Only certain operations are permitted in an Expression - see the node_whitelist. For security reasons, all builtins and double underscores are disallowed in the expression string.

evaluate(**kwargs)¶

Evaluate the expression, disallowing all builtins.

Return type:: Any

classmethod from_int(value)¶

Create an Expression from an integer value.

Return type:: Expression

classmethod from_none()¶

Create an Expression from None.

Return type:: Expression

classmethod from_string(code_str)¶

Create an expression object from a string that starts and ends with braces.

Return type:: Expression

is_none()¶

Returns True if the expression evaluates to None.

Return type:: bool

code: CodeType¶

code_str: str¶

const_value: Any¶

has_const_value: bool¶

node_whitelist = {'Add', 'And', 'BinOp', 'BitAnd', 'BitOr', 'BitXor', 'BoolOp', 'Compare', 'Constant', 'Eq', 'Expr', 'FloorDiv', 'Gt', 'GtE', 'Is', 'IsNot', 'LShift', 'Load', 'Lt', 'LtE', 'Mod', 'Module', 'Mult', 'Name', 'NotEq', 'Or', 'Pow', 'RShift', 'Sub', 'Subscript', 'USub', 'UnaryOp'}¶

class Options¶

Returns the singleton module options instance.

To query and change module options create an instance and set or get properties of it.

if Options().byte_aligned:
    # ...
    Options().byte_aligned = False

property byte_aligned: bool¶: Governs the default byte alignment option in methods that use it.

property indent_size: int¶: The number of spaces used for indentation. Defaults to 4.

property no_color: bool¶: If True then no ANSI color codes will be used in output.

class Register¶

Returns the singleton register of the dtype definitions.

This is used to maintain a centralized registry of data type definitions. It is not yet part of the public API, so should not be used.

>>> print(Register())

classmethod add_dtype(definition)¶

classmethod get_array_dtype(cls, kind, size, items, endianness=Endianness.UNSPECIFIED)¶

Return type:: DtypeArray

classmethod get_single_dtype(cls, kind, size, endianness=Endianness.UNSPECIFIED)¶

Return type:: DtypeSingle

kind_to_def: dict[DtypeKind, DtypeDefinition]¶

enum DtypeKind(value)¶

An enum of the different kinds of data types.

A concrete data type is usually a combination of a kind, a length and possibly modifiers such as an endianness. For example 'f32', 'f64' and 'f64_le' are all different data types, but they share the same kind (DtypeKind.FLOAT).

In most user code Dtypes will be created by parsing a string which will give their kind, length and modifiers.

Valid values are as follows:

UINT = <DtypeKind.UINT: 'u'>¶

INT = <DtypeKind.INT: 'i'>¶

BIN = <DtypeKind.BIN: 'bin'>¶

OCT = <DtypeKind.OCT: 'oct'>¶

HEX = <DtypeKind.HEX: 'hex'>¶

BYTES = <DtypeKind.BYTES: 'bytes'>¶

FLOAT = <DtypeKind.FLOAT: 'f'>¶

BITS = <DtypeKind.BITS: 'bits'>¶

BOOL = <DtypeKind.BOOL: 'bool'>¶

PAD = <DtypeKind.PAD: 'pad'>¶

enum Endianness(value)¶

For whole-byte data types, the endianness can be specified as big-endian, little-endian or native.

If the data type is not a whole number of bytes, the endianness should be set to UNSPECIFIED.

Valid values are as follows:

BIG = <Endianness.BIG: 'be'>¶

LITTLE = <Endianness.LITTLE: 'le'>¶

NATIVE = <Endianness.NATIVE: 'ne'>¶

UNSPECIFIED = <Endianness.UNSPECIFIED: ''>¶