odxtools 9.7.0__py3-none-any.whl → 10.1.0__py3-none-any.whl

odxtools/database.py

@@ -1,8 +1,9 @@
 # SPDX-License-Identifier: MIT
+from collections import OrderedDict
 from itertools import chain
 from os import PathLike
 from pathlib import Path
-from typing import IO, Any, Dict, List, Optional, OrderedDict, Union
+from typing import IO, Any, Union
 from xml.etree import ElementTree
 from zipfile import ZipFile
 
@@ -19,7 +20,8 @@ from .diaglayers.functionalgroup import FunctionalGroup
 from .diaglayers.protocol import Protocol
 from .exceptions import odxraise, odxrequire
 from .nameditemlist import NamedItemList
-from .odxlink import OdxLinkDatabase, OdxLinkId
+from .odxdoccontext import OdxDocContext
+from .odxlink import DocType, OdxDocFragment, OdxLinkDatabase, OdxLinkId
 from .snrefcontext import SnRefContext
 
 
@@ -30,7 +32,7 @@ class Database:
     """
 
     def __init__(self) -> None:
-        self.model_version: Optional[Version] = None
+        self.model_version: Version | None = None
         self.auxiliary_files: OrderedDict[str, IO[bytes]] = OrderedDict()
 
         # create an empty database object
@@ -68,17 +70,13 @@ class Database:
 
     def add_auxiliary_file(self,
                            aux_file_name: Union[str, "PathLike[Any]"],
-                           aux_file_obj: Optional[IO[bytes]] = None) -> None:
+                           aux_file_obj: IO[bytes] | None = None) -> None:
         if aux_file_obj is None:
             aux_file_obj = open(aux_file_name, "rb")
 
         self.auxiliary_files[str(aux_file_name)] = aux_file_obj
 
     def _process_xml_tree(self, root: ElementTree.Element) -> None:
-        dlcs: List[DiagLayerContainer] = []
-        comparam_subsets: List[ComparamSubset] = []
-        comparam_specs: List[ComparamSpec] = []
-
         # ODX spec version
         model_version = Version(root.attrib.get("MODEL-VERSION", "2.0"))
         if self.model_version is not None and self.model_version != model_version:
@@ -87,28 +85,33 @@ class Database:
 
         self.model_version = model_version
 
-        dlc = root.find("DIAG-LAYER-CONTAINER")
-        if dlc is not None:
-            dlcs.append(DiagLayerContainer.from_et(dlc, []))
-
-        # In ODX 2.0 there was only COMPARAM-SPEC. In ODX 2.2 the
-        # content of COMPARAM-SPEC was moved to COMPARAM-SUBSET
-        # and COMPARAM-SPEC became a container for PROT-STACKS and
-        # a PROT-STACK references a list of COMPARAM-SUBSET
-        cp_subset = root.find("COMPARAM-SUBSET")
-        if cp_subset is not None:
-            comparam_subsets.append(ComparamSubset.from_et(cp_subset, []))
-
-        cp_spec = root.find("COMPARAM-SPEC")
-        if cp_spec is not None:
+        child_elements = list(root)
+        if len(child_elements) != 1:
+            odxraise("Each ODX document must contain exactly one category.")
+
+        category_et = child_elements[0]
+        category_sn = odxrequire(category_et.findtext("SHORT-NAME"))
+        category_tag = category_et.tag
+
+        if category_tag == "DIAG-LAYER-CONTAINER":
+            context = OdxDocContext(model_version,
+                                    (OdxDocFragment(category_sn, DocType.CONTAINER),))
+            self._diag_layer_containers.append(DiagLayerContainer.from_et(category_et, context))
+        elif category_tag == "COMPARAM-SUBSET":
+            context = OdxDocContext(model_version,
+                                    (OdxDocFragment(category_sn, DocType.COMPARAM_SUBSET),))
+            self._comparam_subsets.append(ComparamSubset.from_et(category_et, context))
+        elif category_tag == "COMPARAM-SPEC":
+            # In ODX 2.0 there was only COMPARAM-SPEC. In ODX 2.2 the
+            # content of COMPARAM-SPEC was moved to COMPARAM-SUBSET
+            # and COMPARAM-SPEC became a container for PROT-STACKS and
+            # a PROT-STACK references a list of COMPARAM-SUBSET
+            context = OdxDocContext(model_version,
+                                    (OdxDocFragment(category_sn, DocType.COMPARAM_SPEC),))
             if model_version < Version("2.2"):
-                comparam_subsets.append(ComparamSubset.from_et(cp_spec, []))
-            else:  # odx >= 2.2
-                comparam_specs.append(ComparamSpec.from_et(cp_spec, []))
-
-        self._diag_layer_containers.extend(dlcs)
-        self._comparam_subsets.extend(comparam_subsets)
-        self._comparam_specs.extend(comparam_specs)
+                self._comparam_subsets.append(ComparamSubset.from_et(category_et, context))
+            else:
+                self._comparam_specs.append(ComparamSpec.from_et(category_et, context))
 
     def refresh(self) -> None:
         # Create wrapper objects
@@ -160,8 +163,8 @@ class Database:
         for dlc in self.diag_layer_containers:
             dlc._resolve_snrefs(context)
 
-    def _build_odxlinks(self) -> Dict[OdxLinkId, Any]:
-        result: Dict[OdxLinkId, Any] = {}
+    def _build_odxlinks(self) -> dict[OdxLinkId, Any]:
+        result: dict[OdxLinkId, Any] = {}
 
         for subset in self.comparam_subsets:
             result.update(subset._build_odxlinks())

odxtools/dataobjectproperty.py

@@ -1,6 +1,6 @@
 # SPDX-License-Identifier: MIT
 from dataclasses import dataclass
-from typing import Any, Dict, List, Optional, cast
+from typing import Any, cast
 from xml.etree import ElementTree
 
 from .compumethods.compumethod import CompuMethod
@@ -12,7 +12,8 @@ from .dopbase import DopBase
 from .encodestate import EncodeState
 from .exceptions import EncodeError, odxraise, odxrequire
 from .internalconstr import InternalConstr
-from .odxlink import OdxDocFragment, OdxLinkDatabase, OdxLinkId, OdxLinkRef
+from .odxdoccontext import OdxDocContext
+from .odxlink import OdxLinkDatabase, OdxLinkId, OdxLinkRef
 from .odxtypes import AtomicOdxType, BytesTypes, ParameterValue
 from .physicaltype import PhysicalType
 from .snrefcontext import SnRefContext
@@ -20,7 +21,7 @@ from .unit import Unit
 from .utils import dataclass_fields_asdict
 
 
-@dataclass
+@dataclass(kw_only=True)
 class DataObjectProperty(DopBase):
     """This class represents a DATA-OBJECT-PROP.
 
@@ -37,42 +38,40 @@ class DataObjectProperty(DopBase):
     #: The type of the value in the physical world
     physical_type: PhysicalType
 
-    internal_constr: Optional[InternalConstr]
+    internal_constr: InternalConstr | None = None
 
     #: The unit associated with physical values (e.g. 'm/s^2')
-    unit_ref: Optional[OdxLinkRef]
+    unit_ref: OdxLinkRef | None = None
 
-    physical_constr: Optional[InternalConstr]
+    physical_constr: InternalConstr | None = None
 
     @property
-    def unit(self) -> Optional[Unit]:
+    def unit(self) -> Unit | None:
         return self._unit
 
     @staticmethod
-    def from_et(et_element: ElementTree.Element,
-                doc_frags: List[OdxDocFragment]) -> "DataObjectProperty":
+    def from_et(et_element: ElementTree.Element, context: OdxDocContext) -> "DataObjectProperty":
         """Reads a DATA-OBJECT-PROP."""
-        kwargs = dataclass_fields_asdict(DopBase.from_et(et_element, doc_frags))
+        kwargs = dataclass_fields_asdict(DopBase.from_et(et_element, context))
 
         diag_coded_type = create_any_diag_coded_type_from_et(
-            odxrequire(et_element.find("DIAG-CODED-TYPE")), doc_frags)
-        physical_type = PhysicalType.from_et(
-            odxrequire(et_element.find("PHYSICAL-TYPE")), doc_frags)
+            odxrequire(et_element.find("DIAG-CODED-TYPE")), context)
+        physical_type = PhysicalType.from_et(odxrequire(et_element.find("PHYSICAL-TYPE")), context)
         compu_method = create_any_compu_method_from_et(
             odxrequire(et_element.find("COMPU-METHOD")),
-            doc_frags,
+            context,
             internal_type=diag_coded_type.base_data_type,
             physical_type=physical_type.base_data_type,
         )
         internal_constr = None
         if (internal_constr_elem := et_element.find("INTERNAL-CONSTR")) is not None:
             internal_constr = InternalConstr.constr_from_et(
-                internal_constr_elem, doc_frags, value_type=diag_coded_type.base_data_type)
-        unit_ref = OdxLinkRef.from_et(et_element.find("UNIT-REF"), doc_frags)
+                internal_constr_elem, context, value_type=diag_coded_type.base_data_type)
+        unit_ref = OdxLinkRef.from_et(et_element.find("UNIT-REF"), context)
         physical_constr = None
         if (physical_constr_elem := et_element.find("PHYS-CONSTR")) is not None:
             physical_constr = InternalConstr.constr_from_et(
-                physical_constr_elem, doc_frags, value_type=physical_type.base_data_type)
+                physical_constr_elem, context, value_type=physical_type.base_data_type)
 
         return DataObjectProperty(
             compu_method=compu_method,
@@ -83,7 +82,7 @@ class DataObjectProperty(DopBase):
             physical_constr=physical_constr,
             **kwargs)
 
-    def _build_odxlinks(self) -> Dict[OdxLinkId, Any]:
+    def _build_odxlinks(self) -> dict[OdxLinkId, Any]:
         result = super()._build_odxlinks()
         result.update(self.compu_method._build_odxlinks())
         result.update(self.diag_coded_type._build_odxlinks())
@@ -96,7 +95,7 @@ class DataObjectProperty(DopBase):
         self.compu_method._resolve_odxlinks(odxlinks)
         self.diag_coded_type._resolve_odxlinks(odxlinks)
 
-        self._unit: Optional[Unit] = None
+        self._unit: Unit | None = None
         if self.unit_ref:
             self._unit = odxlinks.resolve(self.unit_ref, Unit)
 
@@ -106,7 +105,7 @@ class DataObjectProperty(DopBase):
         self.compu_method._resolve_snrefs(context)
         self.diag_coded_type._resolve_snrefs(context)
 
-    def get_static_bit_length(self) -> Optional[int]:
+    def get_static_bit_length(self) -> int | None:
         return self.diag_coded_type.get_static_bit_length()
 
     def encode_into_pdu(self, physical_value: ParameterValue, encode_state: EncodeState) -> None:

odxtools/decodestate.py

@@ -1,6 +1,6 @@
 # SPDX-License-Identifier: MIT
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Dict, List, Optional, Tuple
+from typing import TYPE_CHECKING
 
 from .encoding import Encoding, get_string_encoding
 from .exceptions import DecodeError, odxassert, odxraise, strict_mode
@@ -41,22 +41,22 @@ class DecodeState:
     cursor_bit_position: int = 0
 
     #: values of the length key parameters decoded so far
-    length_keys: Dict[str, int] = field(default_factory=dict)
+    length_keys: dict[str, int] = field(default_factory=dict)
 
     #: values of the table key parameters decoded so far
-    table_keys: Dict[str, "TableRow"] = field(default_factory=dict)
+    table_keys: dict[str, "TableRow"] = field(default_factory=dict)
 
     #: List of parameters that have been decoded so far. The journal
     #: is used by some types of parameters which depend on the values of
     #: other parameters; i.e., environment data description parameters
-    journal: List[Tuple["Parameter", Optional[ParameterValue]]] = field(default_factory=list)
+    journal: list[tuple["Parameter", ParameterValue | None]] = field(default_factory=list)
 
     def extract_atomic_value(
         self,
         *,
         bit_length: int,
         base_data_type: DataType,
-        base_type_encoding: Optional[Encoding],
+        base_type_encoding: Encoding | None,
         is_highlow_byte_order: bool,
     ) -> AtomicOdxType:
         """Extract an internal value from a blob of raw bytes.

odxtools/description.py

@@ -1,22 +1,22 @@
-from dataclasses import dataclass
-from typing import List, Optional
+from dataclasses import dataclass, field
+from typing import Optional
 from xml.etree import ElementTree
 
 from .exceptions import odxrequire
 from .externaldoc import ExternalDoc
-from .odxlink import OdxDocFragment
+from .odxdoccontext import OdxDocContext
 
 
-@dataclass
+@dataclass(kw_only=True)
 class Description:
     text: str
-    external_docs: List[ExternalDoc]
+    external_docs: list[ExternalDoc] = field(default_factory=list)
 
-    text_identifier: Optional[str]
+    text_identifier: str | None = None
 
     @staticmethod
-    def from_et(et_element: Optional[ElementTree.Element],
-                doc_frags: List[OdxDocFragment]) -> Optional["Description"]:
+    def from_et(et_element: ElementTree.Element | None,
+                context: OdxDocContext) -> Optional["Description"]:
         if et_element is None:
             return None
 
@@ -35,7 +35,7 @@ class Description:
 
         external_docs = \
             [
-                odxrequire(ExternalDoc.from_et(ed, doc_frags)) for ed in et_element.iterfind("EXTERNAL-DOCS/EXTERNAL-DOC")
+                odxrequire(ExternalDoc.from_et(ed, context)) for ed in et_element.iterfind("EXTERNAL-DOCS/EXTERNAL-DOC")
             ]
 
         text_identifier = et_element.attrib.get("TI")

odxtools/determinenumberofitems.py

@@ -1,21 +1,22 @@
 # SPDX-License-Identifier: MIT
 from dataclasses import dataclass
-from typing import Any, Dict, List, Optional
+from typing import Any
 from xml.etree import ElementTree
 
 from .dataobjectproperty import DataObjectProperty
 from .exceptions import odxrequire
-from .odxlink import OdxDocFragment, OdxLinkDatabase, OdxLinkId, OdxLinkRef
+from .odxdoccontext import OdxDocContext
+from .odxlink import OdxLinkDatabase, OdxLinkId, OdxLinkRef
 from .snrefcontext import SnRefContext
 
 
-@dataclass
+@dataclass(kw_only=True)
 class DetermineNumberOfItems:
     """
     The object that determines the number of items of dynamic fields
     """
     byte_position: int
-    bit_position: Optional[int]
+    bit_position: int | None = None
     dop_ref: OdxLinkRef
 
     @property
@@ -24,11 +25,11 @@ class DetermineNumberOfItems:
 
     @staticmethod
     def from_et(et_element: ElementTree.Element,
-                doc_frags: List[OdxDocFragment]) -> "DetermineNumberOfItems":
+                context: OdxDocContext) -> "DetermineNumberOfItems":
         byte_position = int(odxrequire(et_element.findtext("BYTE-POSITION")))
         bit_position_str = et_element.findtext("BIT-POSITION")
         bit_position = int(bit_position_str) if bit_position_str is not None else None
-        dop_ref = odxrequire(OdxLinkRef.from_et(et_element.find("DATA-OBJECT-PROP-REF"), doc_frags))
+        dop_ref = odxrequire(OdxLinkRef.from_et(et_element.find("DATA-OBJECT-PROP-REF"), context))
 
         return DetermineNumberOfItems(
             byte_position=byte_position,
@@ -36,7 +37,7 @@ class DetermineNumberOfItems:
             dop_ref=dop_ref,
         )
 
-    def _build_odxlinks(self) -> Dict[OdxLinkId, Any]:
+    def _build_odxlinks(self) -> dict[OdxLinkId, Any]:
         return {}
 
     def _resolve_odxlinks(self, odxlinks: OdxLinkDatabase) -> None:

odxtools/diagcodedtype.py

@@ -1,13 +1,14 @@
 # SPDX-License-Identifier: MIT
 from dataclasses import dataclass
-from typing import Any, Dict, List, Literal, Optional, Union, cast
+from typing import Any, Literal, cast
 from xml.etree import ElementTree
 
 from .decodestate import DecodeState
 from .encodestate import EncodeState
 from .encoding import Encoding
 from .exceptions import odxassert, odxraise, odxrequire
-from .odxlink import OdxDocFragment, OdxLinkDatabase, OdxLinkId
+from .odxdoccontext import OdxDocContext
+from .odxlink import OdxLinkDatabase, OdxLinkId
 from .odxtypes import AtomicOdxType, DataType, odxstr_to_bool
 from .snrefcontext import SnRefContext
 
@@ -20,12 +21,12 @@ DctType = Literal[
 ]
 
 
-@dataclass
+@dataclass(kw_only=True)
 class DiagCodedType:
-    base_type_encoding: Optional[Encoding]
+    base_type_encoding: Encoding | None = None
     base_data_type: DataType
 
-    is_highlow_byte_order_raw: Optional[bool]
+    is_highlow_byte_order_raw: bool | None = None
 
     @property
     def dct_type(self) -> DctType:
@@ -38,8 +39,7 @@ class DiagCodedType:
         return self.is_highlow_byte_order_raw in [None, True]
 
     @staticmethod
-    def from_et(et_element: ElementTree.Element,
-                doc_frags: List[OdxDocFragment]) -> "DiagCodedType":
+    def from_et(et_element: ElementTree.Element, context: OdxDocContext) -> "DiagCodedType":
         base_type_encoding = None
         if (base_type_encoding_str := et_element.get("BASE-TYPE-ENCODING")) is not None:
             try:
@@ -61,7 +61,7 @@ class DiagCodedType:
             base_data_type=base_data_type,
             is_highlow_byte_order_raw=is_highlow_byte_order_raw)
 
-    def _build_odxlinks(self) -> Dict[OdxLinkId, Any]:  # noqa: B027
+    def _build_odxlinks(self) -> dict[OdxLinkId, Any]:  # noqa: B027
         return {}
 
     def _resolve_odxlinks(self, odxlinks: OdxLinkDatabase) -> None:  # noqa: B027
@@ -72,10 +72,10 @@ class DiagCodedType:
         """Recursively resolve any short-name references"""
         pass
 
-    def get_static_bit_length(self) -> Optional[int]:
+    def get_static_bit_length(self) -> int | None:
         return None
 
-    def _minimal_byte_length_of(self, internal_value: Union[bytes, str]) -> int:
+    def _minimal_byte_length_of(self, internal_value: bytes | str) -> int:
         """Helper method to get the minimal byte length.
         (needed for LeadingLength- and MinMaxLengthType)
         """

odxtools/diagcomm.py

@@ -1,6 +1,6 @@
 # SPDX-License-Identifier: MIT
-from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Dict, List, Optional
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
 from xml.etree import ElementTree
 
 from .admindata import AdminData
@@ -10,7 +10,8 @@ from .element import IdentifiableElement
 from .exceptions import odxraise, odxrequire
 from .functionalclass import FunctionalClass
 from .nameditemlist import NamedItemList
-from .odxlink import OdxDocFragment, OdxLinkDatabase, OdxLinkId, OdxLinkRef, resolve_snref
+from .odxdoccontext import OdxDocContext
+from .odxlink import OdxLinkDatabase, OdxLinkId, OdxLinkRef, resolve_snref
 from .odxtypes import odxstr_to_bool
 from .preconditionstateref import PreConditionStateRef
 from .relateddiagcommref import RelatedDiagCommRef
@@ -25,7 +26,7 @@ if TYPE_CHECKING:
     from .diaglayers.protocol import Protocol
 
 
-@dataclass
+@dataclass(kw_only=True)
 class DiagComm(IdentifiableElement):
     """Representation of a diagnostic communication object.
 
@@ -34,21 +35,21 @@ class DiagComm(IdentifiableElement):
 
     """
 
-    admin_data: Optional[AdminData]
-    sdgs: List[SpecialDataGroup]
-    functional_class_refs: List[OdxLinkRef]
-    audience: Optional[Audience]
-    protocol_snrefs: List[str]
-    related_diag_comm_refs: List[RelatedDiagCommRef]
-    pre_condition_state_refs: List[PreConditionStateRef]
-    state_transition_refs: List[StateTransitionRef]
+    admin_data: AdminData | None = None
+    sdgs: list[SpecialDataGroup] = field(default_factory=list)
+    functional_class_refs: list[OdxLinkRef] = field(default_factory=list)
+    audience: Audience | None = None
+    protocol_snrefs: list[str] = field(default_factory=list)
+    related_diag_comm_refs: list[RelatedDiagCommRef] = field(default_factory=list)
+    pre_condition_state_refs: list[PreConditionStateRef] = field(default_factory=list)
+    state_transition_refs: list[StateTransitionRef] = field(default_factory=list)
 
     # attributes
-    semantic: Optional[str]
-    diagnostic_class: Optional[DiagClassType]
-    is_mandatory_raw: Optional[bool]
-    is_executable_raw: Optional[bool]
-    is_final_raw: Optional[bool]
+    semantic: str | None = None
+    diagnostic_class: DiagClassType | None = None
+    is_mandatory_raw: bool | None = None
+    is_executable_raw: bool | None = None
+    is_final_raw: bool | None = None
 
     @property
     def functional_classes(self) -> NamedItemList[FunctionalClass]:
@@ -83,22 +84,20 @@ class DiagComm(IdentifiableElement):
         return self.is_final_raw is True
 
     @staticmethod
-    def from_et(et_element: ElementTree.Element, doc_frags: List[OdxDocFragment]) -> "DiagComm":
-        kwargs = dataclass_fields_asdict(IdentifiableElement.from_et(et_element, doc_frags))
+    def from_et(et_element: ElementTree.Element, context: OdxDocContext) -> "DiagComm":
+        kwargs = dataclass_fields_asdict(IdentifiableElement.from_et(et_element, context))
 
-        admin_data = AdminData.from_et(et_element.find("ADMIN-DATA"), doc_frags)
-        sdgs = [
-            SpecialDataGroup.from_et(sdge, doc_frags) for sdge in et_element.iterfind("SDGS/SDG")
-        ]
+        admin_data = AdminData.from_et(et_element.find("ADMIN-DATA"), context)
+        sdgs = [SpecialDataGroup.from_et(sdge, context) for sdge in et_element.iterfind("SDGS/SDG")]
 
         functional_class_refs = [
-            odxrequire(OdxLinkRef.from_et(el, doc_frags))
+            odxrequire(OdxLinkRef.from_et(el, context))
             for el in et_element.iterfind("FUNCT-CLASS-REFS/FUNCT-CLASS-REF")
         ]
 
         audience = None
         if (audience_elem := et_element.find("AUDIENCE")) is not None:
-            audience = Audience.from_et(audience_elem, doc_frags)
+            audience = Audience.from_et(audience_elem, context)
 
         protocol_snrefs = [
             odxrequire(el.get("SHORT-NAME"))
@@ -106,23 +105,23 @@ class DiagComm(IdentifiableElement):
         ]
 
         related_diag_comm_refs = [
-            RelatedDiagCommRef.from_et(el, doc_frags)
+            RelatedDiagCommRef.from_et(el, context)
             for el in et_element.iterfind("RELATED-DIAG-COMM-REFS/RELATED-DIAG-COMM-REF")
         ]
 
         pre_condition_state_refs = [
-            PreConditionStateRef.from_et(el, doc_frags)
+            PreConditionStateRef.from_et(el, context)
             for el in et_element.iterfind("PRE-CONDITION-STATE-REFS/PRE-CONDITION-STATE-REF")
         ]
 
         state_transition_refs = [
-            StateTransitionRef.from_et(el, doc_frags)
+            StateTransitionRef.from_et(el, context)
             for el in et_element.iterfind("STATE-TRANSITION-REFS/STATE-TRANSITION-REF")
         ]
 
         semantic = et_element.attrib.get("SEMANTIC")
 
-        diagnostic_class: Optional[DiagClassType] = None
+        diagnostic_class: DiagClassType | None = None
         if (diagnostic_class_str := et_element.attrib.get("DIAGNOSTIC-CLASS")) is not None:
             try:
                 diagnostic_class = DiagClassType(diagnostic_class_str)
@@ -149,7 +148,7 @@ class DiagComm(IdentifiableElement):
             is_final_raw=is_final_raw,
             **kwargs)
 
-    def _build_odxlinks(self) -> Dict[OdxLinkId, Any]:
+    def _build_odxlinks(self) -> dict[OdxLinkId, Any]:
         result = {self.odx_id: self}
 
         if self.admin_data is not None: