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

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/commrelation.py

@@ -0,0 +1,122 @@
+# SPDX-License-Identifier: MIT
+import warnings
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Dict, List, Optional
+from xml.etree import ElementTree
+
+from .description import Description
+from .diagcomm import DiagComm
+from .diagservice import DiagService
+from .exceptions import OdxWarning, odxraise, odxrequire
+from .odxlink import OdxDocFragment, OdxLinkDatabase, OdxLinkId, OdxLinkRef, resolve_snref
+from .parameters.parameter import Parameter
+from .snrefcontext import SnRefContext
+
+
+class CommRelationValueType(Enum):
+    CURRENT = "CURRENT"
+    STORED = "STORED"
+    STATIC = "STATIC"
+    SUBSTITUTED = "SUBSTITUTED"
+
+
+@dataclass
+class CommRelation:
+    description: Optional[Description]
+    relation_type: str
+    diag_comm_ref: Optional[OdxLinkRef]
+    diag_comm_snref: Optional[str]
+    in_param_if_snref: Optional[str]
+    #in_param_if_snpathref: Optional[str] # TODO
+    out_param_if_snref: Optional[str]
+    #out_param_if_snpathref: Optional[str] # TODO
+    value_type_raw: Optional[CommRelationValueType]
+
+    @property
+    def diag_comm(self) -> DiagComm:
+        return self._diag_comm
+
+    @property
+    def in_param_if(self) -> Optional[Parameter]:
+        return self._in_param_if
+
+    @property
+    def out_param_if(self) -> Optional[Parameter]:
+        return self._out_param_if
+
+    @property
+    def value_type(self) -> CommRelationValueType:
+        if self.value_type_raw is None:
+            return CommRelationValueType.CURRENT
+
+        return self.value_type_raw
+
+    @staticmethod
+    def from_et(et_element: ElementTree.Element, doc_frags: List[OdxDocFragment]) -> "CommRelation":
+        description = Description.from_et(et_element.find("DESC"), doc_frags)
+        relation_type = odxrequire(et_element.findtext("RELATION-TYPE"))
+
+        diag_comm_ref = OdxLinkRef.from_et(et_element.find("DIAG-COMM-REF"), doc_frags)
+        diag_comm_snref = None
+        if (diag_comm_snref_elem := et_element.find("DIAG-COMM-SNREF")) is not None:
+            diag_comm_snref = odxrequire(diag_comm_snref_elem.get("SHORT-NAME"))
+
+        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"))
+
+        if et_element.find("IN-PARAM-IF-SNPATHREF") is not None:
+            warnings.warn("SNPATHREFs are not supported by odxtools yet", OdxWarning, stacklevel=1)
+
+        out_param_if_snref = None
+        if (out_param_if_snref_elem := et_element.find("OUT-PARAM-IF-SNREF")) is not None:
+            out_param_if_snref = odxrequire(out_param_if_snref_elem.get("SHORT-NAME"))
+
+        if et_element.find("OUT-PARAM-IF-SNPATHREF") is not None:
+            warnings.warn("SNPATHREFs are not supported by odxtools yet", OdxWarning, stacklevel=1)
+
+        value_type_raw = None
+        if (value_type_str := et_element.get("VALUE-TYPE")) is not None:
+            try:
+                value_type_raw = CommRelationValueType(value_type_str)
+            except ValueError:
+                odxraise(f"Encountered unknown comm relation value type '{value_type_str}'")
+
+        return CommRelation(
+            description=description,
+            relation_type=relation_type,
+            diag_comm_ref=diag_comm_ref,
+            diag_comm_snref=diag_comm_snref,
+            in_param_if_snref=in_param_if_snref,
+            out_param_if_snref=out_param_if_snref,
+            value_type_raw=value_type_raw)
+
+    def _build_odxlinks(self) -> Dict[OdxLinkId, Any]:
+        return {}
+
+    def _resolve_odxlinks(self, odxlinks: OdxLinkDatabase) -> None:
+        if self.diag_comm_ref is not None:
+            self._diag_comm = odxlinks.resolve(self.diag_comm_ref, DiagComm)
+
+    def _resolve_snrefs(self, context: SnRefContext) -> None:
+        diag_layer = odxrequire(context.diag_layer)
+
+        if self.diag_comm_snref is not None:
+            self._diag_comm = resolve_snref(self.diag_comm_snref, diag_layer.diag_comms, DiagComm)
+
+        service = self.diag_comm
+        if not isinstance(service, DiagService):
+            odxraise(f"DIAG-VARIABLE references non-service {type(service).__name__} "
+                     f"diagnostic communication")
+
+        self._in_param_if = None
+        if self.in_param_if_snref is not None:
+            self._in_param_if = resolve_snref(self.in_param_if_snref,
+                                              odxrequire(service.request).parameters, Parameter)
+
+        self._out_param_if = None
+        if self.out_param_if_snref is not None:
+            self._out_param_if = resolve_snref(self.out_param_if_snref,
+                                               odxrequire(service.positive_responses[0]).parameters,
+                                               Parameter)

odxtools/companydata.py

@@ -1,6 +1,6 @@
 # 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 .companyspecificinfo import CompanySpecificInfo
@@ -8,12 +8,10 @@ from .element import IdentifiableElement
 from .exceptions import odxrequire
 from .nameditemlist import NamedItemList
 from .odxlink import OdxDocFragment, OdxLinkDatabase, OdxLinkId
+from .snrefcontext import SnRefContext
 from .teammember import TeamMember
 from .utils import dataclass_fields_asdict
 
-if TYPE_CHECKING:
-    from .diaglayer import DiagLayer
-
 
 @dataclass
 class CompanyData(IdentifiableElement):
@@ -64,9 +62,9 @@ class CompanyData(IdentifiableElement):
         if self.company_specific_info:
             self.company_specific_info._resolve_odxlinks(odxlinks)
 
-    def _resolve_snrefs(self, diag_layer: "DiagLayer") -> None:
+    def _resolve_snrefs(self, context: SnRefContext) -> None:
         for tm in self.team_members:
-            tm._resolve_snrefs(diag_layer)
+            tm._resolve_snrefs(context)
 
         if self.company_specific_info:
-            self.company_specific_info._resolve_snrefs(diag_layer)
+            self.company_specific_info._resolve_snrefs(context)

odxtools/companydocinfo.py

@@ -1,18 +1,15 @@
 # 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 .companydata import CompanyData
-from .createsdgs import create_sdgs_from_et
 from .exceptions import odxrequire
 from .odxlink import OdxDocFragment, OdxLinkDatabase, OdxLinkId, OdxLinkRef
+from .snrefcontext import SnRefContext
 from .specialdatagroup import SpecialDataGroup
 from .teammember import TeamMember
 
-if TYPE_CHECKING:
-    from .diaglayer import DiagLayer
-
 
 @dataclass
 class CompanyDocInfo:
@@ -37,7 +34,9 @@ class CompanyDocInfo:
             OdxLinkRef.from_et(et_element.find("COMPANY-DATA-REF"), doc_frags))
         team_member_ref = OdxLinkRef.from_et(et_element.find("TEAM-MEMBER-REF"), doc_frags)
         doc_label = et_element.findtext("DOC-LABEL")
-        sdgs = create_sdgs_from_et(et_element.find("SDGS"), doc_frags)
+        sdgs = [
+            SpecialDataGroup.from_et(sdge, doc_frags) for sdge in et_element.iterfind("SDGS/SDG")
+        ]
 
         return CompanyDocInfo(
             company_data_ref=company_data_ref,
@@ -64,6 +63,6 @@ class CompanyDocInfo:
         for sdg in self.sdgs:
             sdg._resolve_odxlinks(odxlinks)
 
-    def _resolve_snrefs(self, diag_layer: "DiagLayer") -> None:
+    def _resolve_snrefs(self, context: SnRefContext) -> None:
         for sdg in self.sdgs:
-            sdg._resolve_snrefs(diag_layer)
+            sdg._resolve_snrefs(context)

odxtools/companyrevisioninfo.py

@@ -1,14 +1,12 @@
 # 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 .companydata import CompanyData
 from .exceptions import odxrequire
 from .odxlink import OdxDocFragment, OdxLinkDatabase, OdxLinkId, OdxLinkRef
-
-if TYPE_CHECKING:
-    from .diaglayer import DiagLayer
+from .snrefcontext import SnRefContext
 
 
 @dataclass
@@ -39,5 +37,5 @@ class CompanyRevisionInfo:
     def _resolve_odxlinks(self, odxlinks: OdxLinkDatabase) -> None:
         self._company_data = odxlinks.resolve(self.company_data_ref, CompanyData)
 
-    def _resolve_snrefs(self, diag_layer: "DiagLayer") -> None:
+    def _resolve_snrefs(self, context: SnRefContext) -> None:
         pass

odxtools/companyspecificinfo.py

@@ -1,16 +1,13 @@
 # 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 .createsdgs import create_sdgs_from_et
 from .odxlink import OdxDocFragment, OdxLinkDatabase, OdxLinkId
 from .relateddoc import RelatedDoc
+from .snrefcontext import SnRefContext
 from .specialdatagroup import SpecialDataGroup
 
-if TYPE_CHECKING:
-    from .diaglayer import DiagLayer
-
 
 @dataclass
 class CompanySpecificInfo:
@@ -25,7 +22,9 @@ class CompanySpecificInfo:
             for rd in et_element.iterfind("RELATED-DOCS/RELATED-DOC")
         ]
 
-        sdgs = create_sdgs_from_et(et_element.find("SDGS"), doc_frags)
+        sdgs = [
+            SpecialDataGroup.from_et(sdge, doc_frags) for sdge in et_element.iterfind("SDGS/SDG")
+        ]
 
         return CompanySpecificInfo(related_docs=related_docs, sdgs=sdgs)
 
@@ -44,9 +43,9 @@ class CompanySpecificInfo:
         for sdg in self.sdgs:
             sdg._resolve_odxlinks(odxlinks)
 
-    def _resolve_snrefs(self, diag_layer: "DiagLayer") -> None:
+    def _resolve_snrefs(self, context: SnRefContext) -> None:
         for rd in self.related_docs:
-            rd._resolve_snrefs(diag_layer)
+            rd._resolve_snrefs(context)
 
         for sdg in self.sdgs:
-            sdg._resolve_snrefs(diag_layer)
+            sdg._resolve_snrefs(context)

odxtools/comparam.py

@@ -1,17 +1,15 @@
 # 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 .basecomparam import BaseComparam
 from .dataobjectproperty import DataObjectProperty
 from .exceptions import odxrequire
 from .odxlink import OdxDocFragment, OdxLinkDatabase, OdxLinkId, OdxLinkRef
+from .snrefcontext import SnRefContext
 from .utils import dataclass_fields_asdict
 
-if TYPE_CHECKING:
-    from .diaglayer import DiagLayer
-
 
 @dataclass
 class Comparam(BaseComparam):
@@ -41,5 +39,5 @@ class Comparam(BaseComparam):
 
         self._dop = odxlinks.resolve(self.dop_ref, DataObjectProperty)
 
-    def _resolve_snrefs(self, diag_layer: "DiagLayer") -> None:
-        super()._resolve_snrefs(diag_layer)
+    def _resolve_snrefs(self, context: SnRefContext) -> None:
+        super()._resolve_snrefs(context)

odxtools/comparaminstance.py

@@ -1,18 +1,16 @@
 # SPDX-License-Identifier: MIT
 import warnings
 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 .basecomparam import BaseComparam
 from .comparam import Comparam
 from .complexcomparam import ComplexComparam, ComplexValue, create_complex_value_from_et
-from .exceptions import OdxWarning, odxassert, odxraise, odxrequire
+from .description import Description
+from .exceptions import OdxWarning, odxraise, odxrequire
 from .odxlink import OdxDocFragment, OdxLinkDatabase, OdxLinkId, OdxLinkRef
-from .utils import create_description_from_et
-
-if TYPE_CHECKING:
-    from .diaglayer import DiagLayer
+from .snrefcontext import SnRefContext
 
 
 @dataclass
@@ -23,7 +21,7 @@ class ComparamInstance:
     Be aware that the ODX specification calls this class COMPARAM-REF!
     """
     value: Union[str, ComplexValue]
-    description: Optional[str]
+    description: Optional[Description]
     protocol_snref: Optional[str]
     prot_stack_snref: Optional[str]
     spec_ref: OdxLinkRef
@@ -34,7 +32,7 @@ class ComparamInstance:
         spec_ref = odxrequire(OdxLinkRef.from_et(et_element, doc_frags))
 
         # ODX standard v2.0.0 defined only VALUE. ODX v2.0.1 decided
-        # to break things and change it to choice between SIMPLE-VALUE
+        # to break things and change it to a choice between SIMPLE-VALUE
         # and COMPLEX-VALUE
         value: Union[str, List[Union[str, ComplexValue]]]
         if et_element.find("VALUE") is not None:
@@ -44,7 +42,7 @@ class ComparamInstance:
         else:
             value = create_complex_value_from_et(odxrequire(et_element.find("COMPLEX-VALUE")))
 
-        description = create_description_from_et(et_element.find("DESC"))
+        description = Description.from_et(et_element.find("DESC"), doc_frags)
 
         prot_stack_snref = None
         if (psnref_elem := et_element.find("PROT-STACK-SNREF")) is not None:
@@ -68,14 +66,14 @@ class ComparamInstance:
     def _resolve_odxlinks(self, odxlinks: OdxLinkDatabase) -> None:
         self._spec = odxlinks.resolve(self.spec_ref, BaseComparam)
 
-    def _resolve_snrefs(self, diag_layer: "DiagLayer") -> None:
+    def _resolve_snrefs(self, context: SnRefContext) -> None:
         pass
 
     @property
     def spec(self) -> BaseComparam:
         return self._spec
 
-    def get_value(self) -> Optional[str]:
+    def get_value(self) -> str:
         """Retrieve the value of a simple communication parameter
 
         This takes the default value of the comparam (if any) into
@@ -91,7 +89,8 @@ class ComparamInstance:
         else:
             result = self.spec.physical_default_value
 
-        odxassert(isinstance(result, str))
+        if not isinstance(result, str):
+            odxraise()
 
         return result
 
@@ -119,6 +118,7 @@ class ComparamInstance:
         name_list = [cp.short_name for cp in comparam_spec.subparams]
         try:
             idx = name_list.index(subparam_name)
+            subparam = comparam_spec.subparams[idx]
         except ValueError:
             warnings.warn(
                 f"Communication parameter '{self.short_name}' "
@@ -129,8 +129,8 @@ class ComparamInstance:
             return None
 
         result = value_list[idx]
-        if result is None:
-            result = comparam_spec.subparams[idx].physical_default_value
+        if result is None and isinstance(subparam, (Comparam, ComplexComparam)):
+            result = subparam.physical_default_value
         if not isinstance(result, str):
             odxraise()