Loading files
This file is pinned to the selected release. Download the original to open it in your design tool.
"""``add_sheet`` — hierarchical sheet authoring (op-list -> ``(sheet ...)`` node).
Contract (SPEC §2.2): ``add_sheet`` emits a KiCad ``(sheet ...)`` node with
Sheetname/Sheetfile properties, stroke/fill defaults, a deterministic uuid,
sheet pins at computed edge coordinates, and the ``(instances)`` page block the
reader/eeschema resolve designator paths against. The referenced child file is
NOT created by the op. Wires attach to a sheet pin by its ``at`` + ``offset_mil``
coordinate — a label anchor, so the endpoint does not dangle. Cross-sheet
membership parity with eeschema lives in ``tests/test_kicad_parity.py``.
"""
from __future__ import annotations
import uuid as _uuid
from pathlib import Path
from akcli import ops
from akcli.readers import kicad as kreader
from akcli.readers import sexpr
from akcli.report import Severity
from akcli.writers import kicad as kw
_LIB = """\
(kicad_symbol_lib (version 20231120) (generator akcli_test)
(symbol "RR" (pin_numbers (hide yes)) (pin_names (offset 0))
(exclude_from_sim no) (in_bom yes) (on_board yes)
(property "Reference" "R" (at 0 0 0) (effects (font (size 1.27 1.27))))
(property "Value" "RR" (at 0 0 0) (effects (font (size 1.27 1.27))))
(symbol "RR_1_1"
(pin passive line (at 0 3.81 270) (length 1.27)
(name "~" (effects (font (size 1.27 1.27))))
(number "1" (effects (font (size 1.27 1.27)))))
(pin passive line (at 0 -3.81 90) (length 1.27)
(name "~" (effects (font (size 1.27 1.27))))
(number "2" (effects (font (size 1.27 1.27)))))))
)
"""
def _oplist(*op):
return {"protocol_version": 1, "target_format": "kicad", "ops": list(op)}
def _seed(d: Path, name: str = "root.kicad_sch") -> Path:
p = d / name
p.write_text(
f'(kicad_sch (version 20231120) (generator "akcli") '
f'(uuid "{_uuid.uuid4()}") (paper "A4"))\n'
)
return p
def _apply(tgt: Path, lib: Path, *op, apply: bool = True):
# add_sheet refuses a child file that does not exist yet (a dangling sheet
# bricks every later nets/check/render on the design), so stub each child
# first; the tests that exercise the reader overwrite it with real content.
for o in op:
if o.get("op") == "add_sheet" and not (tgt.parent / str(o["file"])).exists():
_seed(tgt.parent, str(o["file"]))
verify_out: list = []
res = kw.apply(_oplist(*op), str(tgt), apply=apply,
sources=[str(lib)], verify_out=verify_out)
return res, verify_out
def _sheet(doc: sexpr.SNode) -> sexpr.SNode:
return doc.find("sheet")
def _props(node: sexpr.SNode) -> dict[str, str]:
out = {}
for p in node.find_all("property"):
out[p.children[1].value] = p.children[2].value
return out
def _at_mm(node: sexpr.SNode) -> tuple[float, float]:
at = node.find("at")
return (float(at.children[1].value), float(at.children[2].value))
# --------------------------------------------------------------------------- #
# node structure
# --------------------------------------------------------------------------- #
def test_add_sheet_emits_sheet_node(tmp_path):
lib = tmp_path / "lib.kicad_sym"
lib.write_text(_LIB)
tgt = _seed(tmp_path)
res, verify = _apply(
tgt, lib,
{"op": "add_sheet", "name": "power", "file": "power.kicad_sch",
"at": [2000, 1000], "size": [1000, 800]},
)
assert [r.status for r in res] == ["ok"]
assert [f for f in verify if f.severity in (Severity.ERROR, Severity.CRITICAL)] == []
doc = sexpr.parse(tgt.read_text())
sh = _sheet(doc)
assert sh is not None
props = _props(sh)
assert props["Sheetname"] == "power"
assert props["Sheetfile"] == "power.kicad_sch"
# stroke/fill/uuid/instances all present
assert sh.find("stroke") is not None and sh.find("fill") is not None
assert sh.find("uuid") is not None
assert sh.find("instances") is not None
# box geometry: origin at (2000,1000) mil = (50.8, 25.4) mm
assert _at_mm(sh) == (50.8, 25.4)
def test_add_sheet_refuses_a_missing_child_file(tmp_path):
"""A sheet pointing at a file that does not exist is a self-inflicted brick:
the op used to succeed and every later nets/check/render on the design then
failed (exit 4) because the child cannot be read."""
lib = tmp_path / "lib.kicad_sym"
lib.write_text(_LIB)
tgt = _seed(tmp_path)
before = tgt.read_bytes()
res = kw.apply(
_oplist({"op": "add_sheet", "name": "ghost", "file": "ghost.kicad_sch",
"at": [2000, 1000], "size": [1000, 800]}),
str(tgt), apply=True, sources=[str(lib)])
assert [r.status for r in res] == ["error"]
assert res[0].error_code == "SHEET_FILE_MISSING"
assert "akcli new ghost.kicad_sch" in (res[0].remediation or "") \
or "akcli new" in res[0].message
assert tgt.read_bytes() == before # nothing written
# authoring the child first makes the SAME op succeed
_seed(tmp_path, "ghost.kicad_sch")
res = kw.apply(
_oplist({"op": "add_sheet", "name": "ghost", "file": "ghost.kicad_sch",
"at": [2000, 1000], "size": [1000, 800]}),
str(tgt), apply=True, sources=[str(lib)])
assert [r.status for r in res] == ["ok"]
def test_sheet_instances_path_references_root_uuid(tmp_path):
lib = tmp_path / "lib.kicad_sym"
lib.write_text(_LIB)
tgt = _seed(tmp_path)
_apply(tgt, lib,
{"op": "add_sheet", "name": "s", "file": "s.kicad_sch",
"at": [0, 0], "size": [1000, 800]})
doc = sexpr.parse(tgt.read_text())
root_uuid = doc.find("uuid").children[1].value
inst = _sheet(doc).find("instances")
path = inst.find("project").find("path")
assert path.children[1].value == "/" + root_uuid
assert path.find("page") is not None
# --------------------------------------------------------------------------- #
# sheet-pin edge coordinates
# --------------------------------------------------------------------------- #
def _pin_coords(tmp_path, side: str, offset_mil: float) -> tuple[float, float]:
lib = tmp_path / "lib.kicad_sym"
lib.write_text(_LIB)
tgt = _seed(tmp_path)
_apply(tgt, lib,
{"op": "add_sheet", "name": "s", "file": "s.kicad_sch",
"at": [2000, 1000], "size": [1000, 800],
"pins": [{"name": "P", "type": "input", "side": side,
"offset_mil": offset_mil}]})
pin = _sheet(sexpr.parse(tgt.read_text())).find("pin")
return _at_mm(pin)
def test_sheet_pin_left_edge(tmp_path):
# left edge: x = x0 (50.8 mm), y = y0 + offset (1000+200 mil = 30.48 mm)
assert _pin_coords(tmp_path, "left", 200) == (50.8, 30.48)
def test_sheet_pin_right_edge(tmp_path):
# right edge: x = x0 + w (2000+1000 mil = 76.2 mm)
assert _pin_coords(tmp_path, "right", 200) == (76.2, 30.48)
def test_sheet_pin_top_edge(tmp_path):
# top edge: y = y0 (25.4 mm), x = x0 + offset (2000+400 mil = 60.96 mm)
assert _pin_coords(tmp_path, "top", 400) == (60.96, 25.4)
def test_sheet_pin_bottom_edge(tmp_path):
# bottom edge: y = y0 + h (1000+800 mil = 45.72 mm)
assert _pin_coords(tmp_path, "bottom", 400) == (60.96, 45.72)
def test_sheet_pin_carries_type_and_uuid(tmp_path):
lib = tmp_path / "lib.kicad_sym"
lib.write_text(_LIB)
tgt = _seed(tmp_path)
_apply(tgt, lib,
{"op": "add_sheet", "name": "s", "file": "s.kicad_sch",
"at": [0, 0], "size": [1000, 800],
"pins": [{"name": "CLK", "type": "output", "side": "right",
"offset_mil": 100}]})
pin = _sheet(sexpr.parse(tgt.read_text())).find("pin")
assert pin.children[1].value == "CLK"
assert pin.children[2].value == "output" # KiCad electrical-type token
assert pin.find("uuid") is not None
# --------------------------------------------------------------------------- #
# wires attach to a sheet pin without dangling
# --------------------------------------------------------------------------- #
def test_wire_to_sheet_pin_does_not_dangle(tmp_path):
lib = tmp_path / "lib.kicad_sym"
lib.write_text(_LIB)
tgt = _seed(tmp_path)
res, verify = _apply(
tgt, lib,
{"op": "place_component", "lib_id": "RR", "designator": "R1",
"x_mil": 1000, "y_mil": 1200},
{"op": "add_sheet", "name": "s", "file": "s.kicad_sch",
"at": [2000, 1000], "size": [1000, 800],
"pins": [{"name": "NET1", "type": "bidirectional", "side": "left",
"offset_mil": 200}]},
# wire R1.1 -> the left sheet-pin coordinate (2000, 1200) mil
{"op": "add_wire", "vertices": ["R1.1", [2000, 1200]]},
)
assert [r.status for r in res] == ["ok", "ok", "ok"]
errs = [f for f in verify if f.severity in (Severity.ERROR, Severity.CRITICAL)]
assert errs == [], [f.message for f in errs]
# --------------------------------------------------------------------------- #
# reader round-trip (Sheetname + cross-sheet membership via a child fixture)
# --------------------------------------------------------------------------- #
def _child_file(tmp_path: Path, root_uuid: str, sheet_uuid: str) -> None:
"""A hand-written child: R2 wired to a hierarchical_label 'NET1'.
The child symbol's ``(instances)`` path is ``/<root>/<sheet>`` so the reader
resolves R2 under the sheet instance (matching eeschema).
"""
child_path = f"/{root_uuid}/{sheet_uuid}"
lib_inline = """\
(lib_symbols
(symbol "RR" (pin_numbers (hide yes)) (pin_names (offset 0))
(exclude_from_sim no) (in_bom yes) (on_board yes)
(property "Reference" "R" (at 0 0 0) (effects (font (size 1.27 1.27))))
(property "Value" "RR" (at 0 0 0) (effects (font (size 1.27 1.27))))
(symbol "RR_1_1"
(pin passive line (at 0 3.81 270) (length 1.27)
(name "~" (effects (font (size 1.27 1.27))))
(number "1" (effects (font (size 1.27 1.27)))))
(pin passive line (at 0 -3.81 90) (length 1.27)
(name "~" (effects (font (size 1.27 1.27))))
(number "2" (effects (font (size 1.27 1.27))))))))"""
(tmp_path / "s.kicad_sch").write_text(
'(kicad_sch (version 20231120) (generator "akcli")\n'
f' (uuid "{_uuid.uuid4()}") (paper "A4")\n'
+ lib_inline + "\n"
' (symbol (lib_id "RR") (at 50.8 50.8 0) (unit 1)\n'
f' (uuid "{_uuid.uuid4()}")\n'
' (property "Reference" "R2" (at 53 49 0) (effects (font (size 1.27 1.27))))\n'
' (property "Value" "RR" (at 53 51 0) (effects (font (size 1.27 1.27))))\n'
f' (pin "1" (uuid "{_uuid.uuid4()}"))\n'
f' (pin "2" (uuid "{_uuid.uuid4()}"))\n'
f' (instances (project "noname" (path "{child_path}" (reference "R2") (unit 1)))))\n'
' (wire (pts (xy 50.8 46.99) (xy 50.8 40.64)) (stroke (width 0) (type default))\n'
f' (uuid "{_uuid.uuid4()}"))\n'
' (hierarchical_label "NET1" (shape bidirectional) (at 50.8 40.64 90)\n'
' (effects (font (size 1.27 1.27)))\n'
f' (uuid "{_uuid.uuid4()}"))\n'
')\n'
)
def test_reader_reads_sheetname_and_crosses_sheet(tmp_path):
lib = tmp_path / "lib.kicad_sym"
lib.write_text(_LIB)
tgt = _seed(tmp_path)
_apply(
tgt, lib,
{"op": "place_component", "lib_id": "RR", "designator": "R1",
"x_mil": 1000, "y_mil": 1200},
{"op": "add_sheet", "name": "child", "file": "s.kicad_sch",
"at": [2000, 1000], "size": [1000, 800],
"pins": [{"name": "NET1", "type": "bidirectional", "side": "left",
"offset_mil": 200}]},
{"op": "add_wire", "vertices": ["R1.1", [2000, 1200]]},
)
doc = sexpr.parse(tgt.read_text())
root_uuid = doc.find("uuid").children[1].value
sheet_uuid = _sheet(doc).find("uuid").children[1].value
_child_file(tmp_path, root_uuid, sheet_uuid)
sch = kreader.read_sch(tgt)
assert sch.sheets == ["child"]
assert {c.designator for c in sch.components} == {"R1", "R2"}
net = next(n for n in sch.nets if ("R1", "1") in n.members)
assert ("R2", "1") in net.members # crosses the sheet boundary
# --------------------------------------------------------------------------- #
# idempotent replay
# --------------------------------------------------------------------------- #
def test_add_sheet_replay_is_byte_identical(tmp_path):
lib = tmp_path / "lib.kicad_sym"
lib.write_text(_LIB)
tgt = _seed(tmp_path)
op = {"op": "add_sheet", "name": "s", "file": "s.kicad_sch",
"at": [2000, 1000], "size": [1000, 800],
"pins": [{"name": "NET1", "type": "input", "side": "left",
"offset_mil": 200}]}
_apply(tgt, lib, op)
first = tgt.read_text()
_apply(tgt, lib, op)
assert tgt.read_text() == first
# --------------------------------------------------------------------------- #
# validation
# --------------------------------------------------------------------------- #
def _codes(doc) -> list[str]:
return [e.code for e in ops.validate_oplist(doc)]
def test_valid_add_sheet_passes_validator():
doc = _oplist({"op": "add_sheet", "name": "s", "file": "s.kicad_sch",
"at": [0, 0], "size": [1000, 800],
"pins": [{"name": "P", "type": "input", "side": "left",
"offset_mil": 0}]})
assert ops.validate_oplist(doc) == []
def test_add_sheet_missing_required_fields():
doc = _oplist({"op": "add_sheet", "name": "s"})
codes = _codes(doc)
assert codes and all(c == "OP_UNSUPPORTED" for c in codes)
def test_add_sheet_bad_size_type():
doc = _oplist({"op": "add_sheet", "name": "s", "file": "s.kicad_sch",
"at": [0, 0], "size": "big"})
assert "OP_UNSUPPORTED" in _codes(doc)
def test_add_sheet_bad_pin_type_and_side():
doc = _oplist({"op": "add_sheet", "name": "s", "file": "s.kicad_sch",
"at": [0, 0], "size": [100, 100],
"pins": [{"name": "P", "type": "analog", "side": "up",
"offset_mil": 0}]})
errs = ops.validate_oplist(doc)
msgs = " ".join(e.message for e in errs)
assert "type" in msgs and "side" in msgs
assert all(e.code == "OP_UNSUPPORTED" for e in errs)
def test_add_sheet_pin_missing_field():
doc = _oplist({"op": "add_sheet", "name": "s", "file": "s.kicad_sch",
"at": [0, 0], "size": [100, 100],
"pins": [{"name": "P", "type": "input", "side": "left"}]})
assert any("offset_mil" in e.message for e in ops.validate_oplist(doc))
def test_add_sheet_unknown_pin_field():
doc = _oplist({"op": "add_sheet", "name": "s", "file": "s.kicad_sch",
"at": [0, 0], "size": [100, 100],
"pins": [{"name": "P", "type": "input", "side": "left",
"offset_mil": 0, "bogus": 1}]})
assert any("bogus" in e.message for e in ops.validate_oplist(doc))
def test_add_sheet_unhashable_pin_type_does_not_crash():
doc = _oplist({"op": "add_sheet", "name": "s", "file": "s.kicad_sch",
"at": [0, 0], "size": [100, 100],
"pins": [{"name": "P", "type": ["input"], "side": "left",
"offset_mil": 0}]})
errs = ops.validate_oplist(doc) # must not raise TypeError
assert any("type" in e.message for e in errs)
# --------------------------------------------------------------------------- #
# template
# --------------------------------------------------------------------------- #
def test_add_sheet_template_is_valid():
tmpl = ops.op_template("add_sheet")
assert tmpl["op"] == "add_sheet"
for field in ("name", "file", "at", "size"):
assert field in tmpl
doc = _oplist(tmpl)
assert ops.validate_oplist(doc) == []
97c6f2bbeThis file is pinned to the selected release. Download the original to open it in your design tool.