models¶
A collection of classes and functions for creating custom packets.
-
class
models.
Field
(default_val=None)[source]¶ 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 validctypes
data class.Parameters: default_val – the default value of the field. This is set at instantiation of the Field -
c_to_py
(c_field)[source]¶ 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 otherField
’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
()[source]¶ 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 thectypes.Structure
.- The first value in the tuple MUST be
self.field_name
as this is used to access the - internal c structure.
- The first value in the tuple MUST be
-
py_to_c
(val)[source]¶ 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 subclassesedField
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.
ArrayField
(array_cls, array_size, default_val=None)[source]¶ 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)[source]¶ 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 otherField
’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)[source]¶ 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 subclassesedField
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.
- array_cls – a
-
class
models.
FlagField
(default_val=False)[source]¶ 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)[source]¶ 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 otherField
’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
()[source]¶ 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 thectypes.Structure
.- The first value in the tuple MUST be
self.field_name
as this is used to access the - internal c structure.
- The first value in the tuple MUST be
-
py_to_c
(val)[source]¶ 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 subclassesedField
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.
BoolField
(default_val=False)[source]¶ A custom field for handling Boolean types
-
c_type
¶ alias of
ctypes.c_bool
-
py_to_c
(val)[source]¶ 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 subclassesedField
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)[source]¶ A custom field for handling floating point numbers.
-
c_type
¶ alias of
ctypes.c_float
-
-
class
models.
DoubleField
(default_val=0.0)[source]¶ A custom field for handling double floating point numbers
-
c_type
¶ alias of
ctypes.c_double
-
-
class
models.
LongDoubleField
(default_val=0.0)[source]¶ A custom field for handling long double floating point numbers
-
c_type
¶ alias of
ctypes.c_longdouble
-
-
class
models.
IntField
(bit_len=None, signed=False, default_val=0)[source]¶ 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 thectypes.c_int
orctypes.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 informationParameters: - 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 thanctypes.sizeof(ctypes.c_int) * 8
-
create_field_c_tuple
()[source]¶ 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 thectypes.Structure
.- The first value in the tuple MUST be
self.field_name
as this is used to access the - internal c structure.
- The first value in the tuple MUST be
-
py_to_c
(val)[source]¶ 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 subclassesedField
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)[source]¶ 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
orctypes.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 informationParameters: - 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)[source]¶ 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
orctypes.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 informationParameters: - 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)[source]¶ 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
orctypes.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 informationParameters: - 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)[source]¶ 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
orctypes.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 informationParameters: - 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.
PacketField
(packet_cls)[source]¶ 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
()[source]¶ 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 thectypes.Structure
.- The first value in the tuple MUST be
self.field_name
as this is used to access the - internal c structure.
- The first value in the tuple MUST be
-
py_to_c
(val)[source]¶ 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 subclassesedField
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)[source]¶ A super class that custom packet classes can 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
-
fields
¶ return the fields as a list in the order they were defined.
-
classmethod
from_bytes
(buf)[source]¶ 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)[source]¶ 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
-
-
class
models.
PacketLittleEndian
(c_pkt=None, **kwargs)[source]¶ A super class that custom packet can inherit from. This class is NOT intended to be used directly, but as a super class. This class configures the internal Packet Structure to use Little Endian byte orientation.
Example:
class Header(models.PacketLittleEndian): 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.
-
class
models.
PacketBigEndian
(c_pkt=None, **kwargs)[source]¶ A super class that custom packet can inherit from. This class is NOT intended to be used directly, but as a super class. This class configures the internal Packet Structure to use Big Endian byte orientation.
Example:
class Header(models.PacketBigEndian): 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.