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

odxtools/relateddoc.py

@@ -1,24 +1,22 @@
 # SPDX-License-Identifier: MIT
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional
 from xml.etree import ElementTree
 
+from .description import Description
 from .odxlink import OdxDocFragment, OdxLinkDatabase, OdxLinkId
-from .utils import create_description_from_et
+from .snrefcontext import SnRefContext
 from .xdoc import XDoc
 
-if TYPE_CHECKING:
-    from .diaglayer import DiagLayer
-
 
 @dataclass
 class RelatedDoc:
-    description: Optional[str]
+    description: Optional[Description]
     xdoc: Optional[XDoc]
 
     @staticmethod
     def from_et(et_element: ElementTree.Element, doc_frags: List[OdxDocFragment]) -> "RelatedDoc":
-        description = create_description_from_et(et_element.find("DESC"))
+        description = Description.from_et(et_element.find("DESC"), doc_frags)
 
         xdoc: Optional[XDoc] = None
         if (xdoc_elem := et_element.find("XDOC")) is not None:
@@ -41,6 +39,6 @@ class RelatedDoc:
         if self.xdoc:
             self.xdoc._resolve_odxlinks(odxlinks)
 
-    def _resolve_snrefs(self, diag_layer: "DiagLayer") -> None:
+    def _resolve_snrefs(self, context: SnRefContext) -> None:
         if self.xdoc:
-            self.xdoc._resolve_snrefs(diag_layer)
+            self.xdoc._resolve_snrefs(context)

odxtools/request.py

@@ -1,22 +1,132 @@
 # SPDX-License-Identifier: MIT
 from dataclasses import dataclass
-from typing import List
+from typing import Any, Dict, List, Optional, cast
 from xml.etree import ElementTree
 
-from .basicstructure import BasicStructure
-from .odxlink import OdxDocFragment
+from .admindata import AdminData
+from .codec import (composite_codec_decode_from_pdu, composite_codec_encode_into_pdu,
+                    composite_codec_get_coded_const_prefix, composite_codec_get_free_parameters,
+                    composite_codec_get_required_parameters, composite_codec_get_static_bit_length)
+from .decodestate import DecodeState
+from .element import IdentifiableElement
+from .encodestate import EncodeState
+from .exceptions import odxraise
+from .nameditemlist import NamedItemList
+from .odxlink import OdxDocFragment, OdxLinkDatabase, OdxLinkId
+from .odxtypes import ParameterValue, ParameterValueDict
+from .parameters.createanyparameter import create_any_parameter_from_et
+from .parameters.parameter import Parameter
+from .snrefcontext import SnRefContext
+from .specialdatagroup import SpecialDataGroup
 from .utils import dataclass_fields_asdict
 
 
-# TODO: The spec does not say that requests are basic structures. For
-# now, we derive from it anyway because it simplifies the en- and
-# decoding machinery...
 @dataclass
-class Request(BasicStructure):
+class Request(IdentifiableElement):
+    """Represents all information related to an UDS request
+
+    This class implements the `CompositeCodec` interface.
+    """
+    admin_data: Optional[AdminData]
+    parameters: NamedItemList[Parameter]
+    sdgs: List[SpecialDataGroup]
+
+    @property
+    def required_parameters(self) -> List[Parameter]:
+        return composite_codec_get_required_parameters(self)
+
+    @property
+    def free_parameters(self) -> List[Parameter]:
+        return composite_codec_get_free_parameters(self)
 
     @staticmethod
     def from_et(et_element: ElementTree.Element, doc_frags: List[OdxDocFragment]) -> "Request":
-        """Reads a response."""
-        kwargs = dataclass_fields_asdict(BasicStructure.from_et(et_element, doc_frags))
+        kwargs = dataclass_fields_asdict(IdentifiableElement.from_et(et_element, doc_frags))
+
+        admin_data = AdminData.from_et(et_element.find("ADMIN-DATA"), doc_frags)
+        parameters = NamedItemList([
+            create_any_parameter_from_et(et_parameter, doc_frags)
+            for et_parameter in et_element.iterfind("PARAMS/PARAM")
+        ])
+        sdgs = [
+            SpecialDataGroup.from_et(sdge, doc_frags) for sdge in et_element.iterfind("SDGS/SDG")
+        ]
+
+        return Request(admin_data=admin_data, parameters=parameters, sdgs=sdgs, **kwargs)
+
+    def _build_odxlinks(self) -> Dict[OdxLinkId, Any]:
+        result = {self.odx_id: self}
+
+        if self.admin_data is not None:
+            result.update(self.admin_data._build_odxlinks())
+
+        for param in self.parameters:
+            result.update(param._build_odxlinks())
+
+        for sdg in self.sdgs:
+            result.update(sdg._build_odxlinks())
+
+        return result
+
+    def _resolve_odxlinks(self, odxlinks: OdxLinkDatabase) -> None:
+        if self.admin_data is not None:
+            self.admin_data._resolve_odxlinks(odxlinks)
+
+        for param in self.parameters:
+            param._resolve_odxlinks(odxlinks)
+
+        for sdg in self.sdgs:
+            sdg._resolve_odxlinks(odxlinks)
+
+    def _resolve_snrefs(self, context: SnRefContext) -> None:
+        context.request = self
+        context.parameters = self.parameters
+
+        if self.admin_data is not None:
+            self.admin_data._resolve_snrefs(context)
+
+        for param in self.parameters:
+            param._resolve_snrefs(context)
+
+        for sdg in self.sdgs:
+            sdg._resolve_snrefs(context)
+
+        context.request = None
+        context.parameters = None
+
+    def get_static_bit_length(self) -> Optional[int]:
+        return composite_codec_get_static_bit_length(self)
+
+    def print_free_parameters_info(self) -> None:
+        """Print a human readable description of the composite codec's
+        free parameters to `stdout`
+        """
+        from .parameterinfo import parameter_info
+
+        print(parameter_info(self.free_parameters), end="")
+
+    def encode(self, **kwargs: ParameterValue) -> bytearray:
+        encode_state = EncodeState(is_end_of_pdu=True)
+
+        self.encode_into_pdu(physical_value=kwargs, encode_state=encode_state)
+
+        return encode_state.coded_message
+
+    def decode(self, message: bytes) -> ParameterValueDict:
+        decode_state = DecodeState(coded_message=message)
+        param_values = self.decode_from_pdu(decode_state)
+
+        if not isinstance(param_values, dict):
+            odxraise("Decoding a request must result in a dictionary")
+
+        return cast(ParameterValueDict, param_values)
+
+    def encode_into_pdu(self, physical_value: Optional[ParameterValue],
+                        encode_state: EncodeState) -> None:
+        composite_codec_encode_into_pdu(self, physical_value, encode_state)
+
+    def decode_from_pdu(self, decode_state: DecodeState) -> ParameterValue:
+        return composite_codec_decode_from_pdu(self, decode_state)
 
-        return Request(**kwargs)
+    def coded_const_prefix(self, request_prefix: bytes = b'') -> bytes:
+        return composite_codec_get_coded_const_prefix(self, request_prefix)

odxtools/response.py

@@ -1,14 +1,24 @@
 # SPDX-License-Identifier: MIT
 from dataclasses import dataclass
 from enum import Enum
-from typing import List, Optional, cast
+from typing import Any, Dict, List, Optional, cast
 from xml.etree import ElementTree
 
-from .basicstructure import BasicStructure
+from .admindata import AdminData
+from .codec import (composite_codec_decode_from_pdu, composite_codec_encode_into_pdu,
+                    composite_codec_get_coded_const_prefix, composite_codec_get_free_parameters,
+                    composite_codec_get_required_parameters, composite_codec_get_static_bit_length)
+from .decodestate import DecodeState
+from .element import IdentifiableElement
+from .encodestate import EncodeState
 from .exceptions import odxraise
-from .odxlink import OdxDocFragment
-from .odxtypes import ParameterValue
-from .parameters.matchingrequestparameter import MatchingRequestParameter
+from .nameditemlist import NamedItemList
+from .odxlink import OdxDocFragment, OdxLinkDatabase, OdxLinkId
+from .odxtypes import ParameterValue, ParameterValueDict
+from .parameters.createanyparameter import create_any_parameter_from_et
+from .parameters.parameter import Parameter
+from .snrefcontext import SnRefContext
+from .specialdatagroup import SpecialDataGroup
 from .utils import dataclass_fields_asdict
 
 
@@ -18,17 +28,23 @@ class ResponseType(Enum):
     GLOBAL_NEGATIVE = "GLOBAL-NEG-RESPONSE"
 
 
-# TODO: The spec does not say that responses are basic structures. For
-# now, we derive from it anyway because it simplifies the en- and
-# decoding machinery...
 @dataclass
-class Response(BasicStructure):
+class Response(IdentifiableElement):
+    """Represents all information related to an UDS response
+
+    This class implements the `CompositeCodec` interface.
+    """
+
     response_type: ResponseType
 
+    admin_data: Optional[AdminData]
+    parameters: NamedItemList[Parameter]
+    sdgs: List[SpecialDataGroup]
+
     @staticmethod
     def from_et(et_element: ElementTree.Element, doc_frags: List[OdxDocFragment]) -> "Response":
         """Reads a response."""
-        kwargs = dataclass_fields_asdict(BasicStructure.from_et(et_element, doc_frags))
+        kwargs = dataclass_fields_asdict(IdentifiableElement.from_et(et_element, doc_frags))
 
         try:
             response_type = ResponseType(et_element.tag)
@@ -36,19 +52,103 @@ class Response(BasicStructure):
             response_type = cast(ResponseType, None)
             odxraise(f"Encountered unknown response type '{et_element.tag}'")
 
-        return Response(response_type=response_type, **kwargs)
+        admin_data = AdminData.from_et(et_element.find("ADMIN-DATA"), doc_frags)
+        parameters = NamedItemList([
+            create_any_parameter_from_et(et_parameter, doc_frags)
+            for et_parameter in et_element.iterfind("PARAMS/PARAM")
+        ])
+        sdgs = [
+            SpecialDataGroup.from_et(sdge, doc_frags) for sdge in et_element.iterfind("SDGS/SDG")
+        ]
+
+        return Response(
+            response_type=response_type,
+            admin_data=admin_data,
+            parameters=parameters,
+            sdgs=sdgs,
+            **kwargs)
+
+    def _build_odxlinks(self) -> Dict[OdxLinkId, Any]:
+        result = {self.odx_id: self}
+
+        if self.admin_data is not None:
+            result.update(self.admin_data._build_odxlinks())
+
+        for param in self.parameters:
+            result.update(param._build_odxlinks())
+
+        for sdg in self.sdgs:
+            result.update(sdg._build_odxlinks())
+
+        return result
+
+    def _resolve_odxlinks(self, odxlinks: OdxLinkDatabase) -> None:
+        if self.admin_data is not None:
+            self.admin_data._resolve_odxlinks(odxlinks)
+
+        for param in self.parameters:
+            param._resolve_odxlinks(odxlinks)
+
+        for sdg in self.sdgs:
+            sdg._resolve_odxlinks(odxlinks)
+
+    def _resolve_snrefs(self, context: SnRefContext) -> None:
+        context.response = self
+        context.parameters = self.parameters
+
+        if self.admin_data is not None:
+            self.admin_data._resolve_snrefs(context)
+
+        for param in self.parameters:
+            param._resolve_snrefs(context)
+
+        for sdg in self.sdgs:
+            sdg._resolve_snrefs(context)
+
+        context.response = None
+        context.parameters = None
+
+    def encode(self, coded_request: Optional[bytes] = None, **kwargs: ParameterValue) -> bytearray:
+        encode_state = EncodeState(triggering_request=coded_request, is_end_of_pdu=True)
+
+        self.encode_into_pdu(physical_value=kwargs, encode_state=encode_state)
+
+        return encode_state.coded_message
+
+    def decode(self, message: bytes) -> ParameterValueDict:
+        decode_state = DecodeState(coded_message=message)
+        param_values = self.decode_from_pdu(decode_state)
+
+        if not isinstance(param_values, dict):
+            odxraise("Decoding a response must result in a dictionary")
+
+        return cast(ParameterValueDict, param_values)
+
+    def encode_into_pdu(self, physical_value: Optional[ParameterValue],
+                        encode_state: EncodeState) -> None:
+        composite_codec_encode_into_pdu(self, physical_value, encode_state)
+
+    def decode_from_pdu(self, decode_state: DecodeState) -> ParameterValue:
+        return composite_codec_decode_from_pdu(self, decode_state)
+
+    def get_static_bit_length(self) -> Optional[int]:
+        return composite_codec_get_static_bit_length(self)
+
+    @property
+    def required_parameters(self) -> List[Parameter]:
+        return composite_codec_get_required_parameters(self)
+
+    @property
+    def free_parameters(self) -> List[Parameter]:
+        return composite_codec_get_free_parameters(self)
 
-    def encode(self, coded_request: Optional[bytes] = None, **params: ParameterValue) -> bytes:
-        if coded_request is not None:
-            # Extract MATCHING-REQUEST-PARAMs from the coded
-            # request. TODO: this should be done by
-            # MatchingRequestParam itself!
-            for param in self.parameters:
-                if isinstance(param, MatchingRequestParameter):
-                    byte_pos = param.request_byte_position
-                    byte_length = param.byte_length
+    def print_free_parameters_info(self) -> None:
+        """Return a human readable description of the structure's
+        free parameters.
+        """
+        from .parameterinfo import parameter_info
 
-                    val = coded_request[byte_pos:byte_pos + byte_length]
-                    params[param.short_name] = val
+        print(parameter_info(self.free_parameters), end="")
 
-        return super().encode(coded_request=coded_request, **params)
+    def coded_const_prefix(self, request_prefix: bytes = b'') -> bytes:
+        return composite_codec_get_coded_const_prefix(self, request_prefix)

odxtools/scaleconstr.py

@@ -1,13 +1,14 @@
 # SPDX-License-Identifier: MIT
 from dataclasses import dataclass
 from enum import Enum
-from typing import Optional
+from typing import List, Optional
 from xml.etree import ElementTree
 
 from .compumethods.limit import Limit
+from .description import Description
 from .exceptions import odxraise, odxrequire
+from .odxlink import OdxDocFragment
 from .odxtypes import DataType
-from .utils import create_description_from_et
 
 
 class ValidType(Enum):
@@ -23,18 +24,22 @@ class ScaleConstr:
     """
 
     short_label: Optional[str]
-    description: Optional[str]
+    description: Optional[Description]
     lower_limit: Optional[Limit]
     upper_limit: Optional[Limit]
     validity: ValidType
+    value_type: DataType
 
     @staticmethod
-    def from_et(et_element: ElementTree.Element, internal_type: DataType) -> "ScaleConstr":
+    def scale_constr_from_et(et_element: ElementTree.Element, doc_frags: List[OdxDocFragment], *,
+                             value_type: DataType) -> "ScaleConstr":
         short_label = et_element.findtext("SHORT-LABEL")
-        description = create_description_from_et(et_element.find("DESC"))
+        description = Description.from_et(et_element.find("DESC"), doc_frags)
 
-        lower_limit = Limit.from_et(et_element.find("LOWER-LIMIT"), internal_type=internal_type)
-        upper_limit = Limit.from_et(et_element.find("UPPER-LIMIT"), internal_type=internal_type)
+        lower_limit = Limit.limit_from_et(
+            et_element.find("LOWER-LIMIT"), doc_frags, value_type=value_type)
+        upper_limit = Limit.limit_from_et(
+            et_element.find("UPPER-LIMIT"), doc_frags, value_type=value_type)
 
         validity_str = odxrequire(et_element.get("VALIDITY"))
         try:
@@ -47,4 +52,5 @@ class ScaleConstr:
             description=description,
             lower_limit=lower_limit,
             upper_limit=upper_limit,
-            validity=validity)
+            validity=validity,
+            value_type=value_type)

odxtools/servicebinner.py

@@ -91,7 +91,7 @@ class ServiceBinner:
         """
         result = StringIO()
         result.write("[ ")
-        result.write(", ".join([f"0x{x}" for x in self._service_groups if x is not None]))
+        result.write(", ".join([f"0x{x:x}" for x in self._service_groups if x is not None]))
         result.write(" ]")
 
         return result.getvalue()

odxtools/singleecujob.py

@@ -1,6 +1,6 @@
 # SPDX-License-Identifier: MIT
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Dict, List
+from typing import Any, Dict, List
 from xml.etree import ElementTree
 
 from .diagcomm import DiagComm
@@ -10,11 +10,9 @@ from .negoutputparam import NegOutputParam
 from .odxlink import OdxDocFragment, OdxLinkDatabase, OdxLinkId
 from .outputparam import OutputParam
 from .progcode import ProgCode
+from .snrefcontext import SnRefContext
 from .utils import dataclass_fields_asdict
 
-if TYPE_CHECKING:
-    from .diaglayer import DiagLayer
-
 
 @dataclass
 class SingleEcuJob(DiagComm):
@@ -88,14 +86,18 @@ class SingleEcuJob(DiagComm):
         for neg_output_param in self.neg_output_params:
             neg_output_param._resolve_odxlinks(odxlinks)
 
-    def _resolve_snrefs(self, diag_layer: "DiagLayer") -> None:
-        super()._resolve_snrefs(diag_layer)
+    def _resolve_snrefs(self, context: SnRefContext) -> None:
+        context.single_ecu_job = self
+
+        super()._resolve_snrefs(context)
 
         for prog_code in self.prog_codes:
-            prog_code._resolve_snrefs(diag_layer)
+            prog_code._resolve_snrefs(context)
         for input_param in self.input_params:
-            input_param._resolve_snrefs(diag_layer)
+            input_param._resolve_snrefs(context)
         for output_param in self.output_params:
-            output_param._resolve_snrefs(diag_layer)
+            output_param._resolve_snrefs(context)
         for neg_output_param in self.neg_output_params:
-            neg_output_param._resolve_snrefs(diag_layer)
+            neg_output_param._resolve_snrefs(context)
+
+        context.single_ecu_job = None

odxtools/snrefcontext.py

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: MIT
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, List, Optional
+
+if TYPE_CHECKING:
+    from .database import Database
+    from .diaglayers.diaglayer import DiagLayer
+    from .diagservice import DiagService
+    from .parameters.parameter import Parameter
+    from .request import Request
+    from .response import Response
+    from .singleecujob import SingleEcuJob
+    from .statechart import StateChart
+
+
+@dataclass
+class SnRefContext:
+    """Represents the context for which a short name reference ought
+    to be resolved
+    """
+
+    database: Optional["Database"] = None
+    diag_layer: Optional["DiagLayer"] = None
+    diag_service: Optional["DiagService"] = None
+    single_ecu_job: Optional["SingleEcuJob"] = None
+    request: Optional["Request"] = None
+    response: Optional["Response"] = None
+    parameters: Optional[List["Parameter"]] = None
+    state_chart: Optional["StateChart"] = None

odxtools/specialdata.py

@@ -1,12 +1,10 @@
 # SPDX-License-Identifier: MIT
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional
 from xml.etree import ElementTree
 
 from .odxlink import OdxDocFragment, OdxLinkDatabase, OdxLinkId
-
-if TYPE_CHECKING:
-    from .diaglayer import DiagLayer
+from .snrefcontext import SnRefContext
 
 
 @dataclass
@@ -21,7 +19,7 @@ class SpecialData:
     def _resolve_odxlinks(self, odxlinks: OdxLinkDatabase) -> None:
         pass
 
-    def _resolve_snrefs(self, diag_layer: "DiagLayer") -> None:
+    def _resolve_snrefs(self, context: SnRefContext) -> None:
         pass
 
     @staticmethod

odxtools/specialdatagroup.py

@@ -1,22 +1,20 @@
 # SPDX-License-Identifier: MIT
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union
+from typing import Any, Dict, List, Optional, Union
 from xml.etree import ElementTree
 
 from .odxlink import OdxDocFragment, OdxLinkDatabase, OdxLinkId, OdxLinkRef
+from .snrefcontext import SnRefContext
 from .specialdata import SpecialData
 from .specialdatagroupcaption import SpecialDataGroupCaption
 
-if TYPE_CHECKING:
-    from .diaglayer import DiagLayer
-
 
 @dataclass
 class SpecialDataGroup:
     sdg_caption: Optional[SpecialDataGroupCaption]
     sdg_caption_ref: Optional[OdxLinkRef]
-    semantic_info: Optional[str]  # the "SI" attribute
     values: List[Union["SpecialDataGroup", SpecialData]]
+    semantic_info: Optional[str]  # the "SI" attribute
 
     @staticmethod
     def from_et(et_element: ElementTree.Element,
@@ -53,7 +51,7 @@ class SpecialDataGroup:
     def _build_odxlinks(self) -> Dict[OdxLinkId, Any]:
         result = {}
 
-        if self.sdg_caption is not None:
+        if self.sdg_caption_ref is None and self.sdg_caption is not None:
             result.update(self.sdg_caption._build_odxlinks())
 
         for val in self.values:
@@ -72,11 +70,11 @@ class SpecialDataGroup:
         for val in self.values:
             val._resolve_odxlinks(odxlinks)
 
-    def _resolve_snrefs(self, diag_layer: "DiagLayer") -> None:
+    def _resolve_snrefs(self, context: SnRefContext) -> None:
         # resolve the SNREFs of the caption, but only if the caption
         # was specified by value, not by reference
         if self.sdg_caption is not None and self.sdg_caption_ref is None:
-            self.sdg_caption._resolve_snrefs(diag_layer)
+            self.sdg_caption._resolve_snrefs(context)
 
         for val in self.values:
-            val._resolve_snrefs(diag_layer)
+            val._resolve_snrefs(context)

odxtools/specialdatagroupcaption.py

@@ -1,16 +1,13 @@
 # SPDX-License-Identifier: MIT
-# import warnings
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Dict, List
+from typing import Any, Dict, List
 from xml.etree import ElementTree
 
 from .element import IdentifiableElement
 from .odxlink import OdxDocFragment, OdxLinkDatabase, OdxLinkId
+from .snrefcontext import SnRefContext
 from .utils import dataclass_fields_asdict
 
-if TYPE_CHECKING:
-    from .diaglayer import DiagLayer
-
 
 @dataclass
 class SpecialDataGroupCaption(IdentifiableElement):
@@ -32,5 +29,5 @@ class SpecialDataGroupCaption(IdentifiableElement):
     def _resolve_odxlinks(self, odxlinks: OdxLinkDatabase) -> None:
         pass
 
-    def _resolve_snrefs(self, diag_layer: "DiagLayer") -> None:
+    def _resolve_snrefs(self, context: SnRefContext) -> None:
         pass