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: Experimental registry for supported data types. It is public for advanced use, but ordinary code should not depend on it yet.
DtypeKind: The kind of data type.
Endianness: The endianness of the data type.
TibsLike: A type alias for values that can be promoted to Tibs.

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 an experimental public API for advanced introspection and extension work. User code should generally not depend on it yet, as details may change between releases.

>>> 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 or little-endian.

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'>¶

UNSPECIFIED = <Endianness.UNSPECIFIED: ''>¶