odxtools 9.3.0__py3-none-any.whl → 9.4.0__py3-none-any.whl

odxtools/diagvariable.py

@@ -9,11 +9,13 @@ from .commrelation import CommRelation
 from .element import IdentifiableElement
 from .exceptions import odxrequire
 from .nameditemlist import NamedItemList
-from .odxlink import OdxDocFragment, OdxLinkDatabase, OdxLinkId, OdxLinkRef
+from .odxlink import OdxDocFragment, OdxLinkDatabase, OdxLinkId, OdxLinkRef, resolve_snref
 from .odxtypes import odxstr_to_bool
 from .snrefcontext import SnRefContext
 from .specialdatagroup import SpecialDataGroup
 from .swvariable import SwVariable
+from .table import Table
+from .tablerow import TableRow
 from .utils import dataclass_fields_asdict
 from .variablegroup import VariableGroup
 
@@ -32,15 +34,30 @@ class DiagVariable(IdentifiableElement):
     """
 
     admin_data: Optional[AdminData]
-    variable_group_ref: OdxLinkRef
+    variable_group_ref: Optional[OdxLinkRef]
     sw_variables: List[SwVariable]
+
+    # a diag variable must specify either COMM-RELATIONS or a
+    # reference to a table row
     comm_relations: List[CommRelation]
-    #snref_to_tablerow: Optional[SnrefToTableRow] # TODO
+
+    # these are nested inside the SNREF-TO-TABLEROW tag
+    table_snref: Optional[str]
+    table_row_snref: Optional[str]
+
     sdgs: List[SpecialDataGroup]
     is_read_before_write_raw: Optional[bool]
 
     @property
-    def variable_group(self) -> VariableGroup:
+    def table(self) -> Optional[Table]:
+        return self._table
+
+    @property
+    def table_row(self) -> Optional[TableRow]:
+        return self._table_row
+
+    @property
+    def variable_group(self) -> Optional[VariableGroup]:
         return self._variable_group
 
     @property
@@ -52,8 +69,7 @@ class DiagVariable(IdentifiableElement):
         kwargs = dataclass_fields_asdict(IdentifiableElement.from_et(et_element, doc_frags))
 
         admin_data = AdminData.from_et(et_element.find("ADMIN-DATA"), doc_frags)
-        variable_group_ref = odxrequire(
-            OdxLinkRef.from_et(et_element.find("VARIABLE-GROUP-REF"), doc_frags))
+        variable_group_ref = OdxLinkRef.from_et(et_element.find("VARIABLE-GROUP-REF"), doc_frags)
         sw_variables = NamedItemList([
             SwVariable.from_et(swv_elem, doc_frags)
             for swv_elem in et_element.iterfind("SW-VARIABLES/SW-VARIABLE")
@@ -62,6 +78,16 @@ class DiagVariable(IdentifiableElement):
             CommRelation.from_et(cr_elem, doc_frags)
             for cr_elem in et_element.iterfind("COMM-RELATIONS/COMM-RELATION")
         ]
+
+        table_snref = None
+        table_row_snref = None
+        if (snref_to_tablerow_elem := et_element.find("SNREF-TO-TABLEROW")) is not None:
+            table_snref_elem = odxrequire(snref_to_tablerow_elem.find("TABLE-SNREF"))
+            table_snref = odxrequire(table_snref_elem.attrib.get("SHORT-NAME"))
+
+            table_row_snref_elem = odxrequire(snref_to_tablerow_elem.find("TABLE-ROW-SNREF"))
+            table_row_snref = odxrequire(table_row_snref_elem.attrib.get("SHORT-NAME"))
+
         sdgs = [
             SpecialDataGroup.from_et(sdge, doc_frags) for sdge in et_element.iterfind("SDGS/SDG")
         ]
@@ -72,6 +98,8 @@ class DiagVariable(IdentifiableElement):
             variable_group_ref=variable_group_ref,
             sw_variables=sw_variables,
             comm_relations=comm_relations,
+            table_snref=table_snref,
+            table_row_snref=table_row_snref,
             sdgs=sdgs,
             is_read_before_write_raw=is_read_before_write_raw,
             **kwargs)
@@ -91,7 +119,9 @@ class DiagVariable(IdentifiableElement):
         return result
 
     def _resolve_odxlinks(self, odxlinks: OdxLinkDatabase) -> None:
-        self._variable_group = odxlinks.resolve(self.variable_group_ref, VariableGroup)
+        self._variable_group = None
+        if self.variable_group_ref is not None:
+            self._variable_group = odxlinks.resolve(self.variable_group_ref, VariableGroup)
 
         if self.admin_data is not None:
             self.admin_data._resolve_odxlinks(odxlinks)
@@ -111,3 +141,11 @@ class DiagVariable(IdentifiableElement):
 
         for cr in self.comm_relations:
             cr._resolve_snrefs(context)
+
+        self._table = None
+        self._table_row = None
+        if self.table_snref is not None:
+            ddds = odxrequire(context.diag_layer).diag_data_dictionary_spec
+            self._table = resolve_snref(self.table_snref, ddds.tables, Table)
+            self._table_row = resolve_snref(
+                odxrequire(self.table_row_snref), self._table.table_rows, TableRow)

odxtools/encodestate.py

@@ -3,6 +3,7 @@ import warnings
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Dict, List, Optional, SupportsBytes, Tuple
 
+from .encoding import Encoding, get_string_encoding
 from .exceptions import EncodeError, OdxWarning, odxassert, odxraise
 from .odxtypes import AtomicOdxType, DataType, ParameterValue
 
@@ -86,6 +87,7 @@ class EncodeState:
         internal_value: AtomicOdxType,
         bit_length: int,
         base_data_type: DataType,
+        base_type_encoding: Optional[Encoding],
         is_highlow_byte_order: bool,
         used_mask: Optional[bytes],
     ) -> None:
@@ -93,63 +95,139 @@ class EncodeState:
 
         raw_value: AtomicOdxType
 
-        # Check that bytes and strings actually fit into the bit length
+        # Deal with raw byte fields, ...
         if base_data_type == DataType.A_BYTEFIELD:
             if not isinstance(internal_value, (bytes, bytearray, SupportsBytes)):
-                odxraise()
-            if 8 * len(internal_value) > bit_length:
-                raise EncodeError(f"The bytefield {internal_value.hex()} is too large "
-                                  f"({len(internal_value)} bytes)."
-                                  f" The maximum length is {bit_length//8}.")
-            raw_value = bytes(internal_value)
-        elif base_data_type == DataType.A_ASCIISTRING:
-            if not isinstance(internal_value, str):
-                odxraise()
+                odxraise(f"{internal_value!r} is not a bytefield", EncodeError)
+                return
 
-            # The spec says ASCII, meaning only byte values 0-127.
-            # But in practice, vendors use iso-8859-1, aka latin-1
-            # reason being iso-8859-1 never fails since it has a valid
-            # character mapping for every possible byte sequence.
-            raw_value = internal_value.encode("iso-8859-1")
+            odxassert(
+                base_type_encoding in (None, Encoding.NONE, Encoding.BCD_P, Encoding.BCD_UP),
+                f"Illegal encoding '{base_type_encoding}' for A_BYTEFIELD")
+
+            # note that we do not ensure that BCD-encoded byte fields
+            # only represent "legal" values
+            raw_value = bytes(internal_value)
 
             if 8 * len(raw_value) > bit_length:
-                raise EncodeError(f"The string {repr(internal_value)} is too large."
-                                  f" The maximum number of characters is {bit_length//8}.")
-        elif base_data_type == DataType.A_UTF8STRING:
+                odxraise(
+                    f"The value '{internal_value!r}' cannot be encoded using "
+                    f"{bit_length} bits.", EncodeError)
+                raw_value = raw_value[0:bit_length // 8]
+
+        # ... string types, ...
+        elif base_data_type in (DataType.A_UTF8STRING, DataType.A_ASCIISTRING,
+                                DataType.A_UNICODE2STRING):
             if not isinstance(internal_value, str):
-                odxraise()
+                odxraise(f"The internal value '{internal_value!r}' is not a string", EncodeError)
+                internal_value = str(internal_value)
 
-            raw_value = internal_value.encode("utf-8")
+            str_encoding = get_string_encoding(base_data_type, base_type_encoding,
+                                               is_highlow_byte_order)
+            if str_encoding is not None:
+                raw_value = internal_value.encode(str_encoding)
+            else:
+                raw_value = b""
 
             if 8 * len(raw_value) > bit_length:
-                raise EncodeError(f"The string {repr(internal_value)} is too large."
-                                  f" The maximum number of bytes is {bit_length//8}.")
+                odxraise(
+                    f"The value '{internal_value!r}' cannot be encoded using "
+                    f"{bit_length} bits.", EncodeError)
+                raw_value = raw_value[0:bit_length // 8]
 
-        elif base_data_type == DataType.A_UNICODE2STRING:
-            if not isinstance(internal_value, str):
-                odxraise()
+        # ... signed integers, ...
+        elif base_data_type == DataType.A_INT32:
+            if not isinstance(internal_value, int):
+                odxraise(
+                    f"Internal value must be of integer type, not {type(internal_value).__name__}",
+                    EncodeError)
+                internal_value = int(internal_value)
+
+            if base_type_encoding == Encoding.ONEC:
+                # one-complement
+                if internal_value >= 0:
+                    raw_value = internal_value
+                else:
+                    mask = (1 << bit_length) - 1
+                    raw_value = mask + internal_value
+            elif base_type_encoding in (None, Encoding.TWOC):
+                # two-complement
+                if internal_value >= 0:
+                    raw_value = internal_value
+                else:
+                    mask = (1 << bit_length) - 1
+                    raw_value = mask + internal_value + 1
+            elif base_type_encoding == Encoding.SM:
+                # sign-magnitude
+                if internal_value >= 0:
+                    raw_value = internal_value
+                else:
+                    raw_value = (1 << (bit_length - 1)) + abs(internal_value)
+            else:
+                odxraise(
+                    f"Illegal encoding ({base_type_encoding and base_type_encoding.value}) specified for "
+                    f"{base_data_type.value}")
 
-            text_encoding = "utf-16-be" if is_highlow_byte_order else "utf-16-le"
-            raw_value = internal_value.encode(text_encoding)
+                if base_type_encoding == Encoding.BCD_P:
+                    raw_value = self.__encode_bcd_p(abs(internal_value))
+                elif base_type_encoding == Encoding.BCD_UP:
+                    raw_value = self.__encode_bcd_up(abs(internal_value))
+                else:
+                    raw_value = internal_value
 
-            if 8 * len(raw_value) > bit_length:
-                raise EncodeError(f"The string {repr(internal_value)} is too large."
-                                  f" The maximum number of characters is {bit_length//16}.")
+            if raw_value.bit_length() > bit_length:
+                odxraise(
+                    f"The value '{internal_value!r}' cannot be encoded using "
+                    f"{bit_length} bits.", EncodeError)
+                raw_value &= (1 << bit_length) - 1
+
+        # ... unsigned integers, ...
+        elif base_data_type == DataType.A_UINT32:
+            if not isinstance(internal_value, int) or internal_value < 0:
+                odxraise(f"Internal value must be a positive integer, not {internal_value!r}")
+                internal_value = abs(int(internal_value))
+
+            if base_type_encoding == Encoding.BCD_P:
+                # packed BCD
+                raw_value = self.__encode_bcd_p(internal_value)
+            elif base_type_encoding == Encoding.BCD_UP:
+                # unpacked BCD
+                raw_value = self.__encode_bcd_up(internal_value)
+            elif base_type_encoding in (None, Encoding.NONE):
+                # no encoding
+                raw_value = internal_value
+            else:
+                odxraise(f"Illegal encoding ({base_type_encoding}) specified for "
+                         f"{base_data_type.value}")
+
+                raw_value = internal_value
+
+            if raw_value.bit_length() > bit_length:
+                odxraise(
+                    f"The value '{internal_value!r}' cannot be encoded using "
+                    f"{bit_length} bits.", EncodeError)
+                raw_value &= (1 << bit_length) - 1
+
+        # ... and others (floating point values)
         else:
-            raw_value = internal_value
+            odxassert(base_data_type in (DataType.A_FLOAT32, DataType.A_FLOAT64))
+            odxassert(base_type_encoding in (None, Encoding.NONE))
 
-        # If the bit length is zero, return empty bytes
+            if base_data_type == DataType.A_FLOAT32 and bit_length != 32:
+                odxraise(f"Illegal bit length for a float32 object ({bit_length})")
+                bit_length = 32
+            elif base_data_type == DataType.A_FLOAT64 and bit_length != 64:
+                odxraise(f"Illegal bit length for a float64 object ({bit_length})")
+                bit_length = 64
+
+            raw_value = float(internal_value)
+
+        # If the bit length is zero, encode an empty value
         if bit_length == 0:
-            if (base_data_type.value in [
-                    DataType.A_INT32, DataType.A_UINT32, DataType.A_FLOAT32, DataType.A_FLOAT64
-            ] and base_data_type.value != 0):
-                odxraise(
-                    f"The number {repr(internal_value)} cannot be encoded into {bit_length} bits.",
-                    EncodeError)
             self.emplace_bytes(b'')
             return
 
-        char = base_data_type.bitstruct_format_letter
+        format_char = base_data_type.bitstruct_format_letter
         padding = (8 - ((bit_length + self.cursor_bit_position) % 8)) % 8
         odxassert((0 <= padding and padding < 8 and
                    (padding + bit_length + self.cursor_bit_position) % 8 == 0),
@@ -157,19 +235,17 @@ class EncodeState:
         left_pad = f"p{padding}" if padding > 0 else ""
 
         # actually encode the value
-        coded = bitstruct.pack(f"{left_pad}{char}{bit_length}", raw_value)
+        coded = bitstruct.pack(f"{left_pad}{format_char}{bit_length}", raw_value)
 
         # create the raw mask of used bits for numeric objects
         used_mask_raw = used_mask
-        if base_data_type in [DataType.A_INT32, DataType.A_UINT32
-                             ] and (self.cursor_bit_position != 0 or
-                                    (self.cursor_bit_position + bit_length) % 8 != 0):
-            if used_mask is None:
-                tmp = (1 << bit_length) - 1
-            else:
-                tmp = int.from_bytes(used_mask, "big")
-            tmp <<= self.cursor_bit_position
 
+        if used_mask_raw is None:
+            used_mask_raw = ((1 << bit_length) - 1).to_bytes((bit_length + 7) // 8, "big")
+
+        if self.cursor_bit_position != 0:
+            tmp = int.from_bytes(used_mask_raw, "big")
+            tmp <<= self.cursor_bit_position
             used_mask_raw = tmp.to_bytes((self.cursor_bit_position + bit_length + 7) // 8, "big")
 
         # apply byte order to numeric objects
@@ -177,9 +253,7 @@ class EncodeState:
                 DataType.A_INT32, DataType.A_UINT32, DataType.A_FLOAT32, DataType.A_FLOAT64
         ]:
             coded = coded[::-1]
-
-            if used_mask_raw is not None:
-                used_mask_raw = used_mask_raw[::-1]
+            used_mask_raw = used_mask_raw[::-1]
 
         self.cursor_bit_position = 0
         self.emplace_bytes(coded, obj_used_mask=used_mask_raw)
@@ -233,3 +307,25 @@ class EncodeState:
                 self.used_mask[pos + i] |= obj_used_mask[i]
 
         self.cursor_byte_position += len(new_data)
+
+    @staticmethod
+    def __encode_bcd_p(value: int) -> int:
+        result = 0
+        shift = 0
+        while value > 0:
+            result |= (value % 10) << shift
+            shift += 4
+            value //= 10
+
+        return result
+
+    @staticmethod
+    def __encode_bcd_up(value: int) -> int:
+        result = 0
+        shift = 0
+        while value > 0:
+            result |= (value % 10) << shift
+            shift += 8
+            value //= 10
+
+        return result

odxtools/encoding.py

@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: MIT
+from enum import Enum
+from typing import Optional
+
+from .exceptions import odxraise
+from .odxtypes import DataType
+
+
+class Encoding(Enum):
+    BCD_P = "BCD-P"
+    BCD_UP = "BCD-UP"
+
+    ONEC = "1C"
+    TWOC = "2C"
+    SM = "SM"
+
+    UTF8 = "UTF-8"
+    UCS2 = "UCS-2"
+    ISO_8859_1 = "ISO-8859-1"
+    ISO_8859_2 = "ISO-8859-2"
+    WINDOWS_1252 = "WINDOWS-1252"
+
+    NONE = "NONE"
+
+
+def get_string_encoding(base_data_type: DataType, base_type_encoding: Optional[Encoding],
+                        is_highlow_byte_order: bool) -> Optional[str]:
+    """If the encoding is for a string, return the value for
+    `str.encode()`/`str.decode()` to convert the string object
+    to/from a byte array
+    """
+
+    # note that the spec disallows certain combinations of
+    # base_data_type and encoding (e.g., A_ASCIISTRING encoded
+    # using UTF-8). Since in python3 strings are always
+    # capable of the full unicode character set, odxtools
+    # ignores these restrictions...
+    if base_type_encoding == Encoding.UTF8 or (base_data_type == DataType.A_UTF8STRING and
+                                               base_type_encoding is None):
+        return "utf-8"
+    elif base_type_encoding == Encoding.UCS2 or (base_data_type == DataType.A_UNICODE2STRING and
+                                                 base_type_encoding is None):
+        return "utf-16-be" if is_highlow_byte_order else "utf-16-le"
+    elif base_type_encoding == Encoding.ISO_8859_1 or (base_data_type == DataType.A_ASCIISTRING and
+                                                       base_type_encoding is None):
+        return "iso-8859-1"
+    elif base_type_encoding == Encoding.ISO_8859_2:
+        return "iso-8859-2"
+    elif base_type_encoding == Encoding.WINDOWS_1252:
+        return "cp1252"
+    else:
+        odxraise(f"Specified illegal encoding {base_type_encoding} for {base_data_type.value} "
+                 f"string object")
+        return "iso-8859-1"
+
+    return None

odxtools/functionalclass.py

@@ -1,8 +1,9 @@
 # SPDX-License-Identifier: MIT
 from dataclasses import dataclass
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Optional
 from xml.etree import ElementTree
 
+from .admindata import AdminData
 from .element import IdentifiableElement
 from .odxlink import OdxDocFragment, OdxLinkDatabase, OdxLinkId
 from .snrefcontext import SnRefContext
@@ -15,13 +16,17 @@ class FunctionalClass(IdentifiableElement):
     Corresponds to FUNCT-CLASS.
     """
 
+    admin_data: Optional[AdminData]
+
     @staticmethod
     def from_et(et_element: ElementTree.Element,
                 doc_frags: List[OdxDocFragment]) -> "FunctionalClass":
 
         kwargs = dataclass_fields_asdict(IdentifiableElement.from_et(et_element, doc_frags))
 
-        return FunctionalClass(**kwargs)
+        admin_data = AdminData.from_et(et_element.find("ADMIN-DATA"), doc_frags)
+
+        return FunctionalClass(admin_data=admin_data, **kwargs)
 
     def _build_odxlinks(self) -> Dict[OdxLinkId, Any]:
         return {self.odx_id: self}

odxtools/inputparam.py

@@ -3,6 +3,8 @@ from dataclasses import dataclass
 from typing import Any, Dict, List, Optional
 from xml.etree import ElementTree
 
+from deprecation import deprecated
+
 from .dopbase import DopBase
 from .element import NamedElement
 from .exceptions import odxrequire
@@ -38,12 +40,16 @@ class InputParam(NamedElement):
         return {}
 
     def _resolve_odxlinks(self, odxlinks: OdxLinkDatabase) -> None:
-        self._dop_base = odxlinks.resolve(self.dop_base_ref, DopBase)
+        self._dop = odxlinks.resolve(self.dop_base_ref, DopBase)
 
     def _resolve_snrefs(self, context: SnRefContext) -> None:
         pass
 
     @property
-    def dop_base(self) -> DopBase:
+    def dop(self) -> DopBase:
         """The data object property describing this parameter."""
-        return self._dop_base
+        return self._dop
+
+    @deprecated(details="use .dop")  # type: ignore[misc]
+    def dop_base(self) -> DopBase:
+        return self._dop

odxtools/leadinglengthinfotype.py

@@ -72,6 +72,7 @@ class LeadingLengthInfoType(DiagCodedType):
             used_mask=None,
             bit_length=self.bit_length,
             base_data_type=DataType.A_UINT32,
+            base_type_encoding=None,
             is_highlow_byte_order=self.is_highlow_byte_order,
         )
 
@@ -80,6 +81,7 @@ class LeadingLengthInfoType(DiagCodedType):
             used_mask=None,
             bit_length=8 * byte_length,
             base_data_type=self.base_data_type,
+            base_type_encoding=None,
             is_highlow_byte_order=self.is_highlow_byte_order,
         )
 
@@ -90,6 +92,7 @@ class LeadingLengthInfoType(DiagCodedType):
         byte_length = decode_state.extract_atomic_value(
             bit_length=self.bit_length,
             base_data_type=DataType.A_UINT32,  # length is an integer
+            base_type_encoding=None,
             is_highlow_byte_order=self.is_highlow_byte_order,
         )
 
@@ -102,6 +105,7 @@ class LeadingLengthInfoType(DiagCodedType):
         value = decode_state.extract_atomic_value(
             bit_length=8 * byte_length,
             base_data_type=self.base_data_type,
+            base_type_encoding=None,
             is_highlow_byte_order=self.is_highlow_byte_order,
         )