enginehall 2.0.0__py3-none-any.whl

pcba/parsers/kicad/schematic.py

@@ -0,0 +1,517 @@
+"""Read a KiCad schematic hierarchy and build its nets from geometry.
+
+What KiCad considers connected, measured against `kicad-cli sch export netlist` (KiCad 10.0.7)
+on synthetic sheets, and what this reader therefore does:
+
+- Items whose points coincide are connected: pin ends, wire ends, labels, junctions, sheet pins.
+- A **label** (local, global or hierarchical), a **junction** or a **sheet pin** joins a wire
+  anywhere along the wire, not only at its ends.
+- A **pin end** (power-symbol pins included) or a **wire end** lying in the interior of another
+  wire does **not** join it. A T drawn without a junction is two nets; so are two collinear wires
+  that overlap. KiCad's editor adds the junction when a person draws the T, which is why
+  generated files are where this bites.
+- Two wires that merely cross do not connect; a junction on the crossing does.
+- A no-connect flag never connects anything. On a pin end it marks the pin as intentionally
+  open.
+- Local labels and hierarchical labels with the same text join within one sheet instance.
+  Global labels and global power symbols join across the whole project; a KiCad 9+ local power
+  symbol joins only within its sheet. A hierarchical label joins the same-named pin of its sheet
+  symbol in the parent.
+- A power symbol names its net with its **Value** field. A hidden power-input pin on an
+  ordinary symbol (older libraries) joins the global net named after the pin.
+- A placed symbol's pin at (px, py) in symbol space (y up) is rotated counter-clockwise by the
+  symbol angle first and mirrored after (`mirror x` negates the rotated y, `mirror y` the
+  rotated x), then placed at (X + px', Y - py'), schematic space being y down. The order
+  matters only at 90 and 270 degrees, and it was measured against `kicad-cli` netlists: the
+  other order swaps the pins of every rotated, mirrored symbol.
+- A sheet file used twice is two instances with separate nets and its own references, taken
+  from the symbol's `(instances (project ... (path ...)))` entry for that instance.
+
+Buses are not resolved: a design that carries signals through bus entries is reported with a
+note, and the kicad-cli netlist cross-check shows which nets that affects.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+import math
+import re
+from collections import defaultdict
+from pathlib import Path
+
+from pcba.model.design import Component, Net, SchLabel, Schematic, SchPin
+from pcba.parsers.altium.geometry import PointIndex, UnionFind
+from pcba.parsers.kicad.sexpr import Node, SexprError, load
+
+# KiCad stores schematic coordinates in mm with at most four decimals (100 nm).
+ON_WIRE_MM = 0.001
+# Item kinds that join a wire anywhere along it: labels, junctions, sheet pins.
+INTERIOR_JOINS = frozenset({"l", "j", "s"})
+_UNIT = re.compile(r"^(.*)_(\d+)_(\d+)$")
+
+
+class KicadError(RuntimeError):
+    """A KiCad file is missing or cannot be read as KiCad."""
+
+
+def _key(x: float, y: float) -> tuple[float, float]:
+    return (round(x, 4) + 0.0, round(y, 4) + 0.0)
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class LibPin:
+    number: str
+    name: str
+    type: str
+    x: float
+    y: float
+    hidden: bool
+    unit: int
+    style: int
+
+
+@dataclasses.dataclass(slots=True)
+class LibSymbol:
+    name: str
+    power: str | None              # "global", "local" or None
+    pins: list[LibPin]
+    extends: str | None = None
+
+
+def lib_symbols(root: Node) -> dict[str, LibSymbol]:
+    """The embedded symbol library of one schematic file, by its full name ("Device:R")."""
+    out: dict[str, LibSymbol] = {}
+    library = root.child("lib_symbols")
+    if library is None:
+        return out
+    for symbol in library.children("symbol"):
+        full = symbol[1] if len(symbol) > 1 and isinstance(symbol[1], str) else ""
+        power_node = symbol.child("power")
+        power = None
+        if power_node is not None:
+            atoms = power_node.atoms()
+            power = atoms[0] if atoms else "global"
+        pins: list[LibPin] = []
+        units = list(symbol.children("symbol")) or [symbol]
+        for unit_symbol in units:
+            unit, style = 0, 0
+            match = _UNIT.match(unit_symbol[1] if len(unit_symbol) > 1 else "")
+            if match and unit_symbol is not symbol:
+                unit, style = int(match.group(2)), int(match.group(3))
+            for pin in unit_symbol.children("pin"):
+                at = pin.xy("at") or (0.0, 0.0, 0.0)
+                atoms = pin.atoms()
+                name = pin.value("name", "") or ""
+                pins.append(LibPin(
+                    number=pin.value("number", "") or "",
+                    name="" if name == "~" else name,
+                    type=atoms[0] if atoms else "unspecified",
+                    x=at[0], y=at[1], hidden=pin.flag("hide"), unit=unit, style=style,
+                ))
+        out[full] = LibSymbol(full, power, pins, symbol.value("extends"))
+    # A derived symbol (`extends`) keeps its parent's pins.
+    for name, symbol in out.items():
+        if symbol.extends and not symbol.pins:
+            library_prefix = name.split(":")[0] + ":" if ":" in name else ""
+            parent = out.get(library_prefix + symbol.extends) or out.get(symbol.extends)
+            if parent:
+                symbol.pins = list(parent.pins)
+    return out
+
+
+def place(px: float, py: float, x: float, y: float, angle: float, mirror: str | None) -> tuple[float, float]:
+    """Absolute schematic position of a symbol-space point (see the module docstring)."""
+    rad = math.radians(angle)
+    cos, sin = round(math.cos(rad), 12), round(math.sin(rad), 12)
+    rx, ry = px * cos - py * sin, px * sin + py * cos
+    if mirror == "x":
+        ry = -ry
+    elif mirror == "y":
+        rx = -rx
+    return x + rx, y - ry
+
+
+def _property(node: Node, name: str) -> str | None:
+    for prop in node.children("property"):
+        atoms = prop.atoms()
+        if atoms and atoms[0] == name:
+            return atoms[1] if len(atoms) > 1 else ""
+    return None
+
+
+def _properties(node: Node) -> dict[str, str]:
+    out = {}
+    for prop in node.children("property"):
+        atoms = prop.atoms()
+        if len(atoms) >= 2:
+            out[atoms[0]] = atoms[1]
+    return out
+
+
+def _instance_reference(symbol: Node, instance_path: str, legacy: dict[str, tuple[str, int]]) -> tuple[str, int]:
+    """Reference and unit of a placed symbol in one sheet instance."""
+    unit = int(float(symbol.value("unit", "1") or 1))
+    instances = symbol.child("instances")
+    if instances is not None:
+        for project in instances.children("project"):
+            for path in project.children("path"):
+                atoms = path.atoms()
+                if atoms and atoms[0] == instance_path:
+                    return path.value("reference", "") or "", int(float(path.value("unit", str(unit)) or unit))
+    uuid = symbol.value("uuid")
+    if uuid:
+        # KiCad 6 kept the references in the root's `symbol_instances`, keyed by the sheet path
+        # without the root uuid.
+        tail = "/".join(instance_path.split("/")[2:])
+        hit = legacy.get(("/" + tail + "/" if tail else "/") + uuid)
+        if hit:
+            return hit
+    return _property(symbol, "Reference") or "?", unit
+
+
+@dataclasses.dataclass(slots=True)
+class _Instance:
+    path: str           # uuid path, "/<root uuid>/<sheet uuid>"
+    names: str          # sheet path, "/" or "/Power/"
+    file: Path
+    node: Node
+    parent: str | None = None
+    sheet_pins: dict[str, list[tuple[str, tuple[float, float], int]]] = dataclasses.field(default_factory=dict)
+
+
+def _sheet_file_property(sheet: Node) -> tuple[str, str]:
+    name = _property(sheet, "Sheetname") or _property(sheet, "Sheet name") or ""
+    file = _property(sheet, "Sheetfile") or _property(sheet, "Sheet file") or ""
+    return name, file
+
+
+def _instances(root_file: Path, root: Node, cache: dict[Path, Node], notes: list[str]) -> list[_Instance]:
+    root_uuid = root.value("uuid", "") or ""
+    out = [_Instance(path="/" + root_uuid, names="/", file=root_file, node=root)]
+    stack = [(out[0], (root_file.resolve(),))]
+    while stack:
+        parent, chain = stack.pop()
+        for sheet in parent.node.children("sheet"):
+            name, file = _sheet_file_property(sheet)
+            child_file = (parent.file.parent / file).resolve()
+            uuid = sheet.value("uuid", "") or ""
+            child_path = f"{parent.path}/{uuid}"
+            if child_file in chain:
+                notes.append(f"sheet {name or file} includes itself; the recursion is cut there")
+                continue
+            if not child_file.is_file():
+                notes.append(f"sheet file {file} of sheet {name or uuid} not found; its nets are missing")
+                continue
+            if child_file not in cache:
+                try:
+                    cache[child_file] = load(child_file)
+                except (OSError, SexprError) as exc:
+                    notes.append(f"cannot read sheet {file}: {exc}")
+                    continue
+            child = _Instance(path=child_path, names=f"{parent.names}{name}/", file=child_file,
+                              node=cache[child_file], parent=parent.path)
+            pins = parent.sheet_pins.setdefault(child_path, [])
+            for pin in sheet.children("pin"):
+                at = pin.xy("at") or (0.0, 0.0, 0.0)
+                pins.append((pin[1] if len(pin) > 1 else "", (at[0], at[1]), pin.line))
+            out.append(child)
+            stack.append((child, chain + (child_file,)))
+    return out
+
+
+def find_root(directory: Path) -> tuple[Path | None, Path | None]:
+    """(project file, root schematic) of the KiCad project in `directory`, if any."""
+    projects = sorted(directory.glob("*.kicad_pro"))
+    for project in projects:
+        root = project.with_suffix(".kicad_sch")
+        if root.is_file():
+            return project, root
+    sheets = sorted(directory.glob("*.kicad_sch"))
+    if not sheets:
+        return (projects[0] if projects else None), None
+    # Without a project file, the root is a sheet no other sheet includes.
+    included: set[str] = set()
+    for sheet in sheets:
+        try:
+            text = sheet.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        included.update(re.findall(r'\(property\s+"Sheet ?file"\s+"([^"]+)"', text))
+    roots = [s for s in sheets if s.name not in included]
+    return None, (roots or sheets)[0]
+
+
+def read(path: Path | str) -> Schematic:
+    """Read a project (`.kicad_pro`), a root `.kicad_sch` or a directory holding one."""
+    path = Path(path)
+    project_file: Path | None = None
+    if path.is_dir():
+        project_file, root_file = find_root(path)
+        if root_file is None:
+            raise KicadError(f"no KiCad schematic in {path}")
+    elif path.suffix == ".kicad_pro":
+        project_file, root_file = path, path.with_suffix(".kicad_sch")
+    else:
+        root_file = path
+        candidate = path.with_suffix(".kicad_pro")
+        project_file = candidate if candidate.is_file() else None
+    if not root_file.is_file():
+        raise KicadError(f"root schematic {root_file} not found")
+    if project_file is not None:
+        try:
+            json.loads(project_file.read_text(encoding="utf-8"))
+        except (OSError, ValueError) as exc:
+            raise KicadError(f"cannot read {project_file.name}: {exc}") from exc
+    try:
+        root = load(root_file)
+    except SexprError as exc:
+        raise KicadError(f"cannot read {root_file.name}: {exc}") from exc
+    if root.head != "kicad_sch":
+        raise KicadError(f"{root_file.name} is not a KiCad schematic")
+    return _build(project_file, root_file.resolve(), root)
+
+
+def _legacy_instances(root: Node) -> dict[str, tuple[str, int]]:
+    out: dict[str, tuple[str, int]] = {}
+    section = root.child("symbol_instances")
+    if section is not None:
+        for path in section.children("path"):
+            atoms = path.atoms()
+            if atoms:
+                out[atoms[0]] = (path.value("reference", "") or "",
+                                 int(float(path.value("unit", "1") or 1)))
+    return out
+
+
+def _build(project_file: Path | None, root_file: Path, root: Node) -> Schematic:
+    notes: list[str] = []
+    cache: dict[Path, Node] = {root_file: root}
+    instances = _instances(root_file, root, cache, notes)
+    legacy = _legacy_instances(root)
+    schematic = Schematic(
+        project_file=str(project_file.resolve()) if project_file else None,
+        root_file=str(root_file),
+        sheet_files=sorted({str(i.file) for i in instances}),
+        sheet_paths={i.names: str(i.file) for i in instances},
+    )
+    libraries = {file: lib_symbols(node) for file, node in cache.items()}
+
+    graph = UnionFind()
+    cluster_pins: dict[object, list[SchPin]] = defaultdict(list)
+    cluster_labels: dict[object, list[tuple[SchLabel, int]]] = defaultdict(list)
+    cluster_nc: set[object] = set()
+    components: dict[str, Component] = {}
+    bus_warned = False
+
+    for instance in instances:
+        node = instance.node
+        library = libraries[instance.file]
+        file = str(instance.file)
+        if not bus_warned and (node.child("bus") is not None or node.child("bus_entry") is not None):
+            notes.append("the schematic uses buses; signals carried through bus entries are not resolved")
+            bus_warned = True
+
+        local = UnionFind()
+        at_point: dict[tuple[float, float], list[object]] = defaultdict(list)
+        wires: list[tuple[tuple[float, float], tuple[float, float], int]] = []
+        pins: list[tuple[object, SchPin, LibPin, bool]] = []
+        labels: list[tuple[object, SchLabel, int]] = []   # (item, label, priority)
+        no_connects: list[tuple[float, float]] = []
+
+        for index, wire in enumerate(node.children("wire")):
+            pts = wire.child("pts")
+            xys = [tuple(float(a) for a in xy.atoms()[:2]) for xy in pts.children("xy")] if pts else []
+            for a, b in zip(xys, xys[1:]):
+                item = ("w", instance.path, index, len(wires))
+                wires.append((_key(*a), _key(*b), len(wires)))
+                at_point[_key(*a)].append(item)
+                at_point[_key(*b)].append(item)
+                local.find(item)
+        for index, junction in enumerate(node.children("junction")):
+            at = junction.xy("at")
+            if at:
+                item = ("j", instance.path, index)
+                at_point[_key(at[0], at[1])].append(item)
+                local.find(item)
+        for junction in node.children("no_connect"):
+            at = junction.xy("at")
+            if at:
+                no_connects.append(_key(at[0], at[1]))
+
+        for kind, priority in (("label", 4), ("global_label", 7), ("hierarchical_label", 3)):
+            for index, label in enumerate(node.children(kind)):
+                at = label.xy("at")
+                if not at or len(label) < 2 or not isinstance(label[1], str):
+                    continue
+                item = ("l", instance.path, kind, index)
+                lab = SchLabel(kind={"label": "local", "global_label": "global",
+                                     "hierarchical_label": "hierarchical"}[kind],
+                               text=label[1], sheet_file=file, sheet_path=instance.names,
+                               x=at[0], y=at[1], line=label.line)
+                labels.append((item, lab, priority))
+                at_point[_key(at[0], at[1])].append(item)
+                local.find(item)
+        for child_path, sheet_pins in instance.sheet_pins.items():
+            for index, (text, (x, y), line) in enumerate(sheet_pins):
+                item = ("s", instance.path, child_path, index)
+                lab = SchLabel(kind="sheet_pin", text=text, sheet_file=file, sheet_path=instance.names,
+                               x=x, y=y, line=line)
+                labels.append((item, lab, 2))
+                at_point[_key(x, y)].append(item)
+                local.find(item)
+                # The pin joins the child's hierarchical labels of the same name.
+                graph.union(("sheetpin", instance.path, child_path, index), ("L", child_path, text))
+
+        for symbol in node.children("symbol"):
+            lib_name = symbol.value("lib_name") or symbol.value("lib_id") or ""
+            lib = library.get(lib_name) or library.get(symbol.value("lib_id") or "")
+            ref, unit = _instance_reference(symbol, instance.path, legacy)
+            at = symbol.xy("at") or (0.0, 0.0, 0.0)
+            mirror = symbol.value("mirror")
+            style = int(float(symbol.value("body_style") or symbol.value("convert") or 1))
+            properties = _properties(symbol)
+            power = bool(lib and lib.power)
+            component = components.get(ref)
+            if component is None:
+                component = Component(
+                    ref=ref, value=properties.get("Value", ""), lib_id=symbol.value("lib_id") or "",
+                    footprint=properties.get("Footprint", ""), sheet_file=file, sheet_path=instance.names,
+                    line=symbol.line, properties=properties, power=power or ref.startswith("#"),
+                    dnp=symbol.flag("dnp"),
+                    in_bom=symbol.value("in_bom", "yes") != "no",
+                    on_board=symbol.value("on_board", "yes") != "no",
+                )
+                components[ref] = component
+            elif component.lib_id != (symbol.value("lib_id") or "") and not ref.startswith("#"):
+                notes.append(f"reference {ref} is used by two different symbols")
+            if "?" in ref and not ref.startswith("#"):
+                notes.append("the schematic has unannotated symbols (references with '?'); "
+                             "they merge into one part until annotated")
+            if lib is None:
+                notes.append(f"{ref}: symbol {lib_name} is missing from lib_symbols; its pins are unknown")
+                continue
+            for lib_pin in lib.pins:
+                if lib_pin.unit not in (0, unit) or lib_pin.style not in (0, style):
+                    continue
+                x, y = place(lib_pin.x, lib_pin.y, at[0], at[1], at[2], mirror)
+                pin = SchPin(ref=ref, number=lib_pin.number, name=lib_pin.name, type=lib_pin.type,
+                             sheet_file=file, sheet_path=instance.names, x=round(x, 4), y=round(y, 4),
+                             line=symbol.line, hidden=lib_pin.hidden)
+                item = ("p", instance.path, ref, lib_pin.number, len(pins))
+                pins.append((item, pin, lib_pin, power))
+                at_point[_key(x, y)].append(item)
+                local.find(item)
+                if power and lib_pin.type == "power_in":
+                    value = properties.get("Value", "")
+                    kind = "local_power" if lib.power == "local" else "power"
+                    lab = SchLabel(kind=kind, text=value, sheet_file=file, sheet_path=instance.names,
+                                   x=x, y=y, line=symbol.line)
+                    label_item = ("pw", instance.path, ref, lib_pin.number, len(pins))
+                    labels.append((label_item, lab, 5 if kind == "local_power" else 6))
+                    local.union(label_item, item)
+                elif lib_pin.hidden and lib_pin.type == "power_in" and lib_pin.name:
+                    lab = SchLabel(kind="power", text=lib_pin.name, sheet_file=file, sheet_path=instance.names,
+                                   x=x, y=y, line=symbol.line)
+                    label_item = ("hp", instance.path, ref, lib_pin.number, len(pins))
+                    labels.append((label_item, lab, 6))
+                    local.union(label_item, item)
+
+        # Everything at one point is connected (no-connect flags are kept out of at_point).
+        for items in at_point.values():
+            for other in items[1:]:
+                local.union(items[0], other)
+        # A label, junction or sheet pin anywhere on a wire joins it; pins and wire ends do not.
+        index = PointIndex(at_point.keys())
+        for a, b, number in wires:
+            wire_item = next(i for i in at_point[a] if i[0] == "w" and i[3] == number)
+            for point in index.near_segment(a, b, ON_WIRE_MM):
+                for item in at_point[point]:
+                    if item[0] in INTERIOR_JOINS:
+                        local.union(wire_item, item)
+
+        no_connect_points = set(no_connects)
+        for item, pin, _lib_pin, _power in pins:
+            root_item = ("c", instance.path, local.find(item))
+            if _key(pin.x, pin.y) in no_connect_points:
+                pin = dataclasses.replace(pin, no_connect=True)
+                cluster_nc.add(root_item)
+            cluster_pins[root_item].append(pin)
+            graph.find(root_item)
+        for item, label, priority in labels:
+            root_item = ("c", instance.path, local.find(item))
+            cluster_labels[root_item].append((label, priority))
+            graph.find(root_item)
+            if label.kind in ("local", "hierarchical", "local_power"):
+                graph.union(root_item, ("L", instance.path, label.text))
+            elif label.kind in ("global", "power"):
+                graph.union(root_item, ("G", label.text))
+            elif label.kind == "sheet_pin":
+                graph.union(root_item, ("sheetpin", instance.path, item[2], item[3]))
+
+    # Group clusters into nets.
+    members: dict[object, list[object]] = defaultdict(list)
+    for cluster in set(cluster_pins) | set(cluster_labels):
+        members[graph.find(cluster)].append(cluster)
+
+    nets: list[Net] = []
+    for clusters in members.values():
+        pins = sorted((p for c in clusters for p in cluster_pins.get(c, [])),
+                      key=lambda p: (p.ref, _natural(p.number)))
+        named = [(label, priority) for c in clusters for label, priority in cluster_labels.get(c, [])]
+        if not pins and not named:
+            continue
+        name, label_text, power = _net_name(pins, named)
+        nets.append(Net(name=name, label=label_text, pins=pins,
+                        labels=[label for label, _ in named], power=power,
+                        no_connect=any(c in cluster_nc for c in clusters)))
+
+    # Two separate nets can still end up with one KiCad-style name (an auto name, rarely a
+    # label); keep them apart by suffixing, as KiCad does with its own collisions.
+    seen: dict[str, int] = {}
+    for net in sorted(nets, key=lambda n: (n.name, [(p.ref, p.number) for p in n.pins])):
+        count = seen.get(net.name, 0)
+        seen[net.name] = count + 1
+        if count:
+            net.name = f"{net.name}_{count}"
+
+    for net in nets:
+        for pin in net.pins:
+            component = components.get(pin.ref)
+            if component is not None:
+                component.pins.append(pin)
+    counted = []
+    for net in nets:
+        connections = len(net.parts)
+        net.labels = [dataclasses.replace(label, connections=connections) for label in net.labels]
+        counted.extend(net.labels)
+    schematic.labels = sorted(counted, key=lambda lab: (lab.sheet_file, lab.line, lab.text))
+    schematic.components = dict(sorted(components.items(), key=lambda kv: _natural(kv[0])))
+    schematic.nets = sorted(nets, key=lambda n: _natural(n.name))
+    schematic.notes = sorted(set(notes))
+    schematic.index()
+    return schematic
+
+
+def _natural(text: str) -> tuple:
+    return tuple((0, int(t), "") if t.isdigit() else (1, 0, t) for t in re.split(r"(\d+)", text or "") if t)
+
+
+def _net_name(pins: list[SchPin], named: list[tuple[SchLabel, int]]) -> tuple[str, str | None, bool]:
+    """KiCad-style net name: the highest-priority driver wins (global label, power symbol,
+    local power, local label, hierarchical label, sheet pin), the highest sheet level and then
+    the smallest text breaking ties. Unnamed nets are named after their first pin."""
+    power = any(label.kind in ("power", "local_power") for label, _ in named)
+    if named:
+        label, _priority = min(named, key=lambda lp: (-lp[1], lp[0].sheet_path.count("/"), lp[0].text))
+        if label.kind in ("global", "power"):
+            return label.text, label.text, power
+        return f"{label.sheet_path}{label.text}", label.text, power
+    parts = [p for p in pins if not p.ref.startswith("#")] or pins
+    # Measured against kicad-cli: a named pin wins over an unnamed one, then the reference that
+    # sorts first as text (R10 before R9), then the pin number.
+    first = min(parts, key=lambda p: (not p.name, p.ref, _natural(p.number)))
+    pad = f"{first.name}-Pad{first.number}" if first.name else f"Pad{first.number}"
+    if len(parts) == 1:
+        return f"unconnected-({first.ref}-{pad})", None, False
+    return f"Net-({first.ref}-{first.name or 'Pad' + first.number})", None, False

pcba/parsers/kicad/sexpr.py

@@ -0,0 +1,136 @@
+"""KiCad's S-expression files, read with the standard library.
+
+`.kicad_sch`, `.kicad_pcb`, `.kicad_sym`, `.kicad_mod` and the `kicadsexpr` netlist are one
+syntax: lists in parentheses, bare atoms (`yes`, `smd`, `1.27`) and double-quoted strings with
+backslash escapes. A list remembers the line its opening parenthesis is on, so a finding can
+point at the line of the symbol, wire or pad it is about.
+
+Quoted and bare atoms are both returned as `str`. KiCad does not distinguish them by meaning
+(`(hide yes)` and `(hide "yes")` read the same), and keeping one type keeps every caller simple.
+"""
+
+from __future__ import annotations
+
+import bisect
+import re
+from collections.abc import Iterator
+from pathlib import Path
+
+_TOKEN = re.compile(r'\(|\)|"(?:[^"\\]|\\.)*"|[^\s()"]+', re.S)
+_ESCAPE = re.compile(r"\\(.)", re.S)
+_ESCAPES = {"n": "\n", "t": "\t", "r": "\r"}
+
+
+class SexprError(ValueError):
+    """The text is not a well-formed S-expression."""
+
+
+class Node(list):
+    """One parenthesised list: `node[0]` is its head atom, the rest are atoms and Nodes."""
+
+    __slots__ = ("line",)
+
+    def __init__(self, line: int = 0) -> None:
+        super().__init__()
+        self.line = line
+
+    @property
+    def head(self) -> str:
+        return self[0] if self and isinstance(self[0], str) else ""
+
+    def children(self, name: str | None = None) -> Iterator[Node]:
+        """Child lists, optionally only those whose head is `name`."""
+        for item in self:
+            if isinstance(item, Node) and (name is None or item.head == name):
+                yield item
+
+    def child(self, name: str) -> Node | None:
+        return next(self.children(name), None)
+
+    def atoms(self) -> list[str]:
+        """The atoms after the head, skipping nested lists."""
+        return [item for item in self[1:] if isinstance(item, str)]
+
+    def value(self, name: str, default: str | None = None) -> str | None:
+        """The first atom of child `name`: `value("layer")` on `(layer "F.Cu")` is `F.Cu`."""
+        found = self.child(name)
+        if found is None:
+            return default
+        atoms = found.atoms()
+        return atoms[0] if atoms else default
+
+    def number(self, name: str, default: float | None = None) -> float | None:
+        text = self.value(name)
+        try:
+            return float(text) if text is not None else default
+        except ValueError:
+            return default
+
+    def flag(self, name: str) -> bool:
+        """A boolean KiCad writes as `(name yes)` (KiCad 9+) or as a bare `name` atom (older)."""
+        if name in self.atoms():
+            return True
+        found = self.child(name)
+        if found is None:
+            return False
+        atoms = found.atoms()
+        return not atoms or atoms[0] in ("yes", "true")
+
+    def xy(self, name: str = "at") -> tuple[float, float, float] | None:
+        """`(at x y [angle])` as floats; None when absent."""
+        found = self.child(name)
+        if found is None:
+            return None
+        numbers = [float(a) for a in found.atoms()[:3]]
+        while len(numbers) < 3:
+            numbers.append(0.0)
+        return numbers[0], numbers[1], numbers[2]
+
+
+def unquote(token: str) -> str:
+    return _ESCAPE.sub(lambda m: _ESCAPES.get(m.group(1), m.group(1)), token[1:-1])
+
+
+def parse(text: str) -> Node:
+    """Parse one top-level list. Raises SexprError on unbalanced or empty input."""
+    newlines = [m.start() for m in re.finditer("\n", text)]
+    stack: list[Node] = []
+    root: Node | None = None
+    for match in _TOKEN.finditer(text):
+        token = match.group()
+        if token == "(":
+            node = Node(bisect.bisect_right(newlines, match.start()) + 1)
+            if stack:
+                stack[-1].append(node)
+            elif root is not None:
+                raise SexprError("more than one top-level list")
+            else:
+                root = node
+            stack.append(node)
+        elif token == ")":
+            if not stack:
+                raise SexprError(f"unbalanced ')' at offset {match.start()}")
+            stack.pop()
+        elif not stack:
+            raise SexprError(f"atom outside a list at offset {match.start()}")
+        else:
+            stack[-1].append(unquote(token) if token.startswith('"') else token)
+    if stack:
+        raise SexprError(f"{len(stack)} list(s) not closed")
+    if root is None:
+        raise SexprError("no S-expression found")
+    return root
+
+
+def load(path: Path | str) -> Node:
+    """Parse a file. KiCad writes UTF-8; a byte order mark is tolerated."""
+    try:
+        text = Path(path).read_text(encoding="utf-8-sig")
+    except UnicodeDecodeError as exc:
+        raise SexprError(f"{Path(path).name} is not UTF-8: {exc}") from exc
+    return parse(text)
+
+
+def quote(text: str) -> str:
+    """Quote a string the way KiCad writes it (for the synthetic fixture writer and tests)."""
+    return '"' + text.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n") + '"'