enginehall 2.0.0__py3-none-any.whl

pcba/parsers/altium/project.py

@@ -0,0 +1,249 @@
+"""Read project-listed schematic sheets and expand their sheet-symbol instances.
+
+This is structural discovery, not electrical connectivity or compiled annotation.
+Every child reference is resolved against the project inventory before instances
+are expanded. Reusing a sheet creates separate instance paths; cycles and ambiguous
+references raise SchDocError instead of silently falling back to global names.
+"""
+
+from __future__ import annotations
+
+import configparser
+import dataclasses
+import re
+from pathlib import Path, PureWindowsPath
+
+from pcba.parsers.altium.records import SchDocError, load_any_records, text_of
+
+REC_SHEET_SYMBOL = "22"
+REC_SHEET_ENTRY = "23"
+REC_SHEET_NAME = "32"
+REC_SHEET_FILE_NAME = "35"
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class SheetSymbol:
+    """One source symbol and its owned entry records."""
+
+    index: int
+    name: str
+    child: Path
+    entries: tuple[dict[str, str], ...]
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class SheetInstance:
+    """One occurrence of a project sheet, identified by its symbol path."""
+
+    path: tuple[str, ...]
+    sheet: Path
+    parent: tuple[str, ...] | None
+    symbol_index: int | None
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class ProjectSheets:
+    """Source inventory and instances; no product-model entities or compiled nets."""
+
+    project: Path
+    records: dict[Path, list[dict[str, str]]]
+    symbols: dict[Path, tuple[SheetSymbol, ...]]
+    instances: tuple[SheetInstance, ...]
+
+
+def read_project(path: Path | str) -> ProjectSheets:
+    """Read only the schematic documents listed in a .PrjPcb and expand their instances."""
+    path = Path(path).resolve()
+    documents = _documents(path)
+    records = {document: load_any_records(document) for document in documents}
+    symbols = {document: _symbols(document, stream, documents, path.parent) for document, stream in records.items()}
+    _check_cycles(symbols)
+    children = {symbol.child for found in symbols.values() for symbol in found}
+    roots = [document for document in documents if document not in children]
+    instances: list[SheetInstance] = []
+    pending = [
+        SheetInstance((document.relative_to(path.parent).as_posix(),), document, None, None)
+        for document in reversed(roots)
+    ]
+    while pending:
+        instance = pending.pop()
+        instances.append(instance)
+        pending.extend(
+            SheetInstance(instance.path + (symbol.name,), symbol.child, instance.path, symbol.index)
+            for symbol in reversed(symbols[instance.sheet])
+        )
+    return ProjectSheets(path, records, symbols, tuple(instances))
+
+
+def to_dict(project: ProjectSheets) -> dict:
+    """Return structural source facts, explicitly excluding electrical and compiled results."""
+    def relative(path: Path) -> str:
+        return path.relative_to(project.project.parent).as_posix()
+
+    return {
+        "project": project.project.name,
+        "electrical_connectivity": "not_resolved",
+        "sheets": [relative(path) for path in project.records],
+        "instances": [
+            {
+                "path": list(instance.path),
+                "sheet": relative(instance.sheet),
+                "parent": list(instance.parent) if instance.parent is not None else None,
+                "symbol_record": instance.symbol_index,
+            }
+            for instance in project.instances
+        ],
+        "sheet_symbols": {
+            relative(path): [
+                {
+                    "record": symbol.index,
+                    "name": symbol.name,
+                    "child": relative(symbol.child),
+                    "entries": [
+                        (fields.get("%UTF8%Name") or fields.get("Name", "")).strip() for fields in symbol.entries
+                    ],
+                }
+                for symbol in symbols
+            ]
+            for path, symbols in project.symbols.items()
+        },
+    }
+
+
+def _documents(project: Path) -> tuple[Path, ...]:
+    try:
+        data = project.read_bytes()
+        try:
+            text = data.decode("utf-8-sig")
+        except UnicodeDecodeError:
+            text = data.decode("latin-1")
+        config = configparser.ConfigParser(interpolation=None, strict=True)
+        config.read_string(text)
+    except (OSError, configparser.Error) as exc:
+        raise SchDocError(f"{project}: cannot read project ({exc})") from exc
+    documents: dict[str, Path] = {}
+    for section in config.sections():
+        if not re.fullmatch(r"Document\d+", section, re.I):
+            continue
+        value = config.get(section, "DocumentPath", fallback="").strip()
+        if not value:
+            raise SchDocError(f"{project}: {section} has no DocumentPath")
+        if PureWindowsPath(value).suffix.lower() != ".schdoc":
+            continue
+        document = _case_file(project.parent, value)
+        identity = document.relative_to(project.parent).as_posix().casefold()
+        if identity in documents:
+            raise SchDocError(f"{project}: duplicate schematic document {value!r}")
+        if not document.is_file():
+            raise SchDocError(f"{project}: missing schematic document {value!r}")
+        documents[identity] = document
+    if not documents:
+        raise SchDocError(f"{project}: no schematic documents listed")
+    return tuple(documents.values())
+
+
+def _inside(root: Path, value: str) -> Path:
+    windows = PureWindowsPath(value)
+    if windows.drive or windows.root or Path(value).is_absolute():
+        raise SchDocError(f"absolute schematic reference is not supported: {value!r}")
+    result = root.joinpath(*windows.parts).resolve()
+    if not result.is_relative_to(root):
+        raise SchDocError(f"schematic reference leaves the project directory: {value!r}")
+    return result
+
+
+def _case_file(root: Path, value: str) -> Path:
+    """Resolve every listed path segment with Windows case semantics, without first-wins."""
+    logical = _inside(root, value)
+    current = root
+    for part in logical.relative_to(root).parts:
+        try:
+            matches = [entry for entry in current.iterdir() if entry.name.casefold() == part.casefold()]
+        except OSError as exc:
+            raise SchDocError(f"cannot read schematic path {value!r}: {exc}") from exc
+        if len(matches) != 1:
+            reason = "ambiguous" if matches else "missing"
+            raise SchDocError(f"{reason} schematic document {value!r}")
+        current = matches[0]
+    current = current.resolve()
+    if not current.is_relative_to(root):
+        raise SchDocError(f"schematic reference leaves the project directory: {value!r}")
+    return current
+
+
+def _child(document: Path, value: str, documents: tuple[Path, ...], root: Path) -> Path:
+    windows = PureWindowsPath(value)
+    if windows.drive or windows.root or Path(value).is_absolute():
+        raise SchDocError(f"absolute schematic reference is not supported: {value!r}")
+    references = {
+        candidate.relative_to(root).as_posix().casefold()
+        for base in (root, document.parent)
+        if (candidate := base.joinpath(*windows.parts).resolve()).is_relative_to(root)
+    }
+    if not references:
+        raise SchDocError(f"schematic reference leaves the project directory: {value!r}")
+    matches = [candidate for candidate in documents if candidate.relative_to(root).as_posix().casefold() in references]
+    if not matches and len(PureWindowsPath(value).parts) == 1:
+        matches = [candidate for candidate in documents if candidate.name.casefold() == value.casefold()]
+    if len(matches) != 1:
+        reason = "ambiguous" if matches else "unlisted or missing"
+        raise SchDocError(f"{document}: {reason} child schematic {value!r}")
+    return matches[0]
+
+
+def _symbols(
+    document: Path, records: list[dict[str, str]], documents: tuple[Path, ...], root: Path
+) -> tuple[SheetSymbol, ...]:
+    indices = {index for index, fields in enumerate(records) if fields.get("RECORD") == REC_SHEET_SYMBOL}
+    owned: dict[int, list[dict[str, str]]] = {index: [] for index in indices}
+    for fields in records:
+        if fields.get("RECORD") not in (REC_SHEET_NAME, REC_SHEET_FILE_NAME, REC_SHEET_ENTRY):
+            continue
+        value = fields.get("OwnerIndex", "")
+        if not value.strip():
+            raise SchDocError(f"{document}: sheet-symbol child has no owner")
+        index = int(value) + 1
+        if index not in indices:
+            raise SchDocError(f"{document}: sheet-symbol child has an invalid owner")
+        owned[index].append(fields)
+    out: list[SheetSymbol] = []
+    names: set[str] = set()
+    for index in sorted(indices):
+        name = _one_text(document, owned[index], REC_SHEET_NAME)
+        filename = _one_text(document, owned[index], REC_SHEET_FILE_NAME)
+        if re.match(r"repeat\s*\(", name, re.I):
+            raise SchDocError(f"{document}: Repeat sheet-symbol expansion is not implemented")
+        identity = name.casefold()
+        if identity in names:
+            raise SchDocError(f"{document}: duplicate sheet-symbol name {name!r}")
+        names.add(identity)
+        entries = tuple(fields for fields in owned[index] if fields.get("RECORD") == REC_SHEET_ENTRY)
+        out.append(SheetSymbol(index, name, _child(document, filename, documents, root), entries))
+    return tuple(out)
+
+
+def _one_text(document: Path, records: list[dict[str, str]], kind: str) -> str:
+    values = [text_of(fields) for fields in records if fields.get("RECORD") == kind]
+    if len(values) != 1 or not values[0]:
+        raise SchDocError(f"{document}: sheet symbol needs exactly one nonempty record {kind}")
+    return values[0]
+
+
+def _check_cycles(symbols: dict[Path, tuple[SheetSymbol, ...]]) -> None:
+    complete: set[Path] = set()
+    for start in symbols:
+        active: set[Path] = set()
+        pending: list[tuple[Path, bool]] = [(start, False)]
+        while pending:
+            document, leaving = pending.pop()
+            if leaving:
+                active.remove(document)
+                complete.add(document)
+                continue
+            if document in active:
+                raise SchDocError(f"cyclic schematic hierarchy at {document.name!r}")
+            if document in complete:
+                continue
+            active.add(document)
+            pending.append((document, True))
+            pending.extend((symbol.child, False) for symbol in reversed(symbols[document]))

pcba/parsers/altium/records.py

@@ -0,0 +1,227 @@
+"""Read the record stream out of a binary Altium `.SchDoc`.
+
+Format notes — each of these silently corrupts the result if ignored
+-------------------------------------------------------------------
+- `.SchDoc` is an OLE2/CFB container; the records live in the "FileHeader" stream.
+- Records are uint32-LE length + payload; payload is Latin-1 with embedded NULs and splits
+  into "|KEY=VALUE" fields. Altium writes ANSI, never UTF-8. Some text fields appear as
+  "%UTF8%Text" instead of "Text".
+- `OwnerIndex` is 0-based over the records, so the component index is `OwnerIndex + 1`.
+- A component's designator ("U1") is NOT a field of the component record. It is a child
+  record (RECORD=34) whose `Text` holds it. The component record's `LibReference` is the
+  symbol name, which for an MCU is the part number — reading that as the designator makes
+  every finding say "STM32...PD8" where it should say "U1.PD8".
+- A pin's `Location` is the BODY-ATTACH end. The electrical end is `PinLength` away along
+  the direction in the low 2 bits of `PinConglomerate`.
+- Coordinates are an integer plus an optional millionths sub-step in `<key>_Frac`.
+
+That list is the asset. The code below is the easy part; knowing these six things is what
+took the time.
+
+ASCII schematics
+----------------
+Altium can also save a schematic as text: a file starting
+"|HEADER=Protel for Windows - Schematic Capture Ascii File", one record per line, the same
+"|KEY=VALUE" fields and coordinate units. Its header line is record 0 exactly like the
+binary stream's header record, so `OwnerIndex` means the same thing in both. Everything
+from the "|HEADER=Icon storage" line on is embedded image data, not records. Lines split on
+LF only: Latin-1 decodes byte 0x85 to U+0085, which `str.splitlines` treats as a line
+break. `load_records` stays binary-only, which is the pin map's contract; `load_any_records`
+accepts both.
+"""
+
+from __future__ import annotations
+
+import re
+import struct
+from pathlib import Path
+
+import olefile
+
+# Altium record type ids, as they appear in the RECORD field.
+REC_COMPONENT = "1"
+REC_PIN = "2"
+REC_POWER_PORT = "17"
+REC_PORT = "18"
+REC_NET_LABEL = "25"
+REC_WIRE = "27"
+REC_JUNCTION = "29"
+REC_DESIGNATOR = "34"
+REC_PARAMETER = "41"
+REC_IMPLEMENTATION = "45"
+
+# First bytes of a schematic saved in Altium's ASCII format, and the line that ends its
+# records (embedded images follow it).
+ASCII_SIGNATURE = b"|HEADER=Protel for Windows - Schematic Capture Ascii File"
+_ICON_STORAGE = b"|HEADER=Icon storage"
+
+# Low 2 bits of PinConglomerate give the direction the pin points away from the body.
+PIN_DIRECTION = {0: (1, 0), 1: (0, 1), 2: (-1, 0), 3: (0, -1)}
+
+
+class SchDocError(RuntimeError):
+    """A controlled failure while reading a `.SchDoc`."""
+
+
+def load_records(path: Path | str) -> list[dict[str, str]]:
+    """Return the FileHeader record stream as a list of field dicts."""
+    try:
+        ole = olefile.OleFileIO(str(path))
+    except OSError as exc:
+        raise SchDocError(f"cannot read {path}: {exc}") from exc
+    except Exception as exc:
+        # olefile reports a damaged header with ValueError, IndexError, struct.error or even
+        # MemoryError. One damaged sheet must become a note, not end every review.
+        raise SchDocError(f"{path}: damaged OLE2 container ({type(exc).__name__})") from exc
+    try:
+        if not ole.exists("FileHeader"):
+            raise SchDocError(f"{path}: no FileHeader stream — not a schematic document?")
+        buf = ole.openstream("FileHeader").read()
+    except SchDocError:
+        raise
+    except Exception as exc:
+        raise SchDocError(f"{path}: damaged OLE2 container ({type(exc).__name__})") from exc
+    finally:
+        ole.close()
+
+    records = split_records(buf, source=str(path))
+    try:
+        validate_fields(records)
+    except SchDocError as exc:
+        raise SchDocError(f"{path}: {exc}") from exc
+    return records
+
+
+# Geometry and ownership fields the extractor reads as integers. The TypeScript decoder
+# applies the same check (`validateRecordFields`); both run the shared conformance corpus.
+_INTEGER_FIELD = re.compile(
+    r"RECORD|OwnerIndex|OwnerPartId|CurrentPartId|PinLength|PinConglomerate|LocationCount"
+    r"|Location\.[XY](?:_Frac)?|[XY]\d+(?:_Frac)?"
+)
+# At most ten digits: every Altium coordinate fits an int32, and int() refuses strings over
+# 4300 digits with a ValueError the callers do not expect.
+_INTEGER_VALUE = re.compile(r"[+-]?[0-9]{1,10}")
+
+
+def validate_fields(records: list[dict[str, str]]) -> None:
+    """Reject records whose integer fields are not plain ASCII integers.
+
+    Deliberately stricter than `int()`, which also accepts `1_000` and non-ASCII digits:
+    both decoders must refuse the same inputs.
+    """
+    for index, fields in enumerate(records):
+        for field, value in fields.items():
+            if value and _INTEGER_FIELD.fullmatch(field) and not _INTEGER_VALUE.fullmatch(value.strip(" \t")):
+                raise SchDocError(f"record {index}: invalid integer field {field}")
+        count = fields.get("LocationCount", "").strip(" \t")
+        if count and not 0 <= int(count) <= len(fields):
+            raise SchDocError(f"record {index}: invalid LocationCount")
+
+
+def split_records(buf: bytes, *, source: str = "record stream") -> list[dict[str, str]]:
+    """Decode an Altium record stream without its OLE2 container."""
+
+    out: list[dict[str, str]] = []
+    offset = 0
+    while offset + 4 <= len(buf):
+        (length,) = struct.unpack_from("<I", buf, offset)
+        offset += 4
+        if length == 0:
+            if any(buf[offset:]):
+                raise SchDocError(f"{source}: nonzero data after record-stream terminator")
+            break
+        if offset + length > len(buf):
+            raise SchDocError(
+                f"{source}: truncated record {len(out)} declares {length} bytes, "
+                f"only {len(buf) - offset} remain"
+            )
+        text = buf[offset : offset + length].replace(b"\x00", b"").decode("latin-1")
+        offset += length
+        out.append(_split_fields(text))
+    if offset < len(buf) and len(buf) - offset < 4 and any(buf[offset:]):
+        raise SchDocError(f"{source}: truncated record-length prefix")
+    return out
+
+
+def _split_fields(text: str) -> dict[str, str]:
+    """One record's "|KEY=VALUE|KEY=VALUE" payload as a dict; anything else is empty."""
+    fields: dict[str, str] = {}
+    if text.startswith("|"):
+        for item in text.split("|"):
+            eq = item.find("=")
+            if eq > 0:
+                fields[item[:eq]] = item[eq + 1 :]
+    return fields
+
+
+def split_ascii_records(buf: bytes) -> list[dict[str, str]]:
+    """Decode an ASCII `.SchDoc`: one record per line, up to the icon-storage section.
+
+    Blank lines are not records. A line that is not a "|KEY=VALUE" record still counts as
+    one (an empty dict), as in the binary decoder, so `OwnerIndex` stays aligned.
+    """
+    out: list[dict[str, str]] = []
+    for line in buf.split(b"\n"):
+        line = line.rstrip(b"\r")
+        if line.startswith(_ICON_STORAGE):
+            break
+        if not line.strip():
+            continue
+        out.append(_split_fields(line.replace(b"\x00", b"").decode("latin-1")))
+    return out
+
+
+def load_ascii_records(path: Path | str) -> list[dict[str, str]]:
+    """Return the records of an ASCII `.SchDoc`, validated like the binary stream."""
+    try:
+        buf = Path(path).read_bytes()
+    except OSError as exc:
+        raise SchDocError(f"cannot read {path}: {exc}") from exc
+    if not buf.startswith(ASCII_SIGNATURE):
+        raise SchDocError(f"{path}: not an ASCII schematic document")
+    records = split_ascii_records(buf)
+    try:
+        validate_fields(records)
+    except SchDocError as exc:
+        raise SchDocError(f"{path}: {exc}") from exc
+    return records
+
+
+def load_any_records(path: Path | str) -> list[dict[str, str]]:
+    """Records of a binary or an ASCII `.SchDoc`, chosen by the file's first bytes."""
+    try:
+        with open(path, "rb") as fh:
+            head = fh.read(len(ASCII_SIGNATURE))
+    except OSError as exc:
+        raise SchDocError(f"cannot read {path}: {exc}") from exc
+    if head == ASCII_SIGNATURE:
+        return load_ascii_records(path)
+    return load_records(path)
+
+
+def coord(fields: dict[str, str], key: str) -> float:
+    """Altium stores an integer coordinate plus an optional millionths sub-step."""
+    whole = fields.get(key)
+    frac = fields.get(key + "_Frac")
+    value = int(whole) if whole not in (None, "") else 0
+    if frac not in (None, ""):
+        value += int(frac) / 1e6
+    return value
+
+
+def text_of(fields: dict[str, str]) -> str:
+    """Altium writes either `Text` or, for non-ANSI content, `%UTF8%Text`."""
+    return (fields.get("%UTF8%Text") or fields.get("Text", "")).strip()
+
+
+def contains_part(path: Path | str, part: str) -> bool:
+    """Cheap pre-filter: does this sheet mention the part at all?
+
+    The MCU is drawn on only a couple of sheets in a real design. Scanning the raw bytes is
+    far cheaper than parsing every sheet, and it avoids hardcoding sheet names.
+    """
+    try:
+        with open(path, "rb") as fh:
+            return part.encode("latin-1") in fh.read()
+    except OSError:
+        return False

pcba/parsers/firmware/__init__.py

@@ -0,0 +1,5 @@
+"""Firmware source indexing."""
+
+from pcba.parsers.firmware.index import index, scan_file
+
+__all__ = ["index", "scan_file"]