odxtools 8.3.4__py3-none-any.whl → 9.0.0__py3-none-any.whl

odxtools/cli/compare.py

@@ -5,8 +5,9 @@ import argparse
 import os
 from typing import Any, Dict, List, Optional, Set, Union, cast
 
-from rich import print
-from tabulate import tabulate  # TODO: switch to rich tables
+from rich import print as rich_print
+from rich.padding import Padding as RichPadding
+from rich.table import Table as RichTable
 
 from ..database import Database
 from ..diaglayers.diaglayer import DiagLayer
@@ -46,11 +47,14 @@ class Display:
     # class with variables and functions to display the result of the comparison
 
     # TODO
-    # Idea: results as json export
-    # - write results of comparison in json structure
-    # - use odxlinks to refer to dignostic services / objects if changes have already been detected (e.g. in another ecu variant / diagnostic layer)
-
-    # print all information about parameter properties (request, pos. response & neg. response parameters) for changed diagnostic services
+    # - Idea: results as json export
+    #  - write results of comparison in json structure
+    #  - use odxlinks to refer to dignostic services / objects if
+    #    changes have already been detected (e.g. in another ecu
+    #    variant / diagnostic layer)
+    # - print all information about parameter properties (request,
+    #   pos. response & neg. response parameters) for changed diagnostic
+    #   services
     param_detailed: bool
     obj_detailed: bool
 
@@ -62,46 +66,45 @@ class Display:
         if service_dict["new_services"] or service_dict["deleted_services"] or service_dict[
                 "changed_name_of_service"][0] or service_dict["changed_parameters_of_service"][0]:
             assert isinstance(service_dict["diag_layer"], str)
-            print()
-            print(
+            rich_print()
+            rich_print(
                 f"Changed diagnostic services for diagnostic layer '{service_dict['diag_layer']}' ({service_dict['diag_layer_type']}):"
             )
         if service_dict["new_services"]:
             assert isinstance(service_dict["new_services"], List)
-            print()
-            print(" [blue]New services[/blue]")
-            table = extract_service_tabulation_data(
-                service_dict["new_services"])  # type: ignore[arg-type]
-            print(tabulate(table, headers="keys", tablefmt="presto"))
+            rich_print()
+            rich_print(" [blue]New services[/blue]")
+            rich_print(extract_service_tabulation_data(
+                service_dict["new_services"]))  # type: ignore[arg-type]
         if service_dict["deleted_services"]:
             assert isinstance(service_dict["deleted_services"], List)
-            print()
-            print(" [blue]Deleted services[/blue]")
-            table = extract_service_tabulation_data(
-                service_dict["deleted_services"])  # type: ignore[arg-type]
-            print(tabulate(table, headers="keys", tablefmt="presto"))
+            rich_print()
+            rich_print(" [blue]Deleted services[/blue]")
+            rich_print(extract_service_tabulation_data(
+                service_dict["deleted_services"]))  # type: ignore[arg-type]
         if service_dict["changed_name_of_service"][0]:
-            print()
-            print(" [blue]Renamed services[/blue]")
-            table = extract_service_tabulation_data(
-                service_dict["changed_name_of_service"][0])  # type: ignore[arg-type]
-            table["Old service name"] = service_dict["changed_name_of_service"][1]
-            print(tabulate(table, headers="keys", tablefmt="presto"))
+            rich_print()
+            rich_print(" [blue]Renamed services[/blue]")
+            rich_print(extract_service_tabulation_data(
+                service_dict["changed_name_of_service"][0]))  # type: ignore[arg-type]
         if service_dict["changed_parameters_of_service"][0]:
-            print()
-            print(" [blue]Services with parameter changes[/blue]")
+            rich_print()
+            rich_print(" [blue]Services with parameter changes[/blue]")
             # create table with information about services with parameter changes
+            changed_param_column = [
+                str(x) for x in service_dict["changed_parameters_of_service"][
+                    1]  # type: ignore[union-attr]
+            ]
             table = extract_service_tabulation_data(
-                service_dict["changed_parameters_of_service"][0])  # type: ignore[arg-type]
-            # add information about changed parameters
-            table["Changed parameters"] = service_dict["changed_parameters_of_service"][1]
-            print(tabulate(table, headers="keys", tablefmt="presto"))
+                service_dict["changed_parameters_of_service"][0],  # type: ignore[arg-type]
+                additional_columns=[("Changed Parameters", changed_param_column)])
+            rich_print(table)
 
             for service_idx, service in enumerate(
                     service_dict["changed_parameters_of_service"][0]):  # type: ignore[arg-type]
                 assert isinstance(service, DiagService)
-                print()
-                print(
+                rich_print()
+                rich_print(
                     f"  Detailed changes of diagnostic service [u cyan]{service.short_name}[/u cyan]"
                 )
                 #   detailed_info in [infotext1, dict1, infotext2, dict2, ...]
@@ -110,10 +113,22 @@ class Display:
                     service_dict["changed_parameters_of_service"])[2][service_idx]
                 for detailed_info in info_list:
                     if isinstance(detailed_info, str):
-                        print()
-                        print(detailed_info)
+                        rich_print()
+                        rich_print(detailed_info)
                     elif isinstance(detailed_info, dict):
-                        print(tabulate(detailed_info, headers="keys", tablefmt="presto"))
+                        table = RichTable(
+                            show_header=True,
+                            header_style="bold cyan",
+                            border_style="blue",
+                            show_lines=True)
+                        for header in detailed_info:
+                            table.add_column(header)
+                        rows = zip(*detailed_info.values())
+                        for row in rows:
+                            table.add_row(*map(str, row))
+
+                        rich_print(RichPadding(table, pad=(0, 0, 0, 4)))
+                        rich_print()
                 if self.param_detailed:
                     # print all parameter details of diagnostic service
                     print_service_parameters(service, allow_unknown_bit_lengths=True)
@@ -124,16 +139,18 @@ class Display:
         # diagnostic layers
         if changes_variants["new_diagnostic_layers"] or changes_variants[
                 "deleted_diagnostic_layers"]:
-            print()
-            print("[bright_blue]Changed diagnostic layers[/bright_blue]: ")
-            print(" New diagnostic layers: ")
+            rich_print()
+            rich_print("[bright_blue]Changed diagnostic layers[/bright_blue]: ")
+            rich_print(" New diagnostic layers: ")
             for variant in changes_variants["new_diagnostic_layers"]:
                 assert isinstance(variant, DiagLayer)
-                print(f"  [magenta]{variant.short_name}[/magenta] ({variant.variant_type.value})")
-            print(" Deleted diagnostic layers: ")
+                rich_print(
+                    f"  [magenta]{variant.short_name}[/magenta] ({variant.variant_type.value})")
+            rich_print(" Deleted diagnostic layers: ")
             for variant in changes_variants["deleted_diagnostic_layers"]:
                 assert isinstance(variant, DiagLayer)
-                print(f"  [magenta]{variant.short_name}[/magenta] ({variant.variant_type.value})")
+                rich_print(
+                    f"  [magenta]{variant.short_name}[/magenta] ({variant.variant_type.value})")
 
         # diagnostic services
         for _, value in changes_variants.items():
@@ -275,8 +292,8 @@ class Comparison(Display):
                     if res1_idx == res2_idx:
                         # find changed request parameter properties
                         table = self.compare_parameters(param1, param2)
-                        infotext = (f"   Properties of request parameter '{param2.short_name}'"
-                                    f" have changed\n")
+                        infotext = (f"   Properties of request parameter '{param2.short_name}' "
+                                    f"that have changed:\n")
                         # array index starts with 0 -> param[0] is 1. service parameter
 
                         if table["Property"]:
@@ -311,8 +328,8 @@ class Comparison(Display):
                                         # find changed positive response parameter properties
                                         table = self.compare_parameters(param1, param2)
                                         infotext = (
-                                            f"   Properties of positive response parameter '{param2.short_name}'"
-                                            f"have changed\n")
+                                            f"   Properties of positive response parameter '{param2.short_name}' that "
+                                            f"have changed:\n")
                                         # array index starts with 0 -> param[0] is first service parameter
 
                                         if table["Property"]:
@@ -354,7 +371,7 @@ class Comparison(Display):
                                     if param1_idx == param2_idx:
                                         # find changed negative response parameter properties
                                         table = self.compare_parameters(param1, param2)
-                                        infotext = f"   Properties of response parameter '{param2.short_name}' have changed\n"
+                                        infotext = f"   Properties of response parameter '{param2.short_name}' that have changed:\n"
                                         # array index starts with 0 -> param[0] is 1. service parameter
 
                                         if table["Property"]:
@@ -622,7 +639,7 @@ def run(args: argparse.Namespace) -> None:
 
         for name in args.variants:
             if name not in task.diagnostic_layer_names:
-                print(f"The variant '{name}' could not be found!")
+                rich_print(f"The variant '{name}' could not be found!")
                 return
 
         task.db_indicator_1 = 0
@@ -632,19 +649,20 @@ def run(args: argparse.Namespace) -> None:
                 break
             task.db_indicator_2 = db_idx + 1
 
-            print()
-            print(f"Changes in file '{os.path.basename(db_names[0])}'")
-            print(f" (compared to '{os.path.basename(db_names[db_idx + 1])}')")
+            rich_print()
+            rich_print(f"Changes in file '{os.path.basename(db_names[0])}'")
+            rich_print(f" (compared to '{os.path.basename(db_names[db_idx + 1])}')")
 
-            print()
-            print(f"Overview of diagnostic layers (for {os.path.basename(db_names[0])})")
+            rich_print()
+            rich_print(f"Overview of diagnostic layers (for {os.path.basename(db_names[0])})")
             print_dl_metrics([
                 variant for variant in task.databases[0].diag_layers
                 if variant.short_name in task.diagnostic_layer_names
             ])
 
-            print()
-            print(f"Overview of diagnostic layers (for {os.path.basename(db_names[db_idx+1])})")
+            rich_print()
+            rich_print(
+                f"Overview of diagnostic layers (for {os.path.basename(db_names[db_idx+1])})")
             print_dl_metrics([
                 variant for variant in task.databases[db_idx + 1].diag_layers
                 if variant.short_name in task.diagnostic_layer_names
@@ -673,16 +691,17 @@ def run(args: argparse.Namespace) -> None:
                 break
             task.db_indicator_2 = db_idx + 1
 
-            print()
-            print(f"Changes in file '{os.path.basename(db_names[0])}")
-            print(f" (compared to '{os.path.basename(db_names[db_idx + 1])}')")
+            rich_print()
+            rich_print(f"Changes in file '{os.path.basename(db_names[0])}")
+            rich_print(f" (compared to '{os.path.basename(db_names[db_idx + 1])}')")
 
-            print()
-            print(f"Overview of diagnostic layers (for {os.path.basename(db_names[0])})")
+            rich_print()
+            rich_print(f"Overview of diagnostic layers (for {os.path.basename(db_names[0])})")
             print_dl_metrics(list(task.databases[0].diag_layers))
 
-            print()
-            print(f"Overview of diagnostic layers (for {os.path.basename(db_names[db_idx+1])})")
+            rich_print()
+            rich_print(
+                f"Overview of diagnostic layers (for {os.path.basename(db_names[db_idx+1])})")
             print_dl_metrics(list(task.databases[db_idx + 1].diag_layers))
 
             task.print_database_changes(
@@ -704,20 +723,20 @@ def run(args: argparse.Namespace) -> None:
 
         for name in args.variants:
             if name not in task.diagnostic_layer_names:
-                print(f"The variant '{name}' could not be found!")
+                rich_print(f"The variant '{name}' could not be found!")
                 return
 
-        print()
-        print(f"Overview of diagnostic layers: ")
+        rich_print()
+        rich_print(f"Overview of diagnostic layers: ")
         print_dl_metrics(task.diagnostic_layers)
 
         for db_idx, dl in enumerate(task.diagnostic_layers):
             if db_idx + 1 >= len(task.diagnostic_layers):
                 break
 
-            print()
-            print(f"Changes in diagnostic layer '{dl.short_name}' ({dl.variant_type.value})")
-            print(
+            rich_print()
+            rich_print(f"Changes in diagnostic layer '{dl.short_name}' ({dl.variant_type.value})")
+            rich_print(
                 f" (compared to '{task.diagnostic_layers[db_idx + 1].short_name}' ({task.diagnostic_layers[db_idx + 1].variant_type.value}))"
             )
             task.print_dl_changes(
@@ -725,4 +744,4 @@ def run(args: argparse.Namespace) -> None:
 
     else:
         # no databases & no variants specified
-        print("Please specify either a database or variant for a comparison")
+        rich_print("Please specify either a database or variant for a comparison")

odxtools/cli/list.py

@@ -52,7 +52,7 @@ def print_summary(odxdb: Database,
     if diag_layers:
         rich.print("\n")
         rich.print(f"Overview of diagnostic layers: ")
-        print_dl_metrics(diag_layers, print_fn=rich.print)
+        print_dl_metrics(diag_layers)
 
     for dl in diag_layers:
         rich.print("\n")
@@ -93,8 +93,7 @@ def print_summary(odxdb: Database,
                             print_pre_condition_states=print_pre_condition_states,
                             print_state_transitions=print_state_transitions,
                             print_audiences=print_audiences,
-                            allow_unknown_bit_lengths=allow_unknown_bit_lengths,
-                            print_fn=rich.print)
+                            allow_unknown_bit_lengths=allow_unknown_bit_lengths)
                     elif isinstance(service, SingleEcuJob):
                         rich.print(f" Single ECU job: {service.odx_id}")
                     else:

odxtools/codec.py

@@ -0,0 +1,211 @@
+# SPDX-License-Identifier: MIT
+import typing
+from typing import List, Optional, runtime_checkable
+
+from .decodestate import DecodeState
+from .encodestate import EncodeState
+from .exceptions import EncodeError, odxraise
+from .odxtypes import ParameterValue
+from .parameters.codedconstparameter import CodedConstParameter
+from .parameters.matchingrequestparameter import MatchingRequestParameter
+from .parameters.parameter import Parameter
+from .parameters.physicalconstantparameter import PhysicalConstantParameter
+
+
+@runtime_checkable
+class Codec(typing.Protocol):
+    """Any object which can be en- or decoded to be transferred over
+    the wire implements this API.
+    """
+
+    @property
+    def short_name(self) -> str:
+        return ""
+
+    def encode_into_pdu(self, physical_value: Optional[ParameterValue],
+                        encode_state: EncodeState) -> None:
+        ...
+
+    def decode_from_pdu(self, decode_state: DecodeState) -> ParameterValue:
+        ...
+
+    def get_static_bit_length(self) -> Optional[int]:
+        ...
+
+
+@runtime_checkable
+class CompositeCodec(Codec, typing.Protocol):
+    """Any object which can be en- or decoded to be transferred over
+    the wire which is composed of multiple parameter implements this
+    API.
+
+    """
+
+    @property
+    def parameters(self) -> List[Parameter]:
+        return []
+
+    @property
+    def required_parameters(self) -> List[Parameter]:
+        return []
+
+    @property
+    def free_parameters(self) -> List[Parameter]:
+        return []
+
+
+# some helper functions useful for composite codec objects
+def composite_codec_get_static_bit_length(codec: CompositeCodec) -> Optional[int]:
+    """Compute the length of a composite codec object in bits
+
+    This is basically the sum of the lengths of all parameters. If the
+    length of any parameter can only determined at runtime, `None` is
+    returned.
+    """
+
+    cursor = 0
+    byte_length = 0
+    for param in codec.parameters:
+        param_bit_length = param.get_static_bit_length()
+        if param_bit_length is None:
+            # We were not able to calculate a static bit length
+            return None
+        elif param.byte_position is not None:
+            cursor = param.byte_position
+
+        cursor += ((param.bit_position or 0) + param_bit_length + 7) // 8
+        byte_length = max(byte_length, cursor)
+
+    return byte_length * 8
+
+
+def composite_codec_get_required_parameters(codec: CompositeCodec) -> List[Parameter]:
+    """Return the list of parameters which are required to be
+    specified for encoding the composite codec object
+
+    I.e., all free parameters that do not exhibit a default value.
+    """
+    return [p for p in codec.parameters if p.is_required]
+
+
+def composite_codec_get_free_parameters(codec: CompositeCodec) -> List[Parameter]:
+    """Return the list of parameters which can be freely specified by
+    the user when encoding the composite codec object
+
+    This means all required parameters plus parameters that can be
+    omitted because they specify a default.
+    """
+    return [p for p in codec.parameters if p.is_settable]
+
+
+def composite_codec_get_coded_const_prefix(codec: CompositeCodec,
+                                           request_prefix: bytes = b'') -> bytes:
+    encode_state = EncodeState(coded_message=bytearray(), triggering_request=request_prefix)
+
+    for param in codec.parameters:
+        if (isinstance(param, MatchingRequestParameter) and param.request_byte_position < len(request_prefix)) or \
+            isinstance(param, (CodedConstParameter, PhysicalConstantParameter)):
+            param.encode_into_pdu(physical_value=None, encode_state=encode_state)
+        else:
+            break
+
+    return encode_state.coded_message
+
+
+def composite_codec_encode_into_pdu(codec: CompositeCodec, physical_value: Optional[ParameterValue],
+                                    encode_state: EncodeState) -> None:
+    from .parameters.lengthkeyparameter import LengthKeyParameter
+    from .parameters.tablekeyparameter import TableKeyParameter
+
+    if not isinstance(physical_value, dict):
+        odxraise(
+            f"Expected a dictionary for the values of {codec.short_name}, "
+            f"got {type(physical_value).__name__}", EncodeError)
+    elif encode_state.cursor_bit_position != 0:
+        odxraise(
+            f"Compositional codec objecs must be byte aligned, but "
+            f"{codec.short_name} requested to be at bit position "
+            f"{encode_state.cursor_bit_position}", EncodeError)
+        encode_state.bit_position = 0
+
+    orig_origin = encode_state.origin_byte_position
+    encode_state.origin_byte_position = encode_state.cursor_byte_position
+
+    orig_is_end_of_pdu = encode_state.is_end_of_pdu
+    encode_state.is_end_of_pdu = False
+
+    # ensure that no values for unknown parameters are specified.
+    if not encode_state.allow_unknown_parameters:
+        param_names = {param.short_name for param in codec.parameters}
+        for param_value_name in physical_value:
+            if param_value_name not in param_names:
+                odxraise(f"Value for unknown parameter '{param_value_name}' specified "
+                         f"for composite codec object {codec.short_name}")
+
+    for param in codec.parameters:
+        if id(param) == id(codec.parameters[-1]):
+            # The last parameter of the composite codec object is at
+            # the end of the PDU if the codec object itself is at the
+            # end of the PDU.
+            #
+            # TODO: This assumes that the last parameter specified in
+            # the ODX is located last in the PDU...
+            encode_state.is_end_of_pdu = orig_is_end_of_pdu
+
+        if isinstance(param, (LengthKeyParameter, TableKeyParameter)):
+            # At this point, we encode a placeholder value for length-
+            # and table keys, since these can be specified
+            # implicitly (i.e., by means of parameters that use
+            # these keys). To avoid getting an "overlapping
+            # parameter" warning, we must encode a value of zero
+            # into the PDU here and add the real value of the
+            # parameter in a post-processing step.
+            param.encode_placeholder_into_pdu(
+                physical_value=physical_value.get(param.short_name), encode_state=encode_state)
+
+            continue
+
+        if param.is_required and param.short_name not in physical_value:
+            odxraise(f"No value for required parameter {param.short_name} specified", EncodeError)
+
+        param_phys_value = physical_value.get(param.short_name)
+        param.encode_into_pdu(physical_value=param_phys_value, encode_state=encode_state)
+
+        encode_state.journal.append((param, param_phys_value))
+
+    encode_state.is_end_of_pdu = False
+
+    # encode the length- and table keys. This cannot be done above
+    # because we allow these to be defined implicitly (i.e. they
+    # are defined by their respective users)
+    for param in codec.parameters:
+        if not isinstance(param, (LengthKeyParameter, TableKeyParameter)):
+            # the current parameter is neither a length- nor a table key
+            continue
+
+        # Encode the value of the key parameter into the message
+        param.encode_value_into_pdu(encode_state=encode_state)
+
+    encode_state.origin_byte_position = orig_origin
+
+
+def composite_codec_decode_from_pdu(codec: CompositeCodec,
+                                    decode_state: DecodeState) -> ParameterValue:
+    # move the origin since positions specified by sub-parameters of
+    # composite codec objects are relative to the beginning of the
+    # object.
+    orig_origin = decode_state.origin_byte_position
+    decode_state.origin_byte_position = decode_state.cursor_byte_position
+
+    result = {}
+    for param in codec.parameters:
+        value = param.decode_from_pdu(decode_state)
+
+        decode_state.journal.append((param, value))
+        result[param.short_name] = value
+
+    # decoding of the composite codec object finished. go back the
+    # original origin.
+    decode_state.origin_byte_position = orig_origin
+
+    return result

odxtools/diaglayers/hierarchyelement.py

@@ -8,8 +8,6 @@ from typing import (TYPE_CHECKING, Any, Callable, Dict, Iterable, List, Optional
                     Union, cast)
 from xml.etree import ElementTree
 
-from deprecation import deprecated
-
 from ..additionalaudience import AdditionalAudience
 from ..admindata import AdminData
 from ..comparaminstance import ComparamInstance
@@ -724,10 +722,6 @@ class HierarchyElement(DiagLayer):
 
         return int(result)
 
-    @deprecated(details="use get_can_receive_id()")  # type: ignore[misc]
-    def get_receive_id(self) -> Optional[int]:
-        return self.get_can_receive_id()
-
     def get_can_send_id(self, protocol: Optional[Union[str, "Protocol"]] = None) -> Optional[int]:
         """CAN ID to which the ECU sends replies to diagnostic messages"""
 
@@ -753,10 +747,6 @@ class HierarchyElement(DiagLayer):
 
         return int(result)
 
-    @deprecated(details="use get_can_send_id()")  # type: ignore[misc]
-    def get_send_id(self) -> Optional[int]:
-        return self.get_can_send_id()
-
     def get_can_func_req_id(self,
                             protocol: Optional[Union[str, "Protocol"]] = None) -> Optional[int]:
         """CAN Functional Request Id."""

odxtools/dopbase.py

@@ -16,10 +16,12 @@ from .utils import dataclass_fields_asdict
 
 @dataclass
 class DopBase(IdentifiableElement):
-    """Base class for all DOPs.
+    """Base class for all (simple and complex) data object properties.
+
+    Any class that a parameter can reference via a DOP-REF (Simple
+    DOPs, structures, ...) inherits from this class. All DOPs objects
+    implement the `Codec` type protocol.
 
-    Any class that a parameter can reference via a DOP-REF should
-    inherit from this class.
     """
 
     admin_data: Optional[AdminData]