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

odxtools/nameditemlist.py

@@ -1,14 +1,16 @@
 # SPDX-License-Identifier: MIT
 import abc
+import typing
+from copy import deepcopy
 from keyword import iskeyword
-from typing import (Any, Collection, Dict, Iterable, List, Optional, Protocol, SupportsIndex, Tuple,
-                    TypeVar, Union, cast, overload, runtime_checkable)
+from typing import (Any, Collection, Dict, Iterable, List, Optional, SupportsIndex, Tuple, TypeVar,
+                    Union, cast, overload, runtime_checkable)
 
 from .exceptions import odxraise
 
 
 @runtime_checkable
-class OdxNamed(Protocol):
+class OdxNamed(typing.Protocol):
 
     @property
     def short_name(self) -> str:
@@ -139,8 +141,7 @@ class ItemAttributeList(List[T]):
     def __getitem__(self, key: slice) -> List[T]:
         ...
 
-    def __getitem__(  # type: ignore
-            self, key: Union[SupportsIndex, str, slice]) -> Union[T, List[T]]:
+    def __getitem__(self, key: Union[SupportsIndex, str, slice]) -> Union[T, List[T]]:
         if isinstance(key, (SupportsIndex, slice)):
             return super().__getitem__(key)
         else:
@@ -175,6 +176,29 @@ class ItemAttributeList(List[T]):
     def __repr__(self) -> str:
         return f"{type(self).__name__}([{', '.join([repr(x) for x in self])}])"
 
+    def __copy__(self) -> Any:
+        return self.__class__(list(self))
+
+    def __deepcopy__(self, memo: Dict[int, Any]) -> Any:
+        cls = self.__class__
+        result = cls.__new__(cls)
+        memo[id(self)] = result
+        result._item_dict = {}
+        for x in self:
+            result.append(deepcopy(x, memo))
+
+        return result
+
+    def __reduce__(self) -> Tuple[Any, ...]:
+        """Support for Python's pickle protocol.
+        This method ensures that the object can be reconstructed with its current state,
+        using its class and the list of items it contains.
+        It returns a tuple containing the reconstruction function (the class)
+        and its arguments necessary to recreate the object.
+
+        """
+        return self.__class__, (list(self),)
+
 
 class NamedItemList(ItemAttributeList[T]):
 

odxtools/negoutputparam.py

@@ -1,17 +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 .dopbase import DopBase
 from .element import NamedElement
 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 NegOutputParam(NamedElement):
@@ -35,7 +33,7 @@ class NegOutputParam(NamedElement):
     def _resolve_odxlinks(self, odxlinks: OdxLinkDatabase) -> None:
         self._dop = odxlinks.resolve(self.dop_base_ref)
 
-    def _resolve_snrefs(self, diag_layer: "DiagLayer") -> None:
+    def _resolve_snrefs(self, context: SnRefContext) -> None:
         pass
 
     @property

odxtools/odxcategory.py

@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: MIT
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+from xml.etree import ElementTree
+
+from .admindata import AdminData
+from .companydata import CompanyData
+from .element import IdentifiableElement
+from .exceptions import odxrequire
+from .nameditemlist import NamedItemList
+from .odxlink import OdxDocFragment, OdxLinkDatabase, OdxLinkId
+from .snrefcontext import SnRefContext
+from .specialdatagroup import SpecialDataGroup
+from .utils import dataclass_fields_asdict
+
+if TYPE_CHECKING:
+    from .database import Database
+
+
+@dataclass
+class OdxCategory(IdentifiableElement):
+    """This is the base class for all top-level container classes in ODX"""
+
+    admin_data: Optional[AdminData]
+    company_datas: NamedItemList[CompanyData]
+    sdgs: List[SpecialDataGroup]
+
+    @staticmethod
+    def from_et(et_element: ElementTree.Element, doc_frags: List[OdxDocFragment]) -> "OdxCategory":
+        raise Exception("Calling `._from_et()` is not allowed for OdxCategory. "
+                        "Use `OdxCategory.category_from_et()`!")
+
+    @staticmethod
+    def category_from_et(et_element: ElementTree.Element, doc_frags: List[OdxDocFragment], *,
+                         doc_type: str) -> "OdxCategory":
+
+        short_name = odxrequire(et_element.findtext("SHORT-NAME"))
+        # create the current ODX "document fragment" (description of the
+        # current document for references and IDs)
+        doc_frags = [OdxDocFragment(short_name, doc_type)]
+        kwargs = dataclass_fields_asdict(IdentifiableElement.from_et(et_element, doc_frags))
+
+        admin_data = AdminData.from_et(et_element.find("ADMIN-DATA"), doc_frags)
+        company_datas = NamedItemList([
+            CompanyData.from_et(cde, doc_frags)
+            for cde in et_element.iterfind("COMPANY-DATAS/COMPANY-DATA")
+        ])
+        sdgs = [
+            SpecialDataGroup.from_et(sdge, doc_frags) for sdge in et_element.iterfind("SDGS/SDG")
+        ]
+
+        return OdxCategory(admin_data=admin_data, company_datas=company_datas, 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 cd in self.company_datas:
+            result.update(cd._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 cd in self.company_datas:
+            cd._resolve_odxlinks(odxlinks)
+        for sdg in self.sdgs:
+            sdg._resolve_odxlinks(odxlinks)
+
+    def _finalize_init(self, database: "Database", odxlinks: OdxLinkDatabase) -> None:
+        pass
+
+    def _resolve_snrefs(self, context: SnRefContext) -> None:
+        if self.admin_data is not None:
+            self.admin_data._resolve_snrefs(context)
+        for cd in self.company_datas:
+            cd._resolve_snrefs(context)
+        for sdg in self.sdgs:
+            sdg._resolve_snrefs(context)

odxtools/odxlink.py

@@ -1,32 +1,17 @@
 # SPDX-License-Identifier: MIT
 import warnings
 from dataclasses import dataclass
-from typing import Any, Dict, List, Optional, Type, TypeVar, overload
+from typing import Any, Dict, Iterable, List, Optional, Type, TypeVar, overload
 from xml.etree import ElementTree
 
-from .exceptions import OdxWarning, odxassert
+from .exceptions import OdxWarning, odxassert, odxraise, odxrequire
+from .nameditemlist import OdxNamed, TNamed
 
 
 @dataclass(frozen=True)
 class OdxDocFragment:
     doc_name: str
-    doc_type: Optional[str]
-
-    def __eq__(self, other: Any) -> bool:
-        if other is None:
-            # if the other document fragment is not specified, we
-            # treat it as a wildcard...
-            return True
-
-        if not isinstance(other, OdxDocFragment):
-            return False
-
-        # the ODX spec says that the doctype can be ignored...
-        return self.doc_name == other.doc_name
-
-    def __hash__(self) -> int:
-        # only the document name is relevant for the hash value
-        return hash(self.doc_name) + hash(self.doc_type)
+    doc_type: str
 
 
 @dataclass(frozen=True)
@@ -58,10 +43,12 @@ class OdxLinkId:
         if not isinstance(other, OdxLinkId):
             return False
 
-        # we do take the document fragment into consideration here, because
-        # document fragments are handled using separate sub-databases,
-        # i.e. the same OdxId object can be put into all of them.
-        return self.local_id == other.local_id
+        # if the local ID is different, the whole id is different
+        if self.local_id != other.local_id:
+            return False
+
+        # the document fragments must be identical for the IDs to be identical
+        return self.doc_fragments == other.doc_fragments
 
     def __str__(self) -> str:
         return f"OdxLinkId('{self.local_id}')"
@@ -119,6 +106,7 @@ class OdxLinkRef:
 
         id_ref = et.attrib.get("ID-REF")
         if id_ref is None:
+            odxraise(f"Tag {et.tag} is not a ODXLINK reference")
             return None
 
         doc_ref = et.attrib.get("DOCREF")
@@ -132,7 +120,7 @@ class OdxLinkRef:
         # reference, use it, else use the document fragment containing
         # the reference.
         if doc_ref is not None:
-            doc_frags = [OdxDocFragment(doc_ref, doc_type)]
+            doc_frags = [OdxDocFragment(doc_ref, odxrequire(doc_type))]
         else:
             doc_frags = source_doc_frags
 
@@ -146,32 +134,19 @@ class OdxLinkRef:
     def __str__(self) -> str:
         return f"OdxLinkRef('{self.ref_id}')"
 
-    def __contains__(self, odx_id: OdxLinkId) -> bool:
-        """
-        Returns true iff a given OdxLinkId object is referenced.
-        """
-
-        # we must reference at to at least of the ID's document
-        # fragments
-        if not any(ref_doc in odx_id.doc_fragments for ref_doc in self.ref_docs):
-            return False
-
-        # the local ID of the reference and the object ID must match
-        return odx_id.local_id == self.ref_id
-
 
 T = TypeVar("T")
 
 
 class OdxLinkDatabase:
     """
-    A database holding all objects which ehibit OdxLinkIds
+    A database holding all objects which exhibit OdxLinkIds
 
-    This can resolve references to such.
+    This can resolve ODXLINK references.
     """
 
     def __init__(self) -> None:
-        self._db: Dict[OdxDocFragment, Dict[OdxLinkId, Any]] = {}
+        self._db: Dict[OdxDocFragment, Dict[str, Any]] = {}
 
     @overload
     def resolve(self, ref: OdxLinkRef, expected_type: None = None) -> Any:
@@ -188,13 +163,12 @@ class OdxLinkDatabase:
         If the database does not contain any object which is referred to, a
         KeyError exception is raised.
         """
-        odx_id = OdxLinkId(ref.ref_id, ref.ref_docs)
         for ref_frag in reversed(ref.ref_docs):
             doc_frag_db = self._db.get(ref_frag)
             if doc_frag_db is None:
                 # No object featured by the database uses the document
                 # fragment mentioned by the reference. This should not
-                # happen for correct databases...
+                # happen for correct ODX databases...
                 warnings.warn(
                     f"Warning: Unknown document fragment {ref_frag} "
                     f"when resolving reference {ref}",
@@ -203,15 +177,18 @@ class OdxLinkDatabase:
                 )
                 continue
 
-            obj = doc_frag_db.get(odx_id)
-            if obj is not None:
+            # locate an object exhibiting with the referenced local ID
+            # in the ID database for the document fragment
+            if (obj := doc_frag_db.get(ref.ref_id)) is not None:
                 if expected_type is not None:
                     odxassert(isinstance(obj, expected_type))
 
                 return obj
 
-        raise KeyError(f"ODXLINK reference {ref} could not be resolved for any "
-                       f"of the document fragments {ref.ref_docs}")
+        odxraise(
+            f"ODXLINK reference {ref} could not be resolved for any "
+            f"of the document fragments {ref.ref_docs}", KeyError)
+        return None
 
     @overload
     def resolve_lenient(self, ref: OdxLinkRef, expected_type: None = None) -> Any:
@@ -231,7 +208,6 @@ class OdxLinkDatabase:
         is returned.
         """
 
-        odx_id = OdxLinkId(ref.ref_id, ref.ref_docs)
         for ref_frag in reversed(ref.ref_docs):
             doc_frag_db = self._db.get(ref_frag)
             if doc_frag_db is None:
@@ -246,8 +222,7 @@ class OdxLinkDatabase:
                 )
                 continue
 
-            obj = doc_frag_db.get(odx_id)
-            if obj is not None:
+            if (obj := doc_frag_db.get(ref.ref_id)) is not None:
                 if expected_type is not None:
                     odxassert(isinstance(obj, expected_type))
 
@@ -255,7 +230,7 @@ class OdxLinkDatabase:
 
         return None
 
-    def update(self, new_entries: Dict[OdxLinkId, Any]) -> None:
+    def update(self, new_entries: Dict[OdxLinkId, Any], *, overwrite: bool = True) -> None:
         """
         Add a bunch of new objects to the ODXLINK database.
 
@@ -269,4 +244,38 @@ class OdxLinkDatabase:
                 if doc_frag not in self._db:
                     self._db[doc_frag] = {}
 
-                self._db[doc_frag][odx_id] = obj
+                if overwrite:
+                    self._db[doc_frag][odx_id.local_id] = obj
+                else:
+                    self._db[doc_frag].setdefault(odx_id.local_id, obj)
+
+
+@overload
+def resolve_snref(target_short_name: str,
+                  items: Iterable[OdxNamed],
+                  expected_type: None = None) -> Any:
+    """Resolve a short name reference given a sequence of candidate objects"""
+    ...
+
+
+@overload
+def resolve_snref(target_short_name: str, items: Iterable[OdxNamed],
+                  expected_type: Type[TNamed]) -> TNamed:
+    ...
+
+
+def resolve_snref(target_short_name: str,
+                  items: Iterable[OdxNamed],
+                  expected_type: Any = None) -> Any:
+    candidates = [x for x in items if x.short_name == target_short_name]
+
+    if not candidates:
+        odxraise(f"Cannot resolve short name reference to '{target_short_name}'")
+        return None
+    elif len(candidates) > 1:
+        odxraise(f"Cannot uniquely resolve short name reference to '{target_short_name}'")
+    elif expected_type is not None and not isinstance(candidates[0], expected_type):
+        odxraise(f"Reference '{target_short_name}' points to a {type(candidates[0]).__name__}"
+                 f"object while expecting {expected_type.__name__}")
+
+    return candidates[0]

odxtools/odxtypes.py

@@ -1,6 +1,7 @@
 # SPDX-License-Identifier: MIT
 from enum import Enum
-from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Tuple, Type, Union, overload
+from typing import (TYPE_CHECKING, Any, Callable, Dict, Iterable, Optional, Tuple, Type, Union,
+                    overload)
 from xml.etree import ElementTree
 
 from .exceptions import odxassert, odxraise, odxrequire
@@ -28,7 +29,7 @@ ParameterDict = Dict[str, Union["Parameter", "ParameterDict"]]
 # multiple items, so this can be a list of objects.
 TableStructParameterValue = Tuple[str, "ParameterValue"]
 ParameterValue = Union[AtomicOdxType, "ParameterValueDict", TableStructParameterValue,
-                       List["ParameterValue"], "DiagnosticTroubleCode"]
+                       Iterable["ParameterValue"], "DiagnosticTroubleCode"]
 ParameterValueDict = Dict[str, ParameterValue]
 
 
@@ -63,8 +64,8 @@ def bool_to_odxstr(bool_val: bool) -> str:
 
 def parse_int(value: str) -> int:
     try:
-        return int(value)
-    except ValueError:
+        return int(value, 0)
+    except (ValueError, TypeError):
         try:
             v = float(value)
         except Exception as e:
@@ -154,6 +155,19 @@ def compare_odx_values(a: AtomicOdxType, b: AtomicOdxType) -> int:
              f"and {type(b).__name__}")
 
 
+# format specifiers for the data type using the bitstruct module
+_BITSTRUCT_FORMAT_LETTER_MAP__ = {
+    "A_INT32": "s",
+    "A_UINT32": "u",
+    "A_FLOAT32": "f",
+    "A_FLOAT64": "f",
+    "A_BYTEFIELD": "r",
+    "A_UNICODE2STRING": "r",  # UTF-16 strings must be converted explicitly
+    "A_ASCIISTRING": "r",
+    "A_UTF8STRING": "r",
+}
+
+
 class DataType(Enum):
     """Types for the physical and internal value.
 
@@ -181,6 +195,10 @@ class DataType(Enum):
     def python_type(self) -> Type[AtomicOdxType]:
         return _ODX_TYPE_TO_PYTHON_TYPE[self.value]
 
+    @property
+    def bitstruct_format_letter(self) -> str:
+        return _BITSTRUCT_FORMAT_LETTER_MAP__[self.value]
+
     def from_string(self, value: str) -> AtomicOdxType:
         return _PARSE_ODX_TYPE[self.value](value)
 
@@ -217,9 +235,23 @@ class DataType(Enum):
         expected_type = self.python_type
         if isinstance(value, expected_type):
             return True
-        elif expected_type == float and isinstance(value, (int, float)):
+        elif expected_type is float and isinstance(value, (int, float)):
             return True
         elif self == DataType.A_BYTEFIELD and isinstance(value, (bytearray, bytes)):
             return True
         else:
             return False
+
+    def __str__(self) -> str:
+        if self == DataType.A_INT32:
+            return "int"
+        elif self == DataType.A_UINT32:
+            return "uint"
+        elif self in (DataType.A_FLOAT32, DataType.A_FLOAT64):
+            return "float"
+        elif self == DataType.A_BYTEFIELD:
+            return "bytefield"
+        elif self in (DataType.A_UNICODE2STRING, DataType.A_ASCIISTRING, DataType.A_UTF8STRING):
+            return "string"
+        else:
+            return f"<unknown type '{self.value}'>"

odxtools/outputparam.py

@@ -1,24 +1,19 @@
 # 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 deprecation import deprecated
-
 from .dopbase import DopBase
 from .element import IdentifiableElement
 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 OutputParam(IdentifiableElement):
     dop_base_ref: OdxLinkRef
-    oid: Optional[str]
     semantic: Optional[str]
 
     @staticmethod
@@ -27,9 +22,8 @@ class OutputParam(IdentifiableElement):
         kwargs = dataclass_fields_asdict(IdentifiableElement.from_et(et_element, doc_frags))
         dop_base_ref = odxrequire(OdxLinkRef.from_et(et_element.find("DOP-BASE-REF"), doc_frags))
         semantic = et_element.get("SEMANTIC")
-        oid = et_element.get("OID")
 
-        return OutputParam(dop_base_ref=dop_base_ref, semantic=semantic, oid=oid, **kwargs)
+        return OutputParam(dop_base_ref=dop_base_ref, semantic=semantic, **kwargs)
 
     def _build_odxlinks(self) -> Dict[OdxLinkId, Any]:
         return {}
@@ -37,15 +31,10 @@ class OutputParam(IdentifiableElement):
     def _resolve_odxlinks(self, odxlinks: OdxLinkDatabase) -> None:
         self._dop_base = odxlinks.resolve(self.dop_base_ref, DopBase)
 
-    def _resolve_snrefs(self, diag_layer: "DiagLayer") -> None:
+    def _resolve_snrefs(self, context: SnRefContext) -> None:
         pass
 
     @property
     def dop_base(self) -> DopBase:
         """The data object property describing this parameter."""
         return self._dop_base
-
-    @property
-    @deprecated(details="use .dop_base")  # type: ignore[misc]
-    def dop(self) -> DopBase:
-        return self._dop_base