can-db-model 0.1.0__py3-none-any.whl

can_db_model/__about__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

can_db_model/__init__.py

@@ -0,0 +1,17 @@
+from .__about__ import __version__
+from .model import (
+    Bus, CanDb, Document, Documentation, Label, Message, MuxMember, Node, Signal,
+)
+from .load import load
+from .from_kcd import load_kcd
+from .from_yaml import load_yaml
+from .to_kcd import dump_kcd, to_kcd_bytes
+from .to_yaml import dump_yaml, to_yaml_str
+
+__all__ = [
+    "__version__",
+    "Bus", "CanDb", "Document", "Documentation", "Label", "Message",
+    "MuxMember", "Node", "Signal",
+    "load", "load_kcd", "load_yaml",
+    "dump_kcd", "to_kcd_bytes", "dump_yaml", "to_yaml_str",
+]

can_db_model/from_kcd.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import cantools
+from lxml import etree
+
+from .model import CanDb
+
+_KCD_NS = "http://kayak.2codeornot2code.org/1.0"
+
+
+class KcdLoadError(Exception):
+    pass
+
+
+def _xml_facts(path: Path):
+    """Recover nodes/producers/consumers/bus that cantools' KCD reader drops."""
+    root = etree.parse(str(path)).getroot()
+    ns = {"k": _KCD_NS}
+
+    doc_el = root.find("k:Document", ns)
+    document = None
+    if doc_el is not None:
+        document = {
+            "name": doc_el.get("name") or "",
+            "version": doc_el.get("version") or "",
+            "author": doc_el.get("author") or "",
+        }
+
+    bus = root.find("k:Bus", ns)
+    bus_name = bus.get("name")
+    bus_baud = int(bus.get("baudrate"))
+
+    id_to_name: dict[str, str] = {}
+    node_names: list[str] = []
+    for n in root.findall(".//k:Node", ns):
+        id_to_name[n.get("id")] = n.get("name")
+        node_names.append(n.get("name"))
+
+    def _refs(parent, xpath):
+        out = []
+        for ref in parent.findall(xpath, ns):
+            out.append(id_to_name[ref.get("id")])
+        return out
+
+    producers: dict[int, list[str]] = {}
+    consumers: dict[int, dict[str, list[str]]] = {}
+    for msg in bus.findall("k:Message", ns):
+        mid = int(msg.get("id"), 0)
+        producers[mid] = _refs(msg, "k:Producer/k:NodeRef")
+        per_sig: dict[str, list[str]] = {}
+        for sig in (msg.findall(".//k:Signal", ns) + msg.findall(".//k:Multiplex", ns)):
+            cons = _refs(sig, "k:Consumer/k:NodeRef")
+            if cons:
+                per_sig[sig.get("name")] = cons
+        consumers[mid] = per_sig
+    return document, bus_name, bus_baud, node_names, producers, consumers
+
+
+def _value_type(sig) -> str:
+    if sig.is_float:
+        return "double" if sig.length == 64 else "single"
+    return "signed" if sig.is_signed else "unsigned"
+
+
+def _mux_field(sig):
+    if sig.is_multiplexer:
+        return "multiplexor"
+    if sig.multiplexer_signal is not None:
+        return {"of": sig.multiplexer_signal, "group": sig.multiplexer_ids[0]}
+    return None
+
+
+def load_kcd(path: Path | str) -> CanDb:
+    path = Path(path)
+    try:
+        db = cantools.database.load_file(path, database_format="kcd")
+    except Exception as e:
+        raise KcdLoadError(f"failed to load KCD {path}: {e}") from e
+    document, bus_name, bus_baud, node_names, producers, consumers = _xml_facts(path)
+
+    messages = []
+    for m in db.messages:
+        sigs = []
+        for s in m.signals:
+            sigs.append({
+                "name": s.name,
+                "start": s.start,
+                "length": s.length,
+                "endianness": "big" if s.byte_order == "big_endian" else "little",
+                "type": _value_type(s),
+                "slope": s.scale if s.scale is not None else 1.0,
+                "intercept": s.offset if s.offset is not None else 0.0,
+                "unit": s.unit,
+                "min": s.minimum,
+                "max": s.maximum,
+                "consumers": consumers.get(m.frame_id, {}).get(s.name, []),
+                "labels": ({int(v): str(n) for v, n in s.choices.items()}
+                           if s.choices else {}),
+                "mux": _mux_field(s),
+                "doc": ({"kcd_notes": s.comment} if s.comment else None),
+            })
+        messages.append({
+            "name": m.name,
+            "id": m.frame_id,
+            "extended": m.is_extended_frame,
+            "length": m.length,
+            "interval": m.cycle_time,
+            "producers": producers.get(m.frame_id, []),
+            "signals": sigs,
+            "doc": ({"kcd_notes": m.comment} if m.comment else None),
+        })
+
+    payload = {
+        "bus": {"name": bus_name, "baudrate": bus_baud},
+        "nodes": node_names,
+        "messages": messages,
+    }
+    if document is not None:
+        payload["document"] = document
+    return CanDb.model_validate(payload)

can_db_model/from_yaml.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+from pydantic import ValidationError
+
+from .model import CanDb
+
+
+class YamlLoadError(Exception):
+    pass
+
+
+def _format_validation_error(path: Path, err: ValidationError) -> str:
+    lines = [f"{path}: invalid CAN database:"]
+    for e in err.errors():
+        loc = ".".join(str(p) for p in e["loc"])
+        lines.append(f"  {loc or '<root>'}: {e['msg']}")
+    return "\n".join(lines)
+
+
+def load_yaml(path: Path | str) -> CanDb:
+    path = Path(path)
+    try:
+        data = yaml.safe_load(path.read_text())
+    except yaml.YAMLError as e:
+        raise YamlLoadError(f"{path}: YAML syntax error: {e}") from e
+    if not isinstance(data, dict):
+        raise YamlLoadError(f"{path}: top level must be a mapping")
+    try:
+        return CanDb.model_validate(data)
+    except ValidationError as e:
+        raise YamlLoadError(_format_validation_error(path, e)) from e

can_db_model/load.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from .from_kcd import load_kcd
+from .from_yaml import load_yaml
+from .model import CanDb
+
+
+def load(path: Path | str) -> CanDb:
+    path = Path(path)
+    ext = path.suffix.lower()
+    if ext == ".kcd":
+        return load_kcd(path)
+    if ext in (".yaml", ".yml"):
+        return load_yaml(path)
+    raise ValueError(
+        f"{path}: unsupported extension {ext!r} (expected .kcd/.yaml/.yml)")

can_db_model/model.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+from typing import Literal, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+Endianness = Literal["little", "big"]
+ValueType = Literal["unsigned", "signed", "single", "double"]
+
+_STRICT = ConfigDict(extra="forbid")
+
+
+class Documentation(BaseModel):
+    model_config = _STRICT
+    kcd_notes: Optional[str] = None
+    comments: list[str] = Field(default_factory=list)
+    description: Optional[str] = None
+    tooltip: Optional[str] = None
+
+
+class Label(BaseModel):
+    model_config = _STRICT
+    value: int
+    name: str
+
+
+class MuxMember(BaseModel):
+    model_config = _STRICT
+    of: str
+    group: int
+
+
+class Signal(BaseModel):
+    model_config = _STRICT
+    name: str
+    start: int
+    length: int
+    endianness: Endianness = "little"
+    type: ValueType = "unsigned"
+    slope: float = 1.0
+    intercept: float = 0.0
+    unit: Optional[str] = None
+    min: Optional[float] = None
+    max: Optional[float] = None
+    consumers: list[str] = Field(default_factory=list)
+    labels: list[Label] = Field(default_factory=list)
+    mux: Union[Literal["multiplexor"], MuxMember, None] = None
+    doc: Optional[Documentation] = None
+
+    @field_validator("labels", mode="before")
+    @classmethod
+    def _coerce_labels(cls, v):
+        # Accept the terse YAML mapping {value: name} as well as a list.
+        if isinstance(v, dict):
+            return [{"value": int(val), "name": str(name)} for val, name in v.items()]
+        return v
+
+
+class Message(BaseModel):
+    model_config = _STRICT
+    name: str
+    id: int
+    extended: Optional[bool] = None
+    length: int
+    interval: Optional[int] = None
+    producers: list[str] = Field(default_factory=list)
+    signals: list[Signal] = Field(default_factory=list)
+    doc: Optional[Documentation] = None
+
+    @field_validator("id", mode="before")
+    @classmethod
+    def _parse_id(cls, v):
+        if isinstance(v, str):
+            return int(v, 0)
+        return v
+
+    @model_validator(mode="after")
+    def _infer_extended(self):
+        if self.extended is None:
+            self.extended = self.id > 0x7FF
+        return self
+
+
+class Bus(BaseModel):
+    model_config = _STRICT
+    name: str
+    baudrate: int
+    doc: Optional[Documentation] = None
+
+
+class Node(BaseModel):
+    model_config = _STRICT
+    name: str
+    doc: Optional[Documentation] = None
+
+
+class Document(BaseModel):
+    model_config = _STRICT
+    name: str
+    version: str = ""
+    author: str = ""
+
+
+class CanDb(BaseModel):
+    model_config = _STRICT
+    document: Optional[Document] = None
+    bus: Optional[Bus] = None
+    nodes: list[Node] = Field(default_factory=list)
+    messages: list[Message] = Field(default_factory=list)
+    doc: Optional[Documentation] = None
+
+    @field_validator("nodes", mode="before")
+    @classmethod
+    def _coerce_nodes(cls, v):
+        if isinstance(v, list):
+            return [{"name": n} if isinstance(n, str) else n for n in v]
+        return v
+
+    @model_validator(mode="after")
+    def _semantic_checks(self):
+        node_names = {n.name for n in self.nodes}
+
+        seen_ids: set[int] = set()
+        for msg in self.messages:
+            if msg.id in seen_ids:
+                raise ValueError(f"duplicate frame id 0x{msg.id:X} ({msg.name})")
+            seen_ids.add(msg.id)
+
+            for pname in msg.producers:
+                if pname not in node_names:
+                    raise ValueError(
+                        f"producer node {pname!r} not in nodes ({msg.name})")
+
+            selectors = {s.name for s in msg.signals if s.mux == "multiplexor"}
+            for s in msg.signals:
+                for cname in s.consumers:
+                    if cname not in node_names:
+                        raise ValueError(
+                            f"consumer node {cname!r} not in nodes "
+                            f"({msg.name}.{s.name})")
+                if s.start + s.length > msg.length * 8:
+                    raise ValueError(
+                        f"signal {s.name} exceeds message length ({msg.name})")
+                if isinstance(s.mux, MuxMember) and s.mux.of not in selectors:
+                    raise ValueError(
+                        f"mux selector {s.mux.of!r} not found ({msg.name}.{s.name})")
+
+            # Bit-overlap only among signals that coexist: plain + selector, and
+            # within each individual mux group. Members of different groups may
+            # share bits.
+            def _overlap(sigs):
+                spans = sorted((s.start, s.start + s.length, s.name) for s in sigs)
+                for (a0, a1, an), (b0, b1, bn) in zip(spans, spans[1:]):
+                    if b0 < a1:
+                        raise ValueError(
+                            f"signals {an} and {bn} overlap ({msg.name})")
+
+            base = [s for s in msg.signals
+                    if s.mux is None or s.mux == "multiplexor"]
+            _overlap(base)
+            groups: dict[tuple[str, int], list] = {}
+            for s in msg.signals:
+                if isinstance(s.mux, MuxMember):
+                    groups.setdefault((s.mux.of, s.mux.group), []).append(s)
+            for members in groups.values():
+                _overlap(base + members)
+        return self

can_db_model/to_kcd.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from lxml import etree
+
+from .model import CanDb, MuxMember, Signal
+
+_NS = "http://kayak.2codeornot2code.org/1.0"
+_NSMAP = {None: _NS}
+
+
+def _q(tag: str) -> str:
+    return f"{{{_NS}}}{tag}"
+
+
+def _set_attrs(elem, sig: Signal) -> None:
+    elem.set("name", sig.name)
+    elem.set("offset", str(sig.start))
+    elem.set("length", str(sig.length))
+    elem.set("endianess", "big" if sig.endianness == "big" else "little")
+
+
+def _kcd_notes(sig) -> str | None:
+    return sig.doc.kcd_notes if sig.doc else None
+
+
+def _populate(elem, sig: Signal, node_id):
+    # KCD child order: Notes, Consumer, Value, LabelSet.
+    _set_attrs(elem, sig)
+    if _kcd_notes(sig):
+        etree.SubElement(elem, _q("Notes")).text = _kcd_notes(sig)
+    if sig.consumers:
+        cons = etree.SubElement(elem, _q("Consumer"))
+        for c in sig.consumers:
+            etree.SubElement(cons, _q("NodeRef"), id=node_id[c])
+    v = etree.SubElement(elem, _q("Value"), type=sig.type,
+                         slope=repr(sig.slope), intercept=repr(sig.intercept))
+    if sig.unit:
+        v.set("unit", sig.unit)
+    if sig.labels:
+        ls = etree.SubElement(elem, _q("LabelSet"))
+        for lab in sig.labels:
+            etree.SubElement(ls, _q("Label"), name=lab.name, value=str(lab.value))
+
+
+def _signal_elem(sig: Signal, node_id):
+    s = etree.Element(_q("Signal"))
+    _populate(s, sig, node_id)
+    return s
+
+
+def to_kcd_bytes(db: CanDb) -> bytes:
+    if db.bus is None:
+        raise ValueError("cannot serialize to KCD without a bus")
+    root = etree.Element(_q("NetworkDefinition"), nsmap=_NSMAP)
+    doc = db.document
+    d = etree.SubElement(root, _q("Document"),
+                         name=doc.name if doc else "",
+                         version=doc.version if doc else "",
+                         author=doc.author if doc else "")
+    d.text = doc.name if doc else ""
+
+    node_id: dict[str, str] = {}
+    for idx, node in enumerate(db.nodes, start=1):
+        node_id[node.name] = str(idx)
+        etree.SubElement(root, _q("Node"), id=str(idx), name=node.name)
+
+    bus = etree.SubElement(root, _q("Bus"), name=db.bus.name,
+                           baudrate=str(db.bus.baudrate))
+
+    for msg in db.messages:
+        m = etree.SubElement(bus, _q("Message"), id=f"0x{msg.id:X}",
+                             length=str(msg.length), name=msg.name)
+        if msg.interval is not None:
+            m.set("interval", str(msg.interval))
+        if msg.doc and msg.doc.kcd_notes:
+            etree.SubElement(m, _q("Notes")).text = msg.doc.kcd_notes
+        if msg.producers:
+            prod = etree.SubElement(m, _q("Producer"))
+            for p in msg.producers:
+                etree.SubElement(prod, _q("NodeRef"), id=node_id[p])
+
+        plain = [s for s in msg.signals if s.mux is None]
+        selector = next((s for s in msg.signals if s.mux == "multiplexor"), None)
+        members = [s for s in msg.signals if isinstance(s.mux, MuxMember)]
+
+        for sig in plain:
+            m.append(_signal_elem(sig, node_id))
+
+        if selector is not None:
+            mux_elem = etree.SubElement(m, _q("Multiplex"))
+            _set_attrs(mux_elem, selector)
+            by_group: dict[int, list[Signal]] = {}
+            for s in members:
+                if s.mux.of == selector.name:
+                    by_group.setdefault(s.mux.group, []).append(s)
+            for group, sigs in by_group.items():
+                mg = etree.SubElement(mux_elem, _q("MuxGroup"), count=str(group))
+                for s in sigs:
+                    mg.append(_signal_elem(s, node_id))
+            if _kcd_notes(selector):
+                etree.SubElement(mux_elem, _q("Notes")).text = _kcd_notes(selector)
+            if selector.consumers:
+                cons = etree.SubElement(mux_elem, _q("Consumer"))
+                for c in selector.consumers:
+                    etree.SubElement(cons, _q("NodeRef"), id=node_id[c])
+            etree.SubElement(mux_elem, _q("Value"), type=selector.type,
+                             slope=repr(selector.slope),
+                             intercept=repr(selector.intercept))
+
+    xml = etree.tostring(root, pretty_print=True, xml_declaration=True,
+                         encoding="UTF-8")
+    return xml.replace(b"</Message>\n", b"</Message>\n\n")
+
+
+def dump_kcd(db: CanDb, path: Path | str) -> None:
+    Path(path).write_bytes(to_kcd_bytes(db))

can_db_model/to_yaml.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from .model import CanDb
+
+
+def to_yaml_str(db: CanDb) -> str:
+    # exclude_none/exclude_defaults keep the output terse, mirroring authored YAML.
+    data = db.model_dump(mode="json", exclude_none=True, exclude_defaults=True)
+    return yaml.safe_dump(data, sort_keys=False, default_flow_style=False)
+
+
+def dump_yaml(db: CanDb, path: Path | str) -> None:
+    Path(path).write_text(to_yaml_str(db))

can_db_model-0.1.0.dist-info/METADATA

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: can-db-model
+Version: 0.1.0
+Summary: Shared Pydantic model + KCD/YAML loaders for CAN databases
+Project-URL: Documentation, https://sr.ht/~laplace/can-db-model#readme
+Project-URL: Issues, https://sr.ht/~laplace/can-db-model/issues
+Project-URL: Source, https://sr.ht/~laplace/can-db-model
+Author-email: Alexander Krishna-Becker <nabla.becker@mailbox.org>
+License-Expression: LGPL-3.0-only
+Keywords: automotive,can,dbc,kcd,pydantic,yaml
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Software Development :: Embedded Systems
+Requires-Python: >=3.10
+Requires-Dist: cantools
+Requires-Dist: lxml
+Requires-Dist: pydantic>=2
+Requires-Dist: pyyaml
+Description-Content-Type: text/markdown
+
+# can-db-model
+
+Shared Pydantic model + KCD/YAML loaders and serializers for CAN databases.
+Consumed by can-api-generator and kcd-merger.

can_db_model-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+can_db_model/__about__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+can_db_model/__init__.py,sha256=jt-WXAX7fN2SkNJaXuKEg7yfpb0oU9hJJLYPxBfocVE,549
+can_db_model/from_kcd.py,sha256=yLpXMfQSVaKDvEbzvJX0Zv_iUTPOwY8Tmg7SRffHDeg,3958
+can_db_model/from_yaml.py,sha256=f0ZeRrI8bPARvZU04nM_uRWu1rQUQ1db-ziVT8IFJsg,943
+can_db_model/load.py,sha256=y2WFUmpFeuAzN_3W9JTd_5pK6SuT6wuBp5zvIJzRTOg,457
+can_db_model/model.py,sha256=wTg29K-DHyQ3HO7BQsjZHKRfdMaFNCSOj1-jJ0SVtI4,5269
+can_db_model/to_kcd.py,sha256=wWAAoz_2aPjdR5t07BD_l0VUsKwyvfUmClYLAiYWX8M,4443
+can_db_model/to_yaml.py,sha256=4qM-TUAYE4zGS_FgyTQf1ApxaYx9sPhJxL-Njq90e3g,473
+can_db_model-0.1.0.dist-info/METADATA,sha256=iDGSNrN5KLHYhbkkRSaqCbCLSbqCAt1vjJY88SVvaCE,1183
+can_db_model-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+can_db_model-0.1.0.dist-info/RECORD,,

can_db_model-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any