odxtools 9.4.1__py3-none-any.whl → 9.6.0__py3-none-any.whl

odxtools/statetransitionref.py

@@ -0,0 +1,231 @@
+# SPDX-License-Identifier: MIT
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple, Union
+from xml.etree import ElementTree
+
+from .basicstructure import BasicStructure
+from .dataobjectproperty import DataObjectProperty
+from .exceptions import odxassert, odxraise, odxrequire
+from .odxlink import OdxDocFragment, OdxLinkDatabase, OdxLinkId, OdxLinkRef, resolve_snref
+from .odxtypes import ParameterValue, ParameterValueDict
+from .parameters.codedconstparameter import CodedConstParameter
+from .parameters.parameter import Parameter
+from .parameters.physicalconstantparameter import PhysicalConstantParameter
+from .parameters.tablekeyparameter import TableKeyParameter
+from .parameters.tablestructparameter import TableStructParameter
+from .parameters.valueparameter import ValueParameter
+from .snrefcontext import SnRefContext
+from .state import State
+from .statemachine import StateMachine
+from .statetransition import StateTransition
+from .utils import dataclass_fields_asdict
+
+if TYPE_CHECKING:
+    from .preconditionstateref import PreConditionStateRef
+    from .statemachine import StateMachine
+    from .tablerow import TableRow
+
+
+def _resolve_in_param(
+    in_param_if_snref: Optional[str],
+    in_param_if_snpathref: Optional[str],
+    params: List[Parameter],
+    param_dict: ParameterValueDict,
+) -> Tuple[Optional[Parameter], Optional[ParameterValue]]:
+
+    if in_param_if_snref is not None:
+        path_chunks = [in_param_if_snref]
+    elif in_param_if_snpathref is not None:
+        path_chunks = in_param_if_snpathref.split(".")
+    else:
+        return None, None
+
+    return _resolve_in_param_helper(params, param_dict, path_chunks)
+
+
+def _resolve_in_param_helper(
+    params: List[Parameter],
+    param_dict: ParameterValueDict,
+    path_chunks: List[str],
+) -> Tuple[Optional[Parameter], Optional[ParameterValue]]:
+
+    inner_param = resolve_snref(path_chunks[0], params, Parameter, lenient=True)
+    if inner_param is None:
+        return None, None
+    inner_param_value = param_dict.get(path_chunks[0])
+
+    if len(path_chunks) == 1:
+        return inner_param, inner_param_value
+
+    # deal with table parameters
+    if isinstance(inner_param, TableStructParameter):
+        if not isinstance(inner_param_value, tuple) or len(inner_param_value) == 2:
+            odxraise("Invalid value for table struct parameter")
+            return None, None
+
+        if TYPE_CHECKING:
+            tr = resolve_snref(inner_param_value[0], inner_param.table.table_rows, TableRow)
+        else:
+            tr = resolve_snref(inner_param_value[0], inner_param.table.table_rows)
+
+        if tr.structure is None:
+            odxraise("Table row must reference a structure")
+            return None, None
+
+        inner_param_list = tr.structure.parameters
+        inner_param_value = inner_param_value[1]
+    else:
+        dop = getattr(inner_param, "dop", None)
+        if isinstance(dop, BasicStructure):
+            inner_param_list = dop.parameters
+        else:
+            odxraise(f"Expected the referenced parameter to be composite")
+
+    if not isinstance(inner_param_value, dict):
+        odxraise(f"Expected the referenced parameter to be composite")
+        return None, None
+
+    return _resolve_in_param_helper(inner_param_list, inner_param_value, path_chunks[1:])
+
+
+def _check_applies(ref: Union["StateTransitionRef",
+                              "PreConditionStateRef"], state_machine: "StateMachine",
+                   params: List[Parameter], param_value_dict: ParameterValueDict) -> bool:
+    if state_machine.active_state != ref.state:
+        # if the active state of the state machine is not the
+        # specified one, the precondition does not apply
+        return False
+
+    if ref.in_param_if_snref is None and ref.in_param_if_snpathref is None:
+        # no parameter given -> only the specified state is relevant
+        return True
+
+    param, param_value = \
+        _resolve_in_param(ref.in_param_if_snref, ref.in_param_if_snpathref, params, param_value_dict)
+
+    if param is None:
+        # The referenced parameter does not exist.
+        return False
+    elif not isinstance(
+            param,
+        (CodedConstParameter, PhysicalConstantParameter, TableKeyParameter, ValueParameter)):
+        # see checker rule 194 in section B.2 of the spec
+        odxraise(f"Parameter referenced by state transition ref is of "
+                 f"invalid type {type(param).__name__}")
+        return False
+    elif isinstance(param, (CodedConstParameter, PhysicalConstantParameter,
+                            TableKeyParameter)) and ref.value is not None:
+        # see checker rule 193 in section B.2 of the spec. Why can
+        # no values for constant parameters be specified? (This
+        # seems to be rather inconvenient...)
+        odxraise(f"No value may be specified for state transitions referencing "
+                 f"parameters of type {type(param).__name__}")
+        return False
+    elif isinstance(param, ValueParameter):
+        # see checker rule 193 in section B.2 of the spec
+        if ref.value is None:
+            odxraise(f"An expected VALUE must be specified for preconditions "
+                     f"referencing VALUE parameters")
+            return False
+
+        if param_value is None:
+            param_value = param.physical_default_value
+            if param_value is None:
+                odxraise(f"No value can be determined for parameter {param.short_name}")
+                return False
+
+        if param.dop is None or not isinstance(param.dop, DataObjectProperty):
+            odxraise(f"Parameter {param.short_name} uses a non-simple DOP")
+            return False
+
+        expected_value = param.dop.physical_type.base_data_type.from_string(ref.value)
+
+        if expected_value != param_value:
+            return False
+
+    return True
+
+
+@dataclass
+class StateTransitionRef(OdxLinkRef):
+    """Describes a state transition that is to be potentially taken if
+    a diagnostic communication is executed
+
+    Besides the "raw" state transistion, state transition references
+    may also be conditional on the observed response of the ECU.
+
+    """
+    value: Optional[str]
+
+    in_param_if_snref: Optional[str]
+    in_param_if_snpathref: Optional[str]
+
+    @property
+    def state_transition(self) -> StateTransition:
+        return self._state_transition
+
+    @property
+    def state(self) -> State:
+        return self.state_transition.source_state
+
+    @staticmethod
+    def from_et(  # type: ignore[override]
+            et_element: ElementTree.Element,
+            doc_frags: List[OdxDocFragment]) -> "StateTransitionRef":
+        kwargs = dataclass_fields_asdict(OdxLinkRef.from_et(et_element, doc_frags))
+
+        value = et_element.findtext("VALUE")
+
+        in_param_if_snref = None
+        if (in_param_if_snref_elem := et_element.find("IN-PARAM-IF-SNREF")) is not None:
+            in_param_if_snref = odxrequire(in_param_if_snref_elem.get("SHORT-NAME"))
+
+        in_param_if_snpathref = None
+        if (in_param_if_snpathref_elem := et_element.find("IN-PARAM-IF-SNPATHREF")) is not None:
+            in_param_if_snpathref = odxrequire(in_param_if_snpathref_elem.get("SHORT-NAME-PATH"))
+
+        return StateTransitionRef(
+            value=value,
+            in_param_if_snref=in_param_if_snref,
+            in_param_if_snpathref=in_param_if_snpathref,
+            **kwargs)
+
+    def __post_init__(self) -> None:
+        if self.value is not None:
+            odxassert(self.in_param_if_snref is not None or self.in_param_if_snref is not None,
+                      "If VALUE is specified, a parameter must be referenced")
+
+    def _build_odxlinks(self) -> Dict[OdxLinkId, Any]:
+        return {}
+
+    def _resolve_odxlinks(self, odxlinks: OdxLinkDatabase) -> None:
+        self._state_transition = odxlinks.resolve(self, StateTransition)
+
+    def _resolve_snrefs(self, context: SnRefContext) -> None:
+        pass
+
+    def execute(self, state_machine: StateMachine, params: List[Parameter],
+                param_value_dict: ParameterValueDict) -> bool:
+        """Update a StateMachine object if the state transition ought
+        to be executed based on the response received after executing a
+        diagnostic communication
+
+        Note that the specification is unclear about what the
+        parameters are: It says "The optional VALUE together with the
+        also optional IN-PARAM-IF snref at STATE-TRANSITION-REF and
+        PRE-CONDITION-STATE-REF can be used if the STATE-TRANSITIONs
+        and pre-condition STATEs are dependent on the values of the
+        referenced PARAMs.", but it does not specify what the
+        "referenced PARAMs" are. For the state transition refs, let's
+        assume that they are the parameters of a response received
+        from the ECU, whilst we assume that they are the parameters of
+        the request for PRE-CONDITION-STATE-REFs.
+
+        Returns:
+            ``True´` if the state transition was taken, else ``False``
+        """
+        if _check_applies(self, state_machine, params, param_value_dict):
+            state_machine.active_state = self.state_transition.target_state
+            return True
+
+        return False

odxtools/structure.py

@@ -13,6 +13,10 @@ from .utils import dataclass_fields_asdict
 class Structure(BasicStructure):
     is_visible_raw: Optional[bool]
 
+    @property
+    def is_visible(self) -> bool:
+        return self.is_visible_raw in (True, None)
+
     @staticmethod
     def from_et(et_element: ElementTree.Element, doc_frags: List[OdxDocFragment]) -> "Structure":
         """Read a STRUCTURE element from XML."""
@@ -21,7 +25,3 @@ class Structure(BasicStructure):
         is_visible_raw = odxstr_to_bool(et_element.get("IS-VISIBLE"))
 
         return Structure(is_visible_raw=is_visible_raw, **kwargs)
-
-    @property
-    def is_visible(self) -> bool:
-        return self.is_visible_raw in (True, None)

odxtools/subcomponent.py

@@ -1,6 +1,6 @@
 # SPDX-License-Identifier: MIT
 from dataclasses import dataclass
-from typing import Any, Dict, List, Optional
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
 from xml.etree import ElementTree
 
 from .diagnostictroublecode import DiagnosticTroubleCode
@@ -9,8 +9,7 @@ from .dtcdop import DtcDop
 from .element import IdentifiableElement, NamedElement
 from .environmentdata import EnvironmentData
 from .environmentdatadescription import EnvironmentDataDescription
-from .exceptions import odxraise, odxrequire
-from .matchingparameter import MatchingParameter
+from .exceptions import odxassert, odxraise, odxrequire
 from .nameditemlist import NamedItemList
 from .odxlink import OdxDocFragment, OdxLinkDatabase, OdxLinkId, OdxLinkRef, resolve_snref
 from .parameters.parameter import Parameter
@@ -19,14 +18,18 @@ from .table import Table
 from .tablerow import TableRow
 from .utils import dataclass_fields_asdict
 
+if TYPE_CHECKING:
+    from .matchingparameter import MatchingParameter
+
 
 @dataclass
 class SubComponentPattern:
-    matching_parameters: List[MatchingParameter]
+    matching_parameters: List["MatchingParameter"]
 
     @staticmethod
     def from_et(et_element: ElementTree.Element,
                 doc_frags: List[OdxDocFragment]) -> "SubComponentPattern":
+        from .matchingparameter import MatchingParameter
 
         matching_parameters = [
             MatchingParameter.from_et(el, doc_frags)
@@ -35,6 +38,21 @@ class SubComponentPattern:
 
         return SubComponentPattern(matching_parameters=matching_parameters)
 
+    def _build_odxlinks(self) -> Dict[OdxLinkId, Any]:
+        result = {}
+        for mp in self.matching_parameters:
+            result.update(mp._build_odxlinks())
+
+        return result
+
+    def _resolve_odxlinks(self, odxlinks: OdxLinkDatabase) -> None:
+        for mp in self.matching_parameters:
+            mp._resolve_odxlinks(odxlinks)
+
+    def _resolve_snrefs(self, context: SnRefContext) -> None:
+        for mp in self.matching_parameters:
+            mp._resolve_snrefs(context)
+
 
 @dataclass
 class SubComponentParamConnector(IdentifiableElement):
@@ -69,16 +87,18 @@ class SubComponentParamConnector(IdentifiableElement):
             if elem.tag != "OUT-PARAM-IF-SNREF":
                 odxraise("Currently, only SNREFS are supported for OUT-PARAM-IF-REFS")
                 continue
-
-            out_param_if_refs.append(odxrequire(elem.get("SHORT-NAME")))
+            else:
+                odxassert(elem.tag == "OUT-PARAM-IF-SNREF")
+                out_param_if_refs.append(odxrequire(elem.attrib.get("SHORT-NAME")))
 
         in_param_if_refs = []
         for elem in et_element.find("IN-PARAM-IF-REFS") or []:
             if elem.tag != "IN-PARAM-IF-SNREF":
                 odxraise("Currently, only SNREFS are supported for IN-PARAM-IF-REFS")
                 continue
-
-            in_param_if_refs.append(odxrequire(elem.get("SHORT-NAME")))
+            else:
+                odxassert(elem.tag == "IN-PARAM-IF-SNREF")
+                in_param_if_refs.append(odxrequire(elem.attrib.get("SHORT-NAME")))
 
         return SubComponentParamConnector(
             diag_comm_snref=diag_comm_snref,
@@ -103,13 +123,19 @@ class SubComponentParamConnector(IdentifiableElement):
         if not self._service.positive_responses:
             odxraise()
             return
-        request = odxrequire(service.request)
-        response = service.positive_responses[0]
 
+        request = odxrequire(service.request)
         in_param_ifs = []
         for x in self.in_param_if_refs:
             in_param_ifs.append(resolve_snref(x, request.parameters, Parameter))
 
+        # TODO: The output parameters are probably part of a response
+        # (?). If so, they cannot be resolved ahead of time because
+        # the service in question can have multiple responses
+        # associated with it and each of these has its own set of
+        # parameters. In the meantime, we simply use the first
+        # positive response specified.
+        response = service.positive_responses[0]
         out_param_ifs = []
         for x in self.out_param_if_refs:
             out_param_ifs.append(resolve_snref(x, response.parameters, Parameter))
@@ -232,7 +258,7 @@ class SubComponent(IdentifiableElement):
 
     """
 
-    #sub_component_patterns: NamedItemList[SubComponentPattern]
+    sub_component_patterns: List[SubComponentPattern]
     sub_component_param_connectors: NamedItemList[SubComponentParamConnector]
     table_row_connectors: NamedItemList[TableRowConnector]
     env_data_connectors: NamedItemList[EnvDataConnector]
@@ -246,6 +272,10 @@ class SubComponent(IdentifiableElement):
 
         semantic = et_element.get("SEMANTIC")
 
+        sub_component_patterns = [
+            SubComponentPattern.from_et(el, doc_frags)
+            for el in et_element.iterfind("SUB-COMPONENT-PATTERNS/SUB-COMPONENT-PATTERN")
+        ]
         sub_component_param_connectors = [
             SubComponentParamConnector.from_et(el, doc_frags) for el in et_element.iterfind(
                 "SUB-COMPONENT-PARAM-CONNECTORS/SUB-COMPONENT-PARAM-CONNECTOR")
@@ -265,6 +295,7 @@ class SubComponent(IdentifiableElement):
 
         return SubComponent(
             semantic=semantic,
+            sub_component_patterns=sub_component_patterns,
             sub_component_param_connectors=NamedItemList(sub_component_param_connectors),
             table_row_connectors=NamedItemList(table_row_connectors),
             env_data_connectors=NamedItemList(env_data_connectors),
@@ -274,15 +305,51 @@ class SubComponent(IdentifiableElement):
     def _build_odxlinks(self) -> Dict[OdxLinkId, Any]:
         result = {}
 
+        for scp in self.sub_component_patterns:
+            result.update(scp._build_odxlinks())
+
+        for scpc in self.sub_component_param_connectors:
+            result.update(scpc._build_odxlinks())
+
+        for trc in self.table_row_connectors:
+            result.update(trc._build_odxlinks())
+
+        for edc in self.env_data_connectors:
+            result.update(edc._build_odxlinks())
+
         for dtc_conn in self.dtc_connectors:
             result.update(dtc_conn._build_odxlinks())
 
         return result
 
     def _resolve_odxlinks(self, odxlinks: OdxLinkDatabase) -> None:
+        for scp in self.sub_component_patterns:
+            scp._resolve_odxlinks(odxlinks)
+
+        for scpc in self.sub_component_param_connectors:
+            scpc._resolve_odxlinks(odxlinks)
+
+        for trc in self.table_row_connectors:
+            trc._resolve_odxlinks(odxlinks)
+
+        for edc in self.env_data_connectors:
+            edc._resolve_odxlinks(odxlinks)
+
         for dtc_conn in self.dtc_connectors:
             dtc_conn._resolve_odxlinks(odxlinks)
 
     def _resolve_snrefs(self, context: SnRefContext) -> None:
+        for scp in self.sub_component_patterns:
+            scp._resolve_snrefs(context)
+
+        for scpc in self.sub_component_param_connectors:
+            scpc._resolve_snrefs(context)
+
+        for trc in self.table_row_connectors:
+            trc._resolve_snrefs(context)
+
+        for edc in self.env_data_connectors:
+            edc._resolve_snrefs(context)
+
         for dtc_conn in self.dtc_connectors:
             dtc_conn._resolve_snrefs(context)

odxtools/table.py

@@ -32,6 +32,7 @@ class TableDiagCommConnector:
                 doc_frags: List[OdxDocFragment]) -> "TableDiagCommConnector":
 
         semantic = odxrequire(et_element.findtext("SEMANTIC"))
+
         diag_comm_ref = OdxLinkRef.from_et(et_element.find("DIAG-COMM-REF"), doc_frags)
         diag_comm_snref = None
         if (dc_snref_elem := et_element.find("DIAG-COMM-SNREF")) is not None:
@@ -56,7 +57,6 @@ class TableDiagCommConnector:
 @dataclass
 class Table(IdentifiableElement):
     """This class represents a TABLE."""
-    semantic: Optional[str]
     key_label: Optional[str]
     struct_label: Optional[str]
     admin_data: Optional[AdminData]
@@ -64,13 +64,23 @@ class Table(IdentifiableElement):
     table_rows_raw: List[Union[TableRow, OdxLinkRef]]
     table_diag_comm_connectors: List[TableDiagCommConnector]
     sdgs: List[SpecialDataGroup]
+    semantic: Optional[str]
+
+    @property
+    def key_dop(self) -> Optional[DataObjectProperty]:
+        """The key data object property associated with this table."""
+        return self._key_dop
+
+    @property
+    def table_rows(self) -> NamedItemList[TableRow]:
+        """The table rows (both local and referenced) in this table."""
+        return self._table_rows
 
     @staticmethod
     def from_et(et_element: ElementTree.Element, doc_frags: List[OdxDocFragment]) -> "Table":
         """Reads a TABLE."""
         kwargs = dataclass_fields_asdict(IdentifiableElement.from_et(et_element, doc_frags))
         odx_id = kwargs["odx_id"]
-        semantic = et_element.get("SEMANTIC")
         key_label = et_element.findtext("KEY-LABEL")
         struct_label = et_element.findtext("STRUCT-LABEL")
         admin_data = AdminData.from_et(et_element.find("ADMIN-DATA"), doc_frags)
@@ -92,9 +102,9 @@ class Table(IdentifiableElement):
         sdgs = [
             SpecialDataGroup.from_et(sdge, doc_frags) for sdge in et_element.iterfind("SDGS/SDG")
         ]
+        semantic = et_element.get("SEMANTIC")
 
         return Table(
-            semantic=semantic,
             key_label=key_label,
             struct_label=struct_label,
             admin_data=admin_data,
@@ -102,18 +112,9 @@ class Table(IdentifiableElement):
             table_rows_raw=table_rows_raw,
             table_diag_comm_connectors=table_diag_comm_connectors,
             sdgs=sdgs,
+            semantic=semantic,
             **kwargs)
 
-    @property
-    def key_dop(self) -> Optional[DataObjectProperty]:
-        """The key data object property associated with this table."""
-        return self._key_dop
-
-    @property
-    def table_rows(self) -> NamedItemList[TableRow]:
-        """The table rows (both local and referenced) in this table."""
-        return self._table_rows
-
     def _build_odxlinks(self) -> Dict[OdxLinkId, Any]:
         result = {self.odx_id: self}
 
@@ -124,6 +125,9 @@ class Table(IdentifiableElement):
         for dcc in self.table_diag_comm_connectors:
             result.update(dcc._build_odxlinks())
 
+        for sdg in self.sdgs:
+            result.update(sdg._build_odxlinks())
+
         return result
 
     def _resolve_odxlinks(self, odxlinks: OdxLinkDatabase) -> None:
@@ -147,6 +151,9 @@ class Table(IdentifiableElement):
         for dcc in self.table_diag_comm_connectors:
             dcc._resolve_odxlinks(odxlinks)
 
+        for sdg in self.sdgs:
+            sdg._resolve_odxlinks(odxlinks)
+
     def _resolve_snrefs(self, context: SnRefContext) -> None:
         for table_row_wrapper in self.table_rows_raw:
             if isinstance(table_row_wrapper, TableRow):
@@ -154,3 +161,6 @@ class Table(IdentifiableElement):
 
         for dcc in self.table_diag_comm_connectors:
             dcc._resolve_snrefs(context)
+
+        for sdg in self.sdgs:
+            sdg._resolve_snrefs(context)