ecom.datatypes

Module Contents

Classes

StrEnum	str(object='') -> str
CommunicationDatabaseAccessor	A generic base for classes that want to access the communication database.
StructTypeMeta	Metaclass for the StructType.
StructType	Represents a C struct. Can be iterated over to get the struct members.
ArrayTypeMeta	Metaclass for the ArrayType.
ArrayType	Represents a C array. Provides the type and constant size of the array.
EnumTypeMeta	Metaclass for Enums that are compatible with C style enums and can be compared.
EnumType	Represents a C style enum.
DefaultValueInfo	A default value for a type.
TypeInfo	Describes a data type.

Functions

dataclass_transform()
loadTypedValue(→ Any)	Load a value with the given type.
structField(→ dataclasses.Field)	Declare a new struct dataclass field. This is a wrapper around the dataclasses.field() function.
isStructField(→ bool)	Check whether the given field is a struct field created with ecom.datatypes.structField().
getStructFieldName(→ str)	Get the name of the element in the struct of a struct field. This can be different from the dataclass field name.
getStructFieldType(→ Optional[TypeInfo])	Get the type of the struct field or None, if the struct field does not define its type.
structDataclass(database[, replaceType])	A decorator for a class that inherits from StructType that allows it to act as a dataclass.

Attributes

T
V

class ecom.datatypes.StrEnum

Bases: str, enum.Enum

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

ecom.datatypes.dataclass_transform()

class ecom.datatypes.CommunicationDatabaseAccessor(database: database.CommunicationDatabase)

A generic base for classes that want to access the communication database.

ecom.datatypes.loadTypedValue(value: Any, typ: Type) → Any

Load a value with the given type.

Parameters:

• value – A value.

• typ – The type of the parsed value.

Returns:

The value parsed with the given type.

class ecom.datatypes.StructTypeMeta

Bases: type

Metaclass for the StructType.

__iter__() → Iterator[Tuple[str, TypeInfo]]

Iterate over all children of the struct.

Returns:

A list of child names and child type infos.

__getitem__(item)

Get the type info for a child of the struct.

Parameters:

item – The name of the child.

Returns:

The type info for that child.

Raises:

AttributeError – If the struct does not have a child with that name.

__contains__(childName: str) → bool

Whether this struct contains a child element with the given name.

Parameters:

childName – The name of a child element.

Returns:

Whether the struct contains a child element with that name.

__call__(value: Union[str, Dict, Iterable[Iterable], None] = None, childrenTypes: Optional[Dict[str, TypeInfo]] = None, documentation: Optional[str] = None, **kwargs)

Create a new struct type.

Parameters:

• value – The name of the struct typ.

• childrenTypes – A mapping of children names and their types for the struct type.

• documentation – Documentation for the new type.

Returns:

The new struct type.

__eq__(o: object) → bool

Return self==value.

__hash__() → int

Return hash(self).

offsetOf(database: database.CommunicationDatabase, name: str) → int

Calculate the offset of the child element with the given name.

Parameters:

• database – A communication database.

• name – The name of the child element whose offset should be calculated.

Returns:

The offset of the child element in bytes.

class ecom.datatypes.StructType

Bases: dict

Represents a C struct. Can be iterated over to get the struct members.

ecom.datatypes.T

ecom.datatypes.structField(typ: Union[str, TypeInfo, Callable[[database.CommunicationDatabase], TypeInfo], None] = None, name: Optional[str] = None, **kwargs) → dataclasses.Field

Declare a new struct dataclass field. This is a wrapper around the dataclasses.field() function.

See:

dataclasses.field()

See:

ecom.datatypes.structDataclass()

Parameters:

• typ – The type of this field or a callable that given a communication database resolves the type of this field. This is required unless the field replaces a field of another structure, in which case the type is inferred from the other field.

• name – The name of this field. If omitted, the name of dataclass field is used.

• kwargs – Additional arguments to the dataclasses.field() function.

Returns:

A struct dataclass field.

ecom.datatypes.isStructField(childField: dataclasses.Field) → bool

Check whether the given field is a struct field created with ecom.datatypes.structField().

Parameters:

childField – The field to check.

Returns:

Whether the field is a struct field.

ecom.datatypes.getStructFieldName(childField: dataclasses.field) → str

Get the name of the element in the struct of a struct field. This can be different from the dataclass field name.

Raises:

KeyError – if the field is not a struct field.

Parameters:

childField – The struct field to get the name of.

Returns:

The field name of the struct field.

ecom.datatypes.getStructFieldType(childField: dataclasses.field, database: database.CommunicationDatabase) → Optional[TypeInfo]

Get the type of the struct field or None, if the struct field does not define its type.

Raises:

KeyError – if the field is not a struct field.

Parameters:

• childField – The struct field to get the type of.

• database – A communication database to lookup type info.

Returns:

The type information about the struct field type or None.

ecom.datatypes.structDataclass(database: database.CommunicationDatabase, replaceType: Union[str, bool] = False)

A decorator for a class that inherits from StructType that allows it to act as a dataclass. Members can be defined as structFields, to declare their type. The resulting class is a dataclass.

The field values can be given as a dict, just like a regular StructType:

floatTypeInfo = TypeInfo.lookupBaseType(TypeInfo.BaseType.FLOAT)

@structDataclass(database)
class Quaternion(StructType):
    x: float = structField(typ=floatTypeInfo)
    y: float = structField(typ=floatTypeInfo)
    z: float = structField(typ=floatTypeInfo)
    w: float = structField(typ=floatTypeInfo)

value = Quaternion({'x': 1, 'y': 2, 'z': 3, 'w': 4})
print(value.x)  # -> 1

The field values can also be given as keyword arguments:

Quaternion(x=1, y=2, z=3, w=4)

Alternatively, the field values can be given as a mixture of both methods:

@structDataclass(database)
class Quaternion(StructType):
    x: float = structField(typ=floatTypeInfo)
    y: float = structField(typ=floatTypeInfo)
    z: float = structField(typ=floatTypeInfo)
    w: float = structField(typ=floatTypeInfo)
    other = 5.0

Quaternion({'x': 1, 'y': 2, 'z': 3, 'w': 4}, other=6.0)

A structDataclass can also replace an existing struct type in the database. If replaceType is set to True, the class will replace a struct with the same name as the class. If replaceType is a string, the class will replace a struct by that name. In both cases, the struct have the same fields as the replacing struct. The fields don’t need to be explicitly typed, they will inherit their type from their respective field in the replacing struct:

@structDataclass(database, replace=True)
class Quaternion(StructType):
    x: float
    y: float
    z: float
    w: float

Parameters:

• database – A communication database.

• replaceType – If True, replace a type in the database with the same class name. If a string, replace a type with that name.

Returns:

The struct dataclass.

exception ecom.datatypes.DynamicSizeError(sizeMember: str)

Bases: RuntimeError

An operation was requested that required a known size, but the size must be read dynamically from the parent struct.

property sizeMember: str

Returns:

The name of the member that must be read to get the size.

class ecom.datatypes.ArrayTypeMeta

Bases: type

Metaclass for the ArrayType.

__len__() → int

Returns:

The length of the array.

Raises:

DynamicSizeError – If the length must be dynamically read from a member of the parent struct.

__eq__(o: object) → bool

Return self==value.

__hash__() → int

Return hash(self).

getElementTypeInfo() → TypeInfo

Returns:

The type info for all elements.

__call__(value: Union[str, Iterable], typ: Optional[TypeInfo] = None, size: Optional[Union[int, str]] = None, documentation: Optional[str] = None)

Create a new array type.

Parameters:

• value – The name of the array type.

• typ – The type info for the elements of the array.

• size – The size of the array or the name of the member in the parent struct from which the size can be read.

• documentation – Documentation of the new type.

Returns:

The new array type.

class ecom.datatypes.ArrayType

Bases: list

Represents a C array. Provides the type and constant size of the array.

class ecom.datatypes.EnumTypeMeta

Bases: enum.EnumMeta

Metaclass for Enums that are compatible with C style enums and can be compared.

__eq__(o: object) → bool

Return self==value.

__hash__() → int

Return hash(self).

class ecom.datatypes.EnumType

Bases: int, enum.Enum

Represents a C style enum.

__eq__(o: object) → bool

Return self==value.

__hash__() → Any

Return hash(self).

ecom.datatypes.V

class ecom.datatypes.DefaultValueInfo

Bases: Generic[V]

A default value for a type.

value: V

The default value.

constantName: Optional[str]

The name of the default value as a shared constant.

class ecom.datatypes.TypeInfo

Bases: Generic[V]

Describes a data type.

class BaseType

Bases: enum.StrEnum

A base type that can be used in the communication database.

INT8 = 'int8'

This is the mapping of the C type for small numbers.

UINT8 = 'uint8'

This is the mapping of the C type for small unsigned numbers.

BOOL = 'bool'

This is a type, that has only two values: True and False.

INT16 = 'int16'

This is the mapping of the C type for small numbers.

UINT16 = 'uint16'

This is the mapping of the C type for small unsigned numbers.

INT32 = 'int32'

This is the mapping of the C type for numbers.

UINT32 = 'uint32'

This is the mapping of the C type for unsigned numbers.

INT64 = 'int64'

This is the mapping of the C type for large numbers.

UINT64 = 'uint64'

This is the mapping of the C type for large unsigned numbers.

FLOAT = 'float'

A type for small floating point values.

WARNING: This type does not have a standard size in C.

If the size is not 4 bytes for a platform, the generated code will not compile.

DOUBLE = 'double'

A type for larger floating point values with higher precision.

WARNING: This type does not have a standard size in C.

If the size is not 8 bytes for a platform, the generated code will not compile.

CHAR = 'char'

This type represents a character. It is usually used as an array to represent a string.

BYTES = 'bytes'

This type is similar to the char type, but it is used to represent a byte.

type: Type[V]

The Python type representing the type.

name: str

The name of the type.

baseTypeName: Optional[str]

The name of the base type.

description: Optional[str]

A description of the type.

default: Optional[DefaultValueInfo[V]]

The default value of the type.

getBaseType(database: database.CommunicationDatabase) → BaseType

Parameters:

database – A database of all known types.

Returns:

The base type name of this type.

getSize(database: database.CommunicationDatabase) → int

Parameters:

database – A database of all known types.

Returns:

The size of this type in bytes.

getFormat(database: database.CommunicationDatabase, values: Optional[Dict[str, Any]] = None) → str

Parameters:

• database – A database of all known types.

• values – An optional dictionary of other values on which the format might depend on. For example, this could include a size member for a dynamically sized list.

Returns:

The format string of this type.

getFormats(database: database.CommunicationDatabase) → List[str]

Get the format strings for this type. A type that consists of multiple subtypes will yield a concatenated format string. If a type is dynamically sized, a new format string is started that can be formatted with the parsed values from the previous format string to fill the required size information.

Parameters:

database – The communication database.

Returns:

The format strings.

getMinNumericValue(database: database.CommunicationDatabase) → Union[int, float]

Get the minimum number that this type can represent.

Raises:

TypeError – if the type is not numeric.

Parameters:

database – A communication database.

Returns:

The minimum value of this type.

getMaxNumericValue(database: database.CommunicationDatabase) → Union[int, float]

Get the maximum number that this type can represent.

Raises:

TypeError – if the type is not numeric.

Parameters:

database – A communication database.

Returns:

The maximum value of this type.

classmethod lookupBaseType(name: BaseType) → TypeInfo

Find a base type by its name.

Parameters:

name – The name of the base type.

Returns:

The TypeInfo of the base type.

copyWithType(typ: Type[V]) → TypeInfo[V]

Copy this TypeInfo but replace the type with the given new type.

Parameters:

typ – The new type that this type info should contain.

Returns:

The copied type info with the new type.