models

A collection of classes and functions for creating custom packets.

class models.Field(default_val=None)

A Super class that all other fields inherit from. This class is NOT intended for direct use. Custom Fields MUST inherit from this class.

When creating a custom field you MUST define the c_type property with a valid ctypes data class.

Parameters:default_val – the default value of the field. This is set at instantiation of the Field

c_to_py(c_field)

c_to_py - A function used to convert the ctypes object into a python object. As a default this function simply returns c_field directly from the ctypes.Structure object. It’s up to the other Field’s to define this if further formatting is required in order to turn the ctypes value into something user friendly.

Parameters:c_field – a ctypes object from the packet’s internal ctypes.Structure object

create_field_c_tuple()

create_field_c_tuple - A function used to create the required an field in the ctypes.Structure._fields_ tuple. This must return a tuple that is acceptable for one of the items in the _fields_ list of the ctypes.Structure.

The first value in the tuple MUST be self.field_name as this is used to access the

internal c structure.

py_to_c(val)

py_to_c - A function used to convert a python object into a valid ctypes assignable object. As a default this function simply returns val. It’s up to the other subclassesed Field to define this if further formatting is required in order to set the internal structure of the packet.

Parameters:val – the value the user is attempting to set the packet field to. This can be any python object.

class models.IntField(bit_len=None, signed=False, default_val=0)

An Integer field. This field can be configured to be signed or unsigned. It’s bit length can also be set, however the max bit length for this field is ctypes.sizeof(ctypes.c_int) * 8. This wraps around the ctypes.c_int or ctypes.c_uint data type.

Warning

A word of caution when using the bit_len. If the combination of IntFields with the bit_len set are not byte aligned, there is the possibility of “spare” bits not accessible but used in the overall strucuture. See Unused Bits for more information

Parameters:

• bit_len (int) – the length in bits of the integer.
• signed (bool) – whether to treat the int as an signed integer or unsigned integer (default unsigned)
• default_val (int) – the default value of the field (default 0)

Raises:

ValueError – if the bit_len is less than or equal to 0 or greater than ctypes.sizeof(ctypes.c_int) * 8

create_field_c_tuple()

create_field_c_tuple - A function used to create the required an field in the ctypes.Structure._fields_ tuple. This must return a tuple that is acceptable for one of the items in the _fields_ list of the ctypes.Structure.

The first value in the tuple MUST be self.field_name as this is used to access the

internal c structure.

py_to_c(val)

py_to_c - A function used to convert a python object into a valid ctypes assignable object. As a default this function simply returns val. It’s up to the other subclassesed Field to define this if further formatting is required in order to set the internal structure of the packet.

Parameters:val – the value the user is attempting to set the packet field to. This can be any python object.

class models.IntField8(bit_len=None, signed=False, default_val=0)

An Integer field. This field can be configured to be signed or unsigned. It’s bit length can also be set, however the max bit length for this field is 8. This wraps around the ctypes.c_int8 or ctypes.c_uint8 data type.

Warning

A word of caution when using the bit_len. If the combination of IntFields with the bit_len set are not byte aligned, there is the possibility of “spare” bits not accessible but used in the overall strucuture. See Unused Bits for more information

Parameters:

• bit_len (int) – the length in bits of the integer.
• signed (bool) – whether to treat the int as an signed integer or unsigned integer (default unsigned)
• default_val (int) – the default value of the field (default 0)

Raises:

ValueError – if the bit_len is less than or equal to 0 or greater than 8

class models.IntField16(bit_len=None, signed=False, default_val=0)

An Integer field. This field can be configured to be signed or unsigned. It’s bit length can also be set, however the max bit length for this field is 16. This wraps around the ctypes.c_int16 or ctypes.c_uint16 data type.

Warning

A word of caution when using the bit_len. If the combination of IntFields with the bit_len set are not byte aligned, there is the possibility of “spare” bits not accessible but used in the overall strucuture. See Unused Bits for more information

Parameters:

• bit_len (int) – the length in bits of the integer.
• signed (bool) – whether to treat the int as an signed integer or unsigned integer (default unsigned)
• default_val (int) – the default value of the field (default 0)

Raises:

ValueError – if the bit_len is less than or equal to 0 or greater than 16

class models.IntField32(bit_len=None, signed=False, default_val=0)

An Integer field. This field can be configured to be signed or unsigned. It’s bit length can also be set, however the max bit length for this field is 32. This wraps around the ctypes.c_int32 or ctypes.c_uint32 data type.

Warning

A word of caution when using the bit_len. If the combination of IntFields with the bit_len set are not byte aligned, there is the possibility of “spare” bits not accessible but used in the overall strucuture. See Unused Bits for more information

Parameters:

• bit_len (int) – the length in bits of the integer.
• signed (bool) – whether to treat the int as an signed integer or unsigned integer (default unsigned)
• default_val (int) – the default value of the field (default 0)

Raises:

ValueError – if the bit_len is less than or equal to 0 or greater than 32

class models.IntField64(bit_len=None, signed=False, default_val=0)

An Integer field. This field can be configured to be signed or unsigned. It’s bit length can also be set, however the max bit length for this field is 64. This wraps around the ctypes.c_int64 or ctypes.c_uint64 data type.

Warning

A word of caution when using the bit_len. If the combination of IntFields with the bit_len set are not byte aligned, there is the possibility of “spare” bits not accessible but used in the overall strucuture. See Unused Bits for more information

Parameters:

• bit_len (int) – the length in bits of the integer.
• signed (bool) – whether to treat the int as an signed integer or unsigned integer (default unsigned)
• default_val (int) – the default value of the field (default 0)

Raises:

ValueError – if the bit_len is less than or equal to 0 or greater than 64

class models.ArrayField(array_cls, array_size, default_val=None)

A custom field for handling an array of fields. Only tuples or other ArrayFields can be written to the

Parameters:

• array_cls – a calpack.models.Field subclass object that represent the Field the array will be filled with.
• array_size (int) – the length of the array.

c_to_py(c_field)

c_to_py - A function used to convert the ctypes object into a python object. As a default this function simply returns c_field directly from the ctypes.Structure object. It’s up to the other Field’s to define this if further formatting is required in order to turn the ctypes value into something user friendly.

Parameters:c_field – a ctypes object from the packet’s internal ctypes.Structure object

py_to_c(val)

py_to_c - A function used to convert a python object into a valid ctypes assignable object. As a default this function simply returns val. It’s up to the other subclassesed Field to define this if further formatting is required in order to set the internal structure of the packet.

Parameters:val – the value the user is attempting to set the packet field to. This can be any python object.

class models.PacketField(packet_cls)

A custom Field for handling another packet as a field.

Parameters:packet_cls – A calpack.models.Packet subclass that represents another packet

create_field_c_tuple()

create_field_c_tuple - A function used to create the required an field in the ctypes.Structure._fields_ tuple. This must return a tuple that is acceptable for one of the items in the _fields_ list of the ctypes.Structure.

The first value in the tuple MUST be self.field_name as this is used to access the

internal c structure.

py_to_c(val)

py_to_c - A function used to convert a python object into a valid ctypes assignable object. As a default this function simply returns val. It’s up to the other subclassesed Field to define this if further formatting is required in order to set the internal structure of the packet.

Parameters:val – the value the user is attempting to set the packet field to. This can be any python object.

class models.FlagField(default_val=False)

A custom field for handling single bit ‘flags’.

Parameters:default_val (bool) – the default value of the field (default False)

c_to_py(c_field)

c_to_py - A function used to convert the ctypes object into a python object. As a default this function simply returns c_field directly from the ctypes.Structure object. It’s up to the other Field’s to define this if further formatting is required in order to turn the ctypes value into something user friendly.

Parameters:c_field – a ctypes object from the packet’s internal ctypes.Structure object

c_type

alias of ctypes.c_ubyte

create_field_c_tuple()

create_field_c_tuple - A function used to create the required an field in the ctypes.Structure._fields_ tuple. This must return a tuple that is acceptable for one of the items in the _fields_ list of the ctypes.Structure.

The first value in the tuple MUST be self.field_name as this is used to access the

internal c structure.

py_to_c(val)

py_to_c - A function used to convert a python object into a valid ctypes assignable object. As a default this function simply returns val. It’s up to the other subclassesed Field to define this if further formatting is required in order to set the internal structure of the packet.

Parameters:val – the value the user is attempting to set the packet field to. This can be any python object.

class models.FloatField(default_val=0.0)

A custom field for handling floating point numbers.

c_type

alias of ctypes.c_float

class models.DoubleField(default_val=0.0)

A custom field for handling double floating point numbers

c_type

alias of ctypes.c_double

class models.LongDoubleField(default_val=0.0)

A custom field for handling long double floating point numbers

c_type

alias of ctypes.c_longdouble

class models.BoolField(default_val=False)

A custom field for handling Boolean types

c_type

alias of ctypes.c_bool

py_to_c(val)

py_to_c - A function used to convert a python object into a valid ctypes assignable object. As a default this function simply returns val. It’s up to the other subclassesed Field to define this if further formatting is required in order to set the internal structure of the packet.

Parameters:val – the value the user is attempting to set the packet field to. This can be any python object.

class models.Packet(c_pkt=None, **kwargs)

A super class that custom packet classes MUST inherit from. This class is NOT intended to be used directly, but as a super class.

Example:

class Header(models.Packet):
    source = models.IntField()
    dest = models.IntField()
    data1 = models.IntField()
    data2 = models.IntField()

Parameters:c_pkt – (Optional) a ctypes.Structure object that will be used at the internal c structure. This MUST have the same _fields_ as the Packet would normally have in order for it to work properly.

c_pkt

returns the internal c structure object being used

classmethod from_bytes(buf)

Creates a Packet from a bytes string

Parameters:buf (bytes) – the bytes buffer that will be used to create the packet Returns:an Instance of the Packet as parsed from the bytes string

get_c_field(field_name)

gets the value of the field value of the internal c structure. :param str field_name: the name of the field to get :returns: the field value

set_c_field(field_name, val)

sets the value of the internal c structure.

Parameters:

• field_name (str) – the name of the field to set
• val – a cytpes compatible value to set the field to

to_bytes()

Converts the packet into a bytes string

Returns:the packet as a byte string Return type:bytes

models.typed_property(name, expected_type, default_val=None)

Simple function used to ensure a specific type for a property defined within a class. This can ONLY be used within a class definition as the self keyword is used.

Parameters:

• name (str) – the name of the variable. This can be anything, but cannot be already in use.
• expected_type (type) – the expected type. When setting this property at the class level, if the types do not match, a TypeError is raised.
• default_val – (Optional) the default value for the property. If not set, then None is used. This MUST be of the same type as expected_type or a TypeError is raised.

Returns:

the property

Raises:

TypeError – if the default_val or property’s set value is not of type expected_type