Reference¶

StructDef (struct and union representation)¶

class pycstruct.StructDef(default_byteorder='native', alignment=1, union=False)¶

This class represents a struct or a union definition

Parameters:

default_byteorder (str, optional) – Byte order of each element unless explicitly set for the element. Valid values are ‘native’, ‘little’ and ‘big’.
alignment (str, optional) – Alignment of elements in bytes. If set to a value > 1 padding will be added between elements when necessary. Use 4 for 32 bit architectures, 8 for 64 bit architectures unless packing is performed.
union (boolean, optional) – If this is set the True, the instance will behave like a union instead of a struct, i.e. all elements share the same data (same start address). Default is False.

add(datatype, name, length=1, byteorder='', same_level=False, shape=None)¶

Add a new element in the struct/union definition. The element will be added directly after the previous element if a struct or in parallel with the previous element if union. Padding might be added depending on the alignment setting.

Supported data types:

Name Size in bytes Comment

int8 1 Integer

uint8 1 Unsigned integer

bool8 1 True (<>0) or False (0)

int16 2 Integer

uint16 2 Unsigned integer

bool16 2 True (<>0) or False (0)

float16 2 Floating point number

int32 4 Integer

uint32 4 Unsigned integer

bool32 4 True (<>0) or False (0)

float32 4 Floating point number

int64 8 Integer

uint64 8 Unsigned integer

bool64 8 True (<>0) or False (0)

float64 8 Floating point number

utf-8 1 UTF-8/ASCII string. Use length parameter to set the length of the string including null termination

struct struct size Embedded struct. The actual StructDef object shall be set as type and not ‘struct’ string.

bitfield bitfield size Bitfield. The actual BitfieldDef() object shall be set as type and not ‘bitfield’ string.

enum enum size Enum. The actual EnumDef() object shall be set as type and not ‘enum’ string.

Parameters:

datatype (str | _BaseDef) – Element data type. See above.
name (str) – Name of element. Needs to be unique.
length (int, optional) – Number of elements. If > 1 this is an array/list of elements with equal size. Default is 1. This should only be specified for string size. Use shape for arrays.
shape (int, tuple, optional) – If specified an array of this shape is defined. It supported, int, and tuple of int for multi-dimentional arrays (the last is the fast axis)
byteorder (str, optional) – Byteorder of this element. Valid values are ‘native’, ‘little’ and ‘big’. If not specified the default byteorder is used.
same_level (bool, optional) – Relevant if adding embedded bitfield. If True, the serialized or deserialized dictionary keys will be on the same level as the parent. Default is False.

create_empty_data()¶

Create an empty dictionary with all keys

Returns:	A dictionary keyed with the element names. Values are “empty” or 0.
Return type:	dict

deserialize(buffer, offset=0)¶: Deserialize buffer into dictionary

dtype()¶

Returns the dtype of this structure as defined by numpy.

This allows to use the pycstruct modelization together with numpy to read C structures from buffers.

color_t = StructDef()
color_t.add("uint8", "r")
color_t.add("uint8", "g")
color_t.add("uint8", "b")
color_t.add("uint8", "a")
raw = b""
color = numpy.frombuffer(raw, dtype=color_t.dtype())

Returns:	a python dict representing a numpy dtype
Return type:	dict

get_field_type(name)¶

Returns the type of a field of this struct.

Returns:	Type if the field
Return type:	_BaseDef

instance(buffer=None, buffer_offset=0)¶

Create an instance of this struct / union.

This is an alternative of using dictionaries and the StructDef.serialize()/ StructDef.deserialize() methods for representing the data.

Parameters:	buffer (bytearray, optional) – Byte buffer where data is stored. If no buffer is provided a new byte buffer will be created and the instance will be ‘empty’. buffer_offset (int, optional) – Start offset in the buffer. This means that you can have multiple Instances (or other data) that shares the same buffer.
Returns:	A new Instance object
Return type:	`Instance()`

remove_from(name)¶

Remove all elements from a specific element

This function is useful to create a sub-set of a struct.

param name: Name of element to remove and all after this element

type name: str

remove_to(name)¶

Remove all elements from beginning to a specific element

This function is useful to create a sub-set of a struct.

param name: Name of element to remove and all before element

type name: str

serialize(data, buffer=None, offset=0)¶

Serialize dictionary into buffer

NOTE! If this is a union the method will try to serialize all the elements into the buffer (at the same position in the buffer). It is quite possible that the elements in the dictionary have contradicting data and the buffer of the last serialized element will be ok while the others might be wrong. Thus you should only define the element that you want to serialize in the dictionary.

Parameters:	data (dict) – A dictionary keyed with element names. Elements can be omitted from the dictionary (defaults to value 0).
Returns:	A buffer that contains data
Return type:	bytearray

size()¶

Get size of structure or union.

Returns:	Number of bytes this structure represents alternatively largest of the elements (including end padding) if this is a union.
Return type:	int

BitfieldDef (bitfield representation)¶

class pycstruct.BitfieldDef(byteorder='native', size=-1)¶

This class represents a bit field definition

The size of the bit field is 1, 2, 3, .., 8 bytes depending on the number of elements added to the bit field. You can also force the bitfield size by setting the size argument. When forcing the size larger bitfields than 8 bytes are allowed.

Parameters:	byteorder (str, optional) – Byte order of the bitfield. Valid values are ‘native’, ‘little’ and ‘big’. size (int, optional) – Force bitfield to be a certain size. By default it will expand when new elements are added.

add(name, nbr_of_bits=1, signed=False)¶

Add a new element in the bitfield definition. The element will be added directly after the previous element.

The size of the bitfield will expand when required, but adding more than in total 64 bits (8 bytes) will generate an exception.

Parameters:	name (str) – Name of element. Needs to be unique. nbr_of_bits (int, optional) – Number of bits this element represents. Default is 1. signed (bool, optional) – Should the bit field be signed or not. Default is False.

assigned_bits()¶

Get size of bitfield in bits excluding padding bits

Returns:	Number of bits this bitfield represents excluding padding bits
Return type:	int

create_empty_data()¶

Create an empty dictionary with all keys

Returns:	A dictionary keyed with the element names. Values are “empty” or 0.
Return type:	dict

deserialize(buffer, offset=0)¶

Deserialize buffer into dictionary

Parameters:	buffer (int) – Buffer that contains the data to deserialize (1 - 8 bytes) buffer_offset – Start address in buffer
Returns:	A dictionary keyed with the element names
Return type:	dict

instance(buffer=None, buffer_offset=0)¶

Create an instance of this bitfield.

This is an alternative of using dictionaries and the BitfieldDef.serialize()/ BitfieldDef.deserialize() methods for representing the data.

Parameters:	buffer (bytearray, optional) – Byte buffer where data is stored. If no buffer is provided a new byte buffer will be created and the instance will be ‘empty’. buffer_offset (int, optional) – Start offset in the buffer. This means that you can have multiple Instances (or other data) that shares the same buffer.
Returns:	A new Instance object
Return type:	`Instance()`

serialize(data, buffer=None, offset=0)¶

Serialize dictionary into buffer

Parameters:	data (dict) – A dictionary keyed with element names. Elements can be omitted from the dictionary (defaults to value 0).
Returns:	A buffer that contains data
Return type:	bytearray

size()¶

Get size of bitfield in bytes

Returns:	Number of bytes this bitfield represents
Return type:	int

EnumDef (enum representation)¶

class pycstruct.EnumDef(byteorder='native', size=-1, signed=False)¶

This class represents an enum definition

The size of the enum is 1, 2, 3, .., 8 bytes depending on the value of the largest enum constant. You can also force the enum size by setting the size argument.

Parameters:	byteorder (str, optional) – Byte order of the enum. Valid values are ‘native’, ‘little’ and ‘big’. size (int, optional) – Force enum to be a certain size. By default it will expand when new elements are added. signed (bool, optional) – True if enum is signed (may contain negative values)

add(name, value=None)¶

Add a new constant in the enum definition. Multiple constant might be assigned to the same value.

The size of the enum will expand when required, but adding a value requiring a size larger than 64 bits will generate an exception.

Parameters:	name (str) – Name of constant. Needs to be unique. value (int, optional) – Value of the constant. Automatically assigned to next available value (0, 1, 2, …) if not provided.

deserialize(buffer, offset=0)¶

Deserialize buffer into a string (constant name)

If no constant name is defined for the value following name will be returned:

__VALUE__<value>

Where <value> is the integer stored in the buffer.

Parameters:	buffer (bytearray) – Buffer that contains the data to deserialize (1 - 8 bytes)
Returns:	The constant name (string)
Return type:	str

get_name(value)¶

Get the name representation of the value

Returns:	The constant name
Return type:	str

get_value(name)¶

Get the value representation of the name

Returns:	The value
Return type:	int

serialize(data, buffer=None, offset=0)¶

Serialize string (constant name) into buffer

Parameters:	data (str) – A string representing the constant name.
Returns:	A buffer that contains data
Return type:	bytearray

size()¶

Get size of enum in bytes

Returns:	Number of bytes this enum represents
Return type:	int

Parse source code files¶

pycstruct.parse_file(input_files, byteorder='native', castxml_cmd='castxml', castxml_extra_args=None, cache_path='', use_cached=False, **subprocess_kwargs)¶

Parse one or more C source files (C or C++) and generate pycstruct instances as a result.

The result is a dictionary where the keys are the names of the struct, unions etc. typedef’ed names are also supported.

The values of the resulting dictionary are the actual pycstruct instance connected to the name.

This function requires that the external tool castxml is installed.

Alignment will automatically be detected and configured for the pycstruct instances.

Note that following pycstruct types will be used for char arrays:

‘unsigned char []’ = uint8 array
‘signed char []’ = int8 array
‘char []’ = utf-8 data (string)

Parameters:	input_files (str or list) – Source file name or a list of file names. byteorder (str, optional) – Byteorder of all elements Valid values are ‘native’, ‘little’ and ‘big’. If not specified the ‘native’ byteorder is used. castxml_cmd (str, optional) – Path to the castxml binary. If not specified castxml must be within the PATH. castxml_extra_args (list, optional) – Extra arguments to provide to castxml. For example definitions etc. Check castxml documentation for which arguments that are supported. cache_path (str, optional) – Path where to store temporary files. If not provided, the default system temporary directory is used. use_cached (boolean, optional) – If this is True, use previously cached output from castxml to avoid re-running castxml (since it could be time consuming). Default is False. subprocess_kwargs – keyword arguments that will be passed down to the subprocess.check_outputs() call used to run castxml. By default, stderr will be redirected to stdout. To get the subprocess default behavior, pass stderr=None.
Returns:	A dictionary keyed on names of the structs, unions etc. The values are the actual pycstruct instances.
Return type:	dict

Parse source code strings¶

pycstruct.parse_str(c_str, byteorder='native', castxml_cmd='castxml', castxml_extra_args=None, cache_path='', use_cached=False)¶

Parse a string containing C source code, such as struct or union defintions. Any valid C code is supported.

The result is a dictionary where the keys are the names of the struct, unions etc. typedef’ed names are also supported.

The values of the resulting dictionary are the actual pycstruct instance connected to the name.

This function requires that the external tool castxml is installed.

Alignment will automatically be detected and configured for the pycstruct instances.

Note that following pycstruct types will be used for char arrays:

‘unsigned char []’ = uint8 array
‘signed char []’ = int8 array
‘char []’ = utf-8 data (string)

Parameters:	c_str (str) – A string of C source code. byteorder (str, optional) – Byteorder of all elements Valid values are ‘native’, ‘little’ and ‘big’. If not specified the ‘native’ byteorder is used. castxml_cmd (str, optional) – Path to the castxml binary. If not specified castxml must be within the PATH. castxml_extra_args (list, optional) – Extra arguments to provide to castxml. For example definitions etc. Check castxml documentation for which arguments that are supported. cache_path (str, optional) – Path where to store temporary files. If not provided, the default system temporary directory is used. use_cached (boolean, optional) – If this is True, use previously cached output from castxml to avoid re-running castxml (since it could be time consuming). Default is False.
Returns:	A dictionary keyed on names of the structs, unions etc. The values are the actual pycstruct instances.
Return type:	dict

Instance (instance of StructDef or BitfieldDef)¶

pycstruct.Instance(datatype, buffer=None, buffer_offset=0)¶

This class represents an Instance of either a StructDef() or a BitfieldDef(). The instance object contains a bytearray buffer where ‘raw data’ is stored.

The Instance object has following advantages over using dictionary objects:

Data is only serialized/deserialized when accessed
Data is validated for each element/attribute access. I.e. you will get an exception if you try to set an element/attribute to a value that is not supported by the definition.
Data is accessed by attribute name instead of key indexing

Parameters:

type (StructDef() or BitfieldDef()) – The StructDef() class or BitfieldDef() class that we would like to create an instance of.
buffer (bytearray, optional) – Byte buffer where data is stored. If no buffer is provided a new byte buffer will be created and the instance will be ‘empty’.
buffer_offset (int, optional) – Start offset in the buffer. This means that you can have multiple Instances (or other data) that shares the same buffer.

Reference¶

StructDef (struct and union representation)¶

BitfieldDef (bitfield representation)¶

EnumDef (enum representation)¶

Parse source code files¶

Parse source code strings¶

Instance (instance of StructDef or BitfieldDef)¶

pycstruct

Navigation

Related Topics

Name	Size in bytes	Comment
int8	1	Integer
uint8	1	Unsigned integer
bool8	1	True (<>0) or False (0)
int16	2	Integer
uint16	2	Unsigned integer
bool16	2	True (<>0) or False (0)
float16	2	Floating point number
int32	4	Integer
uint32	4	Unsigned integer
bool32	4	True (<>0) or False (0)
float32	4	Floating point number
int64	8	Integer
uint64	8	Unsigned integer
bool64	8	True (<>0) or False (0)
float64	8	Floating point number
utf-8	1	UTF-8/ASCII string. Use length parameter to set the length of the string including null termination
struct	struct size	Embedded struct. The actual StructDef object shall be set as type and not ‘struct’ string.
bitfield	bitfield size	Bitfield. The actual `BitfieldDef()` object shall be set as type and not ‘bitfield’ string.
enum	enum size	Enum. The actual `EnumDef()` object shall be set as type and not ‘enum’ string.

param name:	Name of element to remove and all after this element
type name:	str

param name:	Name of element to remove and all before element
type name:	str