boardwright 0.1.0__tar.gz → 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. {boardwright-0.1.0 → boardwright-0.2.0}/.gitignore +1 -0
  2. {boardwright-0.1.0 → boardwright-0.2.0}/CHANGELOG.md +17 -1
  3. {boardwright-0.1.0 → boardwright-0.2.0}/PKG-INFO +23 -1
  4. {boardwright-0.1.0 → boardwright-0.2.0}/README.md +21 -0
  5. {boardwright-0.1.0 → boardwright-0.2.0}/examples/existing/README.md +1 -1
  6. {boardwright-0.1.0 → boardwright-0.2.0}/pyproject.toml +4 -1
  7. boardwright-0.2.0/src/boardwright/__init__.py +1 -0
  8. {boardwright-0.1.0 → boardwright-0.2.0}/src/boardwright/build.py +18 -9
  9. {boardwright-0.1.0 → boardwright-0.2.0}/src/boardwright/check.py +3 -2
  10. {boardwright-0.1.0 → boardwright-0.2.0}/src/boardwright/cli.py +35 -10
  11. {boardwright-0.1.0 → boardwright-0.2.0}/src/boardwright/edits.py +7 -6
  12. {boardwright-0.1.0 → boardwright-0.2.0}/src/boardwright/env.py +9 -4
  13. boardwright-0.2.0/src/boardwright/errors.py +33 -0
  14. {boardwright-0.1.0 → boardwright-0.2.0}/src/boardwright/existing.py +12 -9
  15. {boardwright-0.1.0 → boardwright-0.2.0}/src/boardwright/live.py +9 -8
  16. {boardwright-0.1.0 → boardwright-0.2.0}/src/boardwright/sch.py +11 -8
  17. {boardwright-0.1.0 → boardwright-0.2.0}/src/boardwright/selection.py +2 -1
  18. {boardwright-0.1.0 → boardwright-0.2.0}/tests/conftest.py +1 -1
  19. {boardwright-0.1.0 → boardwright-0.2.0}/tests/test_sch_cli.py +36 -1
  20. boardwright-0.1.0/src/boardwright/__init__.py +0 -1
  21. {boardwright-0.1.0 → boardwright-0.2.0}/LICENSE +0 -0
  22. {boardwright-0.1.0 → boardwright-0.2.0}/docs/devlog/README.md +0 -0
  23. {boardwright-0.1.0 → boardwright-0.2.0}/examples/libs/customlib/README.md +0 -0
  24. {boardwright-0.1.0 → boardwright-0.2.0}/src/boardwright/__main__.py +0 -0
  25. {boardwright-0.1.0 → boardwright-0.2.0}/src/boardwright/board.py +0 -0
  26. {boardwright-0.1.0 → boardwright-0.2.0}/src/boardwright/circuit.py +0 -0
  27. {boardwright-0.1.0 → boardwright-0.2.0}/src/boardwright/copper.py +0 -0
  28. {boardwright-0.1.0 → boardwright-0.2.0}/src/boardwright/model.py +0 -0
  29. {boardwright-0.1.0 → boardwright-0.2.0}/src/boardwright/pins.py +0 -0
  30. {boardwright-0.1.0 → boardwright-0.2.0}/src/boardwright/placement.py +0 -0
  31. {boardwright-0.1.0 → boardwright-0.2.0}/src/boardwright/preview.py +0 -0
  32. {boardwright-0.1.0 → boardwright-0.2.0}/src/boardwright/project.py +0 -0
  33. {boardwright-0.1.0 → boardwright-0.2.0}/src/boardwright/review.py +0 -0
  34. {boardwright-0.1.0 → boardwright-0.2.0}/src/boardwright/route.py +0 -0
  35. {boardwright-0.1.0 → boardwright-0.2.0}/src/boardwright/si.py +0 -0
  36. {boardwright-0.1.0 → boardwright-0.2.0}/src/boardwright/verify.py +0 -0
  37. {boardwright-0.1.0 → boardwright-0.2.0}/tests/test_board_model.py +0 -0
  38. {boardwright-0.1.0 → boardwright-0.2.0}/tests/test_edit_route.py +0 -0
  39. {boardwright-0.1.0 → boardwright-0.2.0}/tests/test_pipeline.py +0 -0
  40. {boardwright-0.1.0 → boardwright-0.2.0}/tests/test_si.py +0 -0
@@ -17,3 +17,4 @@ fp-info-cache
17
17
  *.rules
18
18
  preview.svg
19
19
  *_preview.png
20
+ site/
@@ -7,6 +7,21 @@ the command line).
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.2.0] - 2026-11-14
11
+
12
+ ### Changed
13
+
14
+ - Exit codes follow the heibench contract: `2` when a check cannot be
15
+ decided (`verify` with KiCad's reports missing or stale, which used to exit
16
+ `1`), `4` for an environment fault (KiCad, its libraries or Freerouting
17
+ missing or failing, which used to exit `1`), and `64` for usage errors
18
+ (which used to exit `1`, or `2` for an unknown command). An unexpected
19
+ error exits `2` instead of `1`.
20
+
21
+ ### Added
22
+
23
+ - A documentation site at https://heibench.com/boardwright/.
24
+
10
25
  ## [0.1.0] - 2026-11-14
11
26
 
12
27
  First public release.
@@ -37,5 +52,6 @@ First public release.
37
52
  - `boardwright impedance` (IPC-2141 closed form) and `doctor`.
38
53
  - Seven example boards and specs for KiCad's own demo projects.
39
54
 
40
- [Unreleased]: https://github.com/heibench/boardwright/compare/v0.1.0...HEAD
55
+ [Unreleased]: https://github.com/heibench/boardwright/compare/v0.2.0...HEAD
56
+ [0.2.0]: https://github.com/heibench/boardwright/compare/v0.1.0...v0.2.0
41
57
  [0.1.0]: https://github.com/heibench/boardwright/releases/tag/v0.1.0
@@ -1,8 +1,9 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: boardwright
3
- Version: 0.1.0
3
+ Version: 0.2.0
4
4
  Summary: Generate and edit KiCad boards and schematics from a short Python description, checked by KiCad itself.
5
5
  Project-URL: Homepage, https://github.com/heibench/boardwright
6
+ Project-URL: Documentation, https://heibench.com/boardwright/
6
7
  Project-URL: Issues, https://github.com/heibench/boardwright/issues
7
8
  Project-URL: Changelog, https://github.com/heibench/boardwright/blob/main/CHANGELOG.md
8
9
  Author: heibench
@@ -30,6 +31,12 @@ Description-Content-Type: text/markdown
30
31
 
31
32
  # boardwright
32
33
 
34
+ [![Check](https://github.com/heibench/boardwright/actions/workflows/check.yml/badge.svg)](https://github.com/heibench/boardwright/actions/workflows/check.yml)
35
+ [![Docs](https://github.com/heibench/boardwright/actions/workflows/docs.yml/badge.svg)](https://heibench.com/boardwright/)
36
+ [![PyPI](https://img.shields.io/pypi/v/boardwright)](https://pypi.org/project/boardwright/)
37
+ [![Python](https://img.shields.io/pypi/pyversions/boardwright)](https://pypi.org/project/boardwright/)
38
+ [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
39
+
33
40
  **Generate and edit KiCad boards and schematics from a short Python description,
34
41
  checked by KiCad itself.**
35
42
 
@@ -96,6 +103,19 @@ boardwright sch MYPROJ set R12 Value=4k7 # one block of the schematic repla
96
103
  boardwright live apply edit.py # the same edits to the board open in KiCad, one undo step
97
104
  ```
98
105
 
106
+ ## Exit codes
107
+
108
+ The same as the other [heibench](https://heibench.com/) tools, so a script or CI job can
109
+ branch on them:
110
+
111
+ | Code | Meaning |
112
+ |---|---|
113
+ | 0 | done: the board passed, or the edit was made |
114
+ | 1 | violated or refused: a finding about the design, or an edit not made |
115
+ | 2 | could not tell: a check could not be decided (a KiCad report is missing or stale) |
116
+ | 4 | environment fault: KiCad, a library or Freerouting missing or failing; never a verdict on the design |
117
+ | 64 | usage: bad arguments, or a spec naming parts, nets or layers that are not there |
118
+
99
119
  ## How it decides
100
120
 
101
121
  - **KiCad is the judge.** Nothing is "done" on the tool's own arithmetic. Every
@@ -133,6 +153,8 @@ board broke in the tool and what was changed.
133
153
 
134
154
  ## Documentation
135
155
 
156
+ The site is at **https://heibench.com/boardwright/**. In this repository:
157
+
136
158
  - [`docs/guide.md`](docs/guide.md): the full workflow, every `board.py` option, existing
137
159
  boards and schematics, the live KiCad client, and what the tool does badly.
138
160
  - [`docs/devlog/gaps.md`](docs/devlog/gaps.md): known limits.
@@ -1,5 +1,11 @@
1
1
  # boardwright
2
2
 
3
+ [![Check](https://github.com/heibench/boardwright/actions/workflows/check.yml/badge.svg)](https://github.com/heibench/boardwright/actions/workflows/check.yml)
4
+ [![Docs](https://github.com/heibench/boardwright/actions/workflows/docs.yml/badge.svg)](https://heibench.com/boardwright/)
5
+ [![PyPI](https://img.shields.io/pypi/v/boardwright)](https://pypi.org/project/boardwright/)
6
+ [![Python](https://img.shields.io/pypi/pyversions/boardwright)](https://pypi.org/project/boardwright/)
7
+ [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
8
+
3
9
  **Generate and edit KiCad boards and schematics from a short Python description,
4
10
  checked by KiCad itself.**
5
11
 
@@ -66,6 +72,19 @@ boardwright sch MYPROJ set R12 Value=4k7 # one block of the schematic repla
66
72
  boardwright live apply edit.py # the same edits to the board open in KiCad, one undo step
67
73
  ```
68
74
 
75
+ ## Exit codes
76
+
77
+ The same as the other [heibench](https://heibench.com/) tools, so a script or CI job can
78
+ branch on them:
79
+
80
+ | Code | Meaning |
81
+ |---|---|
82
+ | 0 | done: the board passed, or the edit was made |
83
+ | 1 | violated or refused: a finding about the design, or an edit not made |
84
+ | 2 | could not tell: a check could not be decided (a KiCad report is missing or stale) |
85
+ | 4 | environment fault: KiCad, a library or Freerouting missing or failing; never a verdict on the design |
86
+ | 64 | usage: bad arguments, or a spec naming parts, nets or layers that are not there |
87
+
69
88
  ## How it decides
70
89
 
71
90
  - **KiCad is the judge.** Nothing is "done" on the tool's own arithmetic. Every
@@ -103,6 +122,8 @@ board broke in the tool and what was changed.
103
122
 
104
123
  ## Documentation
105
124
 
125
+ The site is at **https://heibench.com/boardwright/**. In this repository:
126
+
106
127
  - [`docs/guide.md`](docs/guide.md): the full workflow, every `board.py` option, existing
107
128
  boards and schematics, the live KiCad client, and what the tool does badly.
108
129
  - [`docs/devlog/gaps.md`](docs/devlog/gaps.md): known limits.
@@ -29,4 +29,4 @@ boardwright existing examples/existing/stickhub review
29
29
  ```
30
30
 
31
31
  Then follow "First contact with a board you did not make" in
32
- [`docs/guide.md`](../../docs/guide.md).
32
+ the [guide](https://heibench.com/boardwright/guide/).
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "boardwright"
3
- version = "0.1.0"
3
+ version = "0.2.0"
4
4
  description = "Generate and edit KiCad boards and schematics from a short Python description, checked by KiCad itself."
5
5
  readme = "README.md"
6
6
  license = "Apache-2.0"
@@ -35,6 +35,7 @@ boardwright = "boardwright.cli:main"
35
35
 
36
36
  [project.urls]
37
37
  Homepage = "https://github.com/heibench/boardwright"
38
+ Documentation = "https://heibench.com/boardwright/"
38
39
  Issues = "https://github.com/heibench/boardwright/issues"
39
40
  Changelog = "https://github.com/heibench/boardwright/blob/main/CHANGELOG.md"
40
41
 
@@ -47,6 +48,8 @@ include = ["src", "tests", "README.md", "CHANGELOG.md", "LICENSE"]
47
48
 
48
49
  [dependency-groups]
49
50
  dev = ["pytest>=8", "ruff>=0.8"]
51
+ # Documentation site, built and deployed by .github/workflows/docs.yml.
52
+ docs = ["mkdocs-material>=9.5,<10"]
50
53
 
51
54
  [tool.ruff]
52
55
  line-length = 120
@@ -0,0 +1 @@
1
+ __version__ = "0.2.0"
@@ -23,6 +23,7 @@ from kicad_tools.schema.pcb import PCB
23
23
  from . import board as B
24
24
  from . import copper, env
25
25
  from .circuit import write_schematic
26
+ from .errors import EnvironmentFault, Usage
26
27
  from .project import vendor_libs, write_project
27
28
  from .review import review
28
29
  from .verify import compare
@@ -240,7 +241,7 @@ def _route_once(d: Path, m, pcb: Path, tag: str, bcost, passes: str) -> None:
240
241
  capture_output=True, text=True, timeout=getattr(m, "FR_TIMEOUT", 900))
241
242
  (d / "out" / f"freerouting{tag}.log").write_text(r.stdout + r.stderr)
242
243
  if not ses.exists():
243
- raise RuntimeError("freerouting produced no SES; see out/freerouting.log")
244
+ raise EnvironmentFault("freerouting produced no SES; see out/freerouting.log")
244
245
  B.kct("pcb", "import-ses", str(pcb), str(ses), "-o", str(pcb))
245
246
  # Freerouting necks traces down to squeeze between pads; never below the fab minimum.
246
247
  minw = (getattr(m, "RULES", None) or {}).get("min_track_width", 0.15)
@@ -357,11 +358,11 @@ def _violations(report: Path) -> list[dict]:
357
358
  def verify(d: Path) -> int:
358
359
  m = load(d)
359
360
  out = d / "out"
360
- ok = True
361
+ ok, missing = True, False
361
362
  for name in ("erc.json", "drc.json"):
362
363
  f = out / name
363
364
  if not f.exists():
364
- print(f"FAIL {name} missing -- run the KiCad gate (boardwright check)"); ok = False; continue
365
+ print(f"MISSING {name} -- run the KiCad gate (boardwright check)"); missing = True; continue
365
366
  vs = [v for v in _violations(f) if v.get("severity") != "exclusion"]
366
367
  print(f"{'OK ' if not vs else 'FAIL'} {name}: {len(vs)} violations")
367
368
  for v in vs[:40]:
@@ -374,21 +375,27 @@ def verify(d: Path) -> int:
374
375
  print(f"{'OK ' if not probs else 'FAIL'} netlist == intent", *probs, sep="\n ")
375
376
  ok &= not probs
376
377
  else:
377
- print("FAIL netlist.xml missing"); ok = False
378
+ print("MISSING netlist.xml -- run the KiCad gate (boardwright check)"); missing = True
378
379
  pcb = d / f"{m.NAME}.kicad_pcb"
379
380
  if (out / "drc.json").exists() and (out / "drc.json").stat().st_mtime < pcb.stat().st_mtime - 2:
380
- print("FAIL drc.json is older than the board -- rerun the gate"); ok = False
381
+ print("STALE drc.json is older than the board -- rerun the gate"); missing = True
381
382
  print("review:")
382
383
  rf = review(pcb, m)
383
384
  print(f"{'OK ' if not rf else 'FAIL'} review", *rf, sep="\n ")
384
385
  ok &= not rf
385
386
  gerbers = list((out / "gerbers").glob("*")) if (out / "gerbers").exists() else []
386
- print(f"{'OK ' if gerbers else 'FAIL'} gerbers+drill: {len(gerbers)} files")
387
- ok &= bool(gerbers)
387
+ print(f"{'OK ' if gerbers else 'MISSING'} gerbers+drill: {len(gerbers)} files")
388
+ missing |= not gerbers
388
389
  for svg in out.glob("*_Cu.svg"): # copper plots: the only view that shows pours and polygons
389
390
  subprocess.run(["rsvg-convert", "-w", "1500", "-b", "white", str(svg), "-o", str(svg.with_suffix(".png"))], check=False)
390
- print("PASS" if ok else "NOT DONE")
391
- return 0 if ok else 1
391
+ if not ok:
392
+ print("NOT DONE")
393
+ return 1
394
+ if missing:
395
+ print("CANNOT TELL: reports are missing or stale")
396
+ return 2
397
+ print("PASS")
398
+ return 0
392
399
 
393
400
 
394
401
  def check_parts(c, d: Path) -> None:
@@ -421,5 +428,7 @@ def pads(d: Path) -> int:
421
428
  def cli(argv: list[str]) -> int:
422
429
  argv = ["boardwright", *argv]
423
430
  d, step = Path(argv[1]).resolve(), argv[2]
431
+ if not (d / "board.py").exists():
432
+ raise Usage(f"{d} has no board.py")
424
433
  return ({"gen": lambda: gen(d) or 0, "verify": lambda: verify(d), "pads": lambda: pads(d),
425
434
  "place": lambda: place_only(d)}[step]())
@@ -14,6 +14,7 @@ import subprocess
14
14
  from pathlib import Path
15
15
 
16
16
  from . import env
17
+ from .errors import Usage
17
18
 
18
19
  _SVG = ["pcb", "export", "svg", "--exclude-drawing-sheet", "--page-size-mode", "2", "--mode-single"]
19
20
 
@@ -49,12 +50,12 @@ def check(d: Path, quick: bool = False) -> int:
49
50
  r = subprocess.run([*cli, *s], capture_output=True, text=True)
50
51
  if r.returncode != 0:
51
52
  print(f"FAILED: {' '.join([*cli, *s])}\n{r.stdout[-2000:]}{r.stderr[-2000:]}")
52
- return 1
53
+ return 4
53
54
  print("ok ", " ".join(s[:3]))
54
55
  return 0
55
56
 
56
57
 
57
58
  def cli(argv: list[str]) -> int:
58
59
  if not argv:
59
- raise SystemExit(__doc__)
60
+ raise Usage(__doc__)
60
61
  return check(Path(argv[0]).resolve(), "--quick" in argv[1:])
@@ -20,6 +20,9 @@ Lookups:
20
20
  boardwright pins LIB:SYMBOL [LIB:FOOTPRINT] [--libs DIR ...]
21
21
  boardwright impedance [STACKUP [Z | Z W]]
22
22
  boardwright doctor what this machine has for each step
23
+
24
+ Exit codes: 0 done, 1 refused or violated, 2 could not tell,
25
+ 4 environment fault (never a verdict on the design), 64 usage.
23
26
  """
24
27
 
25
28
  from __future__ import annotations
@@ -28,8 +31,11 @@ import importlib
28
31
  import importlib.metadata
29
32
  import shutil
30
33
  import sys
34
+ import traceback
35
+ from pathlib import Path
31
36
 
32
37
  from . import __version__
38
+ from .errors import Outcome, Usage
33
39
 
34
40
  _BUILD = {"gen", "place", "verify", "pads"}
35
41
  _MODULES = {
@@ -37,7 +43,7 @@ _MODULES = {
37
43
  "preview": "preview", "edits": "edits", "selection": "selection", "live": "live",
38
44
  "pins": "pins", "impedance": "si",
39
45
  }
40
- _NEEDS_LIBS = {"gen", "place", "pins", "sch"}
46
+ _NEEDS_LIBS = {"gen", "place", "pins"}
41
47
 
42
48
 
43
49
  def doctor() -> int:
@@ -64,11 +70,29 @@ def doctor() -> int:
64
70
  print(f"- {'kicad-python':<12} not installed; `live` needs boardwright[live]")
65
71
  rsvg = shutil.which("rsvg-convert")
66
72
  print(f"{'ok' if rsvg else '-':<5} {'rsvg-convert':<12} {rsvg or 'not found; previews stay SVG'}")
67
- return 0 if ok else 1
73
+ return 0 if ok else 4
68
74
 
69
75
 
70
76
  def main(argv: list[str] | None = None) -> int:
77
+ """Run one command. Exit codes are in boardwright.errors."""
71
78
  argv = sys.argv[1:] if argv is None else argv
79
+ try:
80
+ return _run(argv)
81
+ except Outcome as e:
82
+ print(e.message, file=sys.stderr)
83
+ return e.exit
84
+ except SystemExit as e: # a refusal: the edit was not made
85
+ if isinstance(e.code, str):
86
+ print(e.code, file=sys.stderr)
87
+ return 1
88
+ raise
89
+ except Exception:
90
+ traceback.print_exc()
91
+ print("boardwright: internal error; nothing was checked or written as a result", file=sys.stderr)
92
+ return 2
93
+
94
+
95
+ def _run(argv: list[str]) -> int:
72
96
  if not argv or argv[0] in ("-h", "--help", "help"):
73
97
  print(__doc__)
74
98
  return 0
@@ -78,21 +102,22 @@ def main(argv: list[str] | None = None) -> int:
78
102
  return 0
79
103
  if cmd == "doctor":
80
104
  return doctor()
81
- if cmd in _NEEDS_LIBS:
105
+ if cmd not in _BUILD and cmd not in _MODULES:
106
+ raise Usage(f"unknown command {cmd!r}\n{__doc__}")
107
+ if cmd in _BUILD and not (rest and (Path(rest[0]) / "board.py").exists()):
108
+ raise Usage(f"usage: boardwright {cmd} DIR, where DIR holds a board.py")
109
+ if cmd == "pins" and not rest:
110
+ raise Usage("usage: boardwright pins LIB:SYMBOL [LIB:FOOTPRINT] [--libs DIR ...]")
111
+ if cmd in _NEEDS_LIBS: # after the arguments are known to be usable
82
112
  from . import env
83
113
 
84
114
  env.use_libraries()
85
115
  if cmd in _BUILD:
86
- if not rest:
87
- raise SystemExit(f"usage: boardwright {cmd} DIR")
88
116
  from . import build
89
117
 
90
118
  return build.cli([rest[0], cmd])
91
- if cmd in _MODULES:
92
- mod = importlib.import_module(f".{_MODULES[cmd]}", __package__)
93
- return mod.cli(rest) or 0
94
- print(f"unknown command {cmd!r}\n{__doc__}", file=sys.stderr)
95
- return 2
119
+ mod = importlib.import_module(f".{_MODULES[cmd]}", __package__)
120
+ return mod.cli(rest) or 0
96
121
 
97
122
 
98
123
  if __name__ == "__main__":
@@ -32,6 +32,7 @@ import json
32
32
  from pathlib import Path
33
33
 
34
34
  from . import copper
35
+ from .errors import Usage
35
36
  from .model import Board
36
37
 
37
38
 
@@ -43,16 +44,16 @@ def from_spec(m, board: Board, project=None) -> dict:
43
44
  r = lambda v: round(v, 4)
44
45
  def need_net(n):
45
46
  if n not in nets:
46
- raise SystemExit(f"no net {n!r} on {board.path.name}")
47
+ raise Usage(f"no net {n!r} on {board.path.name}")
47
48
  return n
48
49
  ops = []
49
50
  if getattr(m, "ROUTES", None) and getattr(m, "MOVE", None):
50
- raise SystemExit("ROUTES are worked out on the board as it is; apply the MOVE first, then route in a second edit")
51
+ raise Usage("ROUTES are worked out on the board as it is; apply the MOVE first, then route in a second edit")
51
52
  from .route import expand
52
53
  rtracks, rvias = expand(m, board, ignore=set(getattr(m, "RIPUP", [])), project=project)
53
54
  for ref, pos in getattr(m, "MOVE", {}).items():
54
55
  if ref not in refs:
55
- raise SystemExit(f"no footprint {ref!r} on {board.path.name}")
56
+ raise Usage(f"no footprint {ref!r} on {board.path.name}")
56
57
  op = {"op": "move_footprint", "ref": ref, "x": r(pos[0] + ox), "y": r(pos[1] + oy)}
57
58
  if len(pos) > 2 and pos[2] is not None:
58
59
  op["rotation"] = pos[2]
@@ -68,7 +69,7 @@ def from_spec(m, board: Board, project=None) -> dict:
68
69
  width = t[2] if len(t) > 2 else 0.25
69
70
  layer = t[3] if len(t) > 3 else "F.Cu"
70
71
  if layer not in board.layers:
71
- raise SystemExit(f"{board.path.name} has no layer {layer}")
72
+ raise Usage(f"{board.path.name} has no layer {layer}")
72
73
  for (x1, y1), (x2, y2) in zip(t[1], t[1][1:]):
73
74
  ops.append({"op": "add_track", "net": need_net(t[0]), "x1": r(x1 + ox), "y1": r(y1 + oy),
74
75
  "x2": r(x2 + ox), "y2": r(y2 + oy), "width": width, "layer": layer})
@@ -88,7 +89,7 @@ def describe(doc: dict) -> list[str]:
88
89
  elif k == "add_track":
89
90
  out.append(f"track {o['net']} {o['layer']} w={o['width']}: ({o['x1']}, {o['y1']}) -> ({o['x2']}, {o['y2']})")
90
91
  else:
91
- raise SystemExit(f"unknown op {k!r}")
92
+ raise Usage(f"unknown op {k!r}")
92
93
  return out
93
94
 
94
95
 
@@ -102,7 +103,7 @@ def load_spec(path: str):
102
103
  def cli(argv: list[str]) -> int:
103
104
  argv = ["boardwright", *argv]
104
105
  if len(argv) not in (4, 5):
105
- raise SystemExit(__doc__)
106
+ raise Usage(__doc__)
106
107
  doc = from_spec(load_spec(argv[1]), Board(argv[2]), argv[4] if len(argv) == 5 else None)
107
108
  Path(argv[3]).write_text(json.dumps(doc, indent=1) + "\n")
108
109
  print(f"{len(doc['ops'])} op(s) -> {argv[3]} (absolute mm)")
@@ -17,6 +17,8 @@ import shutil
17
17
  import sys
18
18
  from pathlib import Path
19
19
 
20
+ from .errors import EnvironmentFault
21
+
20
22
  _FLATPAK_RT = "{root}/runtime/org.kicad.KiCad.Library.{kind}/x86_64/stable/active/files/{dir}"
21
23
 
22
24
 
@@ -43,7 +45,7 @@ def _library(dir_: str) -> Path:
43
45
  return Path(os.environ[var])
44
46
  cands = _library_candidates(dir_)
45
47
  if not cands:
46
- raise SystemExit(
48
+ raise EnvironmentFault(
47
49
  f"KiCad's {dir_} library was not found. Install KiCad's libraries or set KICAD_{name}_DIR."
48
50
  )
49
51
  return cands[0]
@@ -70,15 +72,18 @@ def use_libraries(sym: Path | None = None, fp: Path | None = None) -> None:
70
72
 
71
73
  def kicad_cli() -> list[str]:
72
74
  """The command prefix that runs kicad-cli (found the way netspec finds it)."""
73
- from kicad_netspec.oracle.discovery import find_kicad_cli
75
+ from kicad_netspec.oracle.discovery import KiCadNotFound, find_kicad_cli
74
76
 
75
- return list(find_kicad_cli().argv)
77
+ try:
78
+ return list(find_kicad_cli().argv)
79
+ except KiCadNotFound as e:
80
+ raise EnvironmentFault(str(e)) from None
76
81
 
77
82
 
78
83
  def freerouting() -> list[str]:
79
84
  cmd = shlex.split(os.environ.get("BOARDWRIGHT_FREEROUTING", "freerouting"))
80
85
  if not shutil.which(cmd[0]):
81
- raise SystemExit(
86
+ raise EnvironmentFault(
82
87
  f"Freerouting not found ({cmd[0]!r}). Install it or set BOARDWRIGHT_FREEROUTING, "
83
88
  'e.g. "java -jar /path/to/freerouting.jar".'
84
89
  )
@@ -0,0 +1,33 @@
1
+ """Exit codes, shared with the other heibench tools.
2
+
3
+ 0 done: the board passed, or the edit was made and checked
4
+ 1 refused or violated: a finding about the design, or an edit not made
5
+ 2 could not tell: a check that could not be decided (a report is missing)
6
+ 4 environment fault: KiCad, a library or Freerouting missing or failing,
7
+ or an input that cannot be read; never a verdict on the design
8
+ 64 usage: bad arguments, or a spec naming parts, nets or layers that are not there
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+
14
+ class Outcome(SystemExit):
15
+ """A SystemExit carrying a message and one of the codes above."""
16
+
17
+ exit = 1
18
+
19
+ def __init__(self, message: str):
20
+ super().__init__(message)
21
+ self.message = message
22
+
23
+
24
+ class CannotTell(Outcome):
25
+ exit = 2
26
+
27
+
28
+ class EnvironmentFault(Outcome):
29
+ exit = 4
30
+
31
+
32
+ class Usage(Outcome):
33
+ exit = 64
@@ -37,6 +37,7 @@ from pathlib import Path
37
37
 
38
38
  from . import board as B
39
39
  from . import copper, env
40
+ from .errors import CannotTell, EnvironmentFault, Usage
40
41
  from .model import Board
41
42
  from .preview import ratsnest
42
43
  from .preview import write as write_preview
@@ -46,7 +47,7 @@ from .review import review
46
47
  def find(d: Path) -> Path:
47
48
  pcbs = [p for p in d.glob("*.kicad_pcb") if not p.name.endswith(".solve.kicad_pcb")]
48
49
  if len(pcbs) != 1:
49
- raise SystemExit(f"{d}: expected exactly one .kicad_pcb, found {[p.name for p in pcbs]}")
50
+ raise EnvironmentFault(f"{d}: expected exactly one .kicad_pcb, found {[p.name for p in pcbs]}")
50
51
  return pcbs[0]
51
52
 
52
53
 
@@ -132,7 +133,7 @@ def do_review(d: Path) -> list[str]:
132
133
  def baseline(d: Path) -> int:
133
134
  o = out_dir(d)
134
135
  if not (o / "drc.json").exists():
135
- raise SystemExit("run the DRC first (boardwright_out/drc.json)")
136
+ raise CannotTell("run the DRC first (boardwright_out/drc.json)")
136
137
  (o / "drc_baseline.json").write_bytes((o / "drc.json").read_bytes())
137
138
  print(f"baseline: {len(_findings(o / 'drc.json'))} existing DRC finding(s) accepted")
138
139
  return 0
@@ -158,10 +159,10 @@ def verify(d: Path, staged: bool = False) -> int:
158
159
  print(f"note: no {pcb.stem}.kicad_sch beside the board, so KiCad did not check schematic parity")
159
160
  if not (o / "drc.json").exists() or not (o / "drc_baseline.json").exists():
160
161
  print("FAIL need boardwright_out/drc.json and a baseline (see module docstring)")
161
- return 1
162
+ return 2
162
163
  if (o / "drc.json").stat().st_mtime < pcb.stat().st_mtime - 2:
163
- print("FAIL drc.json is older than the board -- rerun the DRC")
164
- ok = False
164
+ print("STALE drc.json is older than the board -- rerun the DRC")
165
+ return 2
165
166
  old = _findings(o / "drc_baseline.json")
166
167
  new = _findings(o / "drc.json")
167
168
  left = list(old)
@@ -218,7 +219,7 @@ def apply(d: Path) -> int:
218
219
  p = PCB.load(str(pcb))
219
220
  for ref, (x, y, rot) in moves.items():
220
221
  if not p.update_footprint_position(ref, x, y, rot):
221
- raise SystemExit(f"no footprint {ref}")
222
+ raise Usage(f"no footprint {ref}")
222
223
  p.save(str(pcb))
223
224
  print(f"moved {len(moves)} footprint(s)")
224
225
  rip = set(getattr(m, "RIPUP", []))
@@ -311,7 +312,7 @@ def reroute(d: Path, nets_: list[str]) -> int:
311
312
  known = {p.net for p in b0.pads}
312
313
  for n in nets_:
313
314
  if n not in known:
314
- raise SystemExit(f"no net {n!r} (see `nets`)")
315
+ raise Usage(f"no net {n!r} (see `nets`)")
315
316
  original = pcb.read_text()
316
317
  names0 = dict(re.findall(r'\n\s*\(net (\d+) "([^"]*)"\)', original))
317
318
  was_open = {n for *_p, n in ratsnest(b0, set())}
@@ -328,7 +329,7 @@ def reroute(d: Path, nets_: list[str]) -> int:
328
329
  (o / "freerouting.log").write_text(r.stdout + r.stderr)
329
330
  if not ses.exists():
330
331
  pcb.write_text(text0)
331
- raise SystemExit("freerouting produced no SES; see boardwright_out/freerouting.log")
332
+ raise EnvironmentFault("freerouting produced no SES; see boardwright_out/freerouting.log")
332
333
  routed = pcb.with_suffix(".solve.kicad_pcb")
333
334
  B.kct("pcb", "import-ses", str(pcb), str(ses), "-o", str(routed))
334
335
  rt = routed.read_text()
@@ -369,8 +370,10 @@ def reroute(d: Path, nets_: list[str]) -> int:
369
370
  def cli(argv: list[str]) -> int:
370
371
  argv = ["boardwright", *argv]
371
372
  if len(argv) < 3:
372
- raise SystemExit(__doc__)
373
+ raise Usage(__doc__)
373
374
  d, step, rest = Path(argv[1]).resolve(), argv[2], argv[3:]
375
+ if step not in ("info", "pads", "nets", "review", "baseline", "verify", "stage", "apply", "reroute"):
376
+ raise Usage(f"unknown step {step!r}\n{__doc__}")
374
377
  return ({"info": lambda: info(d), "pads": lambda: pads(d, rest), "nets": lambda: nets(d, rest[0] if rest else "*"),
375
378
  "review": lambda: 1 if do_review(d) else 0, "baseline": lambda: baseline(d),
376
379
  "verify": lambda: verify(d, "--staged" in rest), "stage": lambda: stage(d, Path(rest[0]).resolve()),
@@ -32,6 +32,7 @@ import importlib.util
32
32
  import types
33
33
  from pathlib import Path
34
34
 
35
+ from .errors import EnvironmentFault, Usage
35
36
  from .model import Board
36
37
 
37
38
 
@@ -53,7 +54,7 @@ def connect():
53
54
  hint = ("The socket exists but this process may not open it."
54
55
  if isinstance(e, PermissionError) or "ermission" in str(e) else
55
56
  "Is KiCad running with the PCB editor open and Preferences > Plugins > Enable KiCad API switched on?")
56
- raise SystemExit(f"cannot reach KiCad ({type(e).__name__}: {e}). {hint}") from e
57
+ raise EnvironmentFault(f"cannot reach KiCad ({type(e).__name__}: {e}). {hint}") from e
57
58
  return k
58
59
 
59
60
 
@@ -61,7 +62,7 @@ def board_of(k):
61
62
  try:
62
63
  return k.get_board()
63
64
  except Exception as e:
64
- raise SystemExit(f"KiCad is running but no board is open in the PCB editor ({type(e).__name__}: {e})") from e
65
+ raise EnvironmentFault(f"KiCad is running but no board is open in the PCB editor ({type(e).__name__}: {e})") from e
65
66
 
66
67
 
67
68
  def snapshot(b, out: Path) -> Path:
@@ -104,7 +105,7 @@ def apply(k, b, doc: dict, save: bool) -> None:
104
105
  nets = {n.name: n for n in b.get_nets()}
105
106
  def net(name):
106
107
  if name not in nets:
107
- raise SystemExit(f"no net {name!r} on the open board")
108
+ raise Usage(f"no net {name!r} on the open board")
108
109
  return nets[name]
109
110
  # kicad-python 0.8.0 cannot name the document in BeginCommit, and KiCad
110
111
  # refuses an unnamed one while the schematic editor is also open. Then the
@@ -151,7 +152,7 @@ def apply(k, b, doc: dict, save: bool) -> None:
151
152
  tr.width, tr.layer, tr.net = from_mm(o["width"]), _layer(o["layer"]), net(o["net"])
152
153
  made += len(b.create_items([tr]))
153
154
  else:
154
- raise SystemExit(f"unknown op {kind!r}")
155
+ raise Usage(f"unknown op {kind!r}")
155
156
  except BaseException:
156
157
  if commit is not None:
157
158
  b.drop_commit(commit)
@@ -171,9 +172,9 @@ def main(argv: list[str]) -> int:
171
172
  try:
172
173
  import kipy # noqa: F401
173
174
  except ImportError:
174
- raise SystemExit('boardwright live needs the live extra: pip install "boardwright[live]"') from None
175
+ raise EnvironmentFault('boardwright live needs the live extra: pip install "boardwright[live]"') from None
175
176
  if not argv:
176
- raise SystemExit(__doc__)
177
+ raise Usage(__doc__)
177
178
  cmd, rest = argv[0], argv[1:]
178
179
  flags = {a for a in rest if a.startswith("--")}
179
180
  args = [a for a in rest if not a.startswith("--")]
@@ -181,7 +182,7 @@ def main(argv: list[str]) -> int:
181
182
  if cmd == "apply" and "--dry-run" in flags: # no connection needed
182
183
  from . import edits
183
184
  if not args[0].endswith(".json") and len(args) < 2:
184
- raise SystemExit("a dry run from a spec needs the board file too: apply SPEC.py BOARD.kicad_pcb --dry-run")
185
+ raise Usage("a dry run from a spec needs the board file too: apply SPEC.py BOARD.kicad_pcb --dry-run")
185
186
  doc = edit_list(args[0], Path(args[1]) if len(args) > 1 else None)
186
187
  print(*(" " + l for l in edits.describe(doc)), sep="\n")
187
188
  return 0
@@ -251,7 +252,7 @@ def main(argv: list[str]) -> int:
251
252
  print(*(" " + l for l in edits.describe(doc)), sep="\n")
252
253
  apply(k, b, doc, "--save" in flags)
253
254
  return 0
254
- raise SystemExit(__doc__)
255
+ raise Usage(__doc__)
255
256
 
256
257
 
257
258
  cli = main
@@ -46,6 +46,7 @@ import uuid
46
46
  from pathlib import Path
47
47
 
48
48
  from .copper import blocks
49
+ from .errors import EnvironmentFault, Usage
49
50
 
50
51
  GRID = 1.27
51
52
 
@@ -86,7 +87,7 @@ def refs(block: str) -> list[str]:
86
87
  def sheets(d: Path) -> list[Sheet]:
87
88
  files = sorted(p for p in d.glob("*.kicad_sch") if not p.name.startswith(("~", "_")))
88
89
  if not files:
89
- raise SystemExit(f"no .kicad_sch in {d}")
90
+ raise EnvironmentFault(f"no .kicad_sch in {d}")
90
91
  return [Sheet(p) for p in files]
91
92
 
92
93
 
@@ -96,7 +97,7 @@ def root(d: Path) -> Sheet:
96
97
  return Sheet(pros[0].with_suffix(".kicad_sch"))
97
98
  ss = sheets(d)
98
99
  if len(ss) != 1:
99
- raise SystemExit("cannot tell which sheet is the root: expected <project>.kicad_sch beside one .kicad_pro")
100
+ raise EnvironmentFault("cannot tell which sheet is the root: expected <project>.kicad_sch beside one .kicad_pro")
100
101
  return ss[0]
101
102
 
102
103
 
@@ -140,13 +141,13 @@ def set_fields(d: Path, ref: str, pairs: list[str]) -> int:
140
141
  name, _, val = pair.partition("=")
141
142
  if name in ("dnp", "in_bom", "on_board"):
142
143
  if val not in ("yes", "no"):
143
- raise SystemExit(f"{name} takes yes or no")
144
+ raise Usage(f"{name} takes yes or no")
144
145
  nb, n = re.subn(r"\(%s (?:yes|no)\)" % name, f"({name} {val})", b, count=1)
145
146
  else:
146
147
  old = prop(b, name)
147
148
  if old is None:
148
149
  have = ", ".join(re.findall(r'\(property "([^"]*)"', b))
149
- raise SystemExit(f"{ref} has no property {name!r} (it has: {have})")
150
+ raise Usage(f"{ref} has no property {name!r} (it has: {have})")
150
151
  esc = val.replace("\\", "\\\\").replace('"', '\\"')
151
152
  nb, n = re.subn(r'(\(property "%s" )"(?:[^"\\]|\\.)*"' % re.escape(name), lambda m: f'{m.group(1)}"{esc}"', b, count=1)
152
153
  if name == "Reference":
@@ -286,9 +287,9 @@ def add(d: Path, spec_path: str) -> int:
286
287
  new = []
287
288
  for i, (ref, like, value, footprint, pins) in enumerate(m.ADD):
288
289
  if ref in by_ref:
289
- raise SystemExit(f"{ref} already exists")
290
+ raise Usage(f"{ref} already exists")
290
291
  if like not in by_ref:
291
- raise SystemExit(f"no part {like!r} to copy")
292
+ raise Usage(f"no part {like!r} to copy")
292
293
  src = by_ref[like]
293
294
  lib_id = re.search(r'\(lib_id "([^"]*)"', src).group(1)
294
295
  lp = _lib_pins(t, lib_id)
@@ -301,7 +302,7 @@ def add(d: Path, spec_path: str) -> int:
301
302
  new.append(b)
302
303
  for num, net in {str(k): v for k, v in pins.items()}.items():
303
304
  if num not in lp:
304
- raise SystemExit(f"{lib_id} has no pin {num} (it has {sorted(lp)})")
305
+ raise Usage(f"{lib_id} has no pin {num} (it has {sorted(lp)})")
305
306
  px, py, ang = lp[num]
306
307
  sx, sy = x + px, y - py # the pin's connection point on the sheet
307
308
  a = math.radians(ang + 180)
@@ -373,8 +374,10 @@ def cli(argv: list[str]) -> int:
373
374
  if len(a) >= 3 and a[0] == "ercdiff":
374
375
  return (ercdiff(a[1], a[2]))
375
376
  if len(a) < 2:
376
- raise SystemExit(__doc__)
377
+ raise Usage(__doc__)
377
378
  d, cmd, rest = Path(a[0]).resolve(), a[1], a[2:]
379
+ if cmd not in ("parts", "set", "remove", "add") or (cmd != "parts" and not rest):
380
+ raise Usage(__doc__)
378
381
  return ({"parts": lambda: parts(d, rest[0] if rest else "*"),
379
382
  "set": lambda: set_fields(d, rest[0], rest[1:]),
380
383
  "remove": lambda: remove(d, rest),
@@ -17,6 +17,7 @@ import shutil
17
17
  import tempfile
18
18
  from pathlib import Path
19
19
 
20
+ from .errors import Usage
20
21
  from .model import Board
21
22
 
22
23
 
@@ -62,6 +63,6 @@ def describe(sel_file: Path, board_file: Path) -> list[str]:
62
63
  def cli(argv: list[str]) -> int:
63
64
  argv = ["boardwright", *argv]
64
65
  if len(argv) != 3:
65
- raise SystemExit(__doc__)
66
+ raise Usage(__doc__)
66
67
  print(*describe(Path(argv[1]), Path(argv[2])), sep="\n")
67
68
  return 0
@@ -35,7 +35,7 @@ def _have_kicad_cli() -> bool:
35
35
  try:
36
36
  env.kicad_cli()
37
37
  return True
38
- except Exception:
38
+ except SystemExit:
39
39
  return False
40
40
 
41
41
 
@@ -55,7 +55,7 @@ def test_cli_version_and_help(capsys):
55
55
  assert capsys.readouterr().out.startswith("boardwright ")
56
56
  assert main([]) == 0
57
57
  assert "boardwright gen DIR" in capsys.readouterr().out
58
- assert main(["no-such-command"]) == 2
58
+ assert main(["no-such-command"]) == 64
59
59
 
60
60
 
61
61
  def test_cli_review_exit_codes(tmp_path):
@@ -69,3 +69,38 @@ def test_cli_review_exit_codes(tmp_path):
69
69
  bad = subprocess.run([sys.executable, "-m", "boardwright", "review", str(board("ldo_breakout")), str(spec)],
70
70
  capture_output=True, text=True)
71
71
  assert bad.returncode == 1 and "LED_A" in bad.stdout
72
+
73
+
74
+ @pytest.fixture(params=["kicad present", "kicad absent"])
75
+ def machine(request, monkeypatch):
76
+ """Run under this machine's KiCad, and again as if none were installed."""
77
+ if request.param == "kicad absent":
78
+ from boardwright import env
79
+
80
+ for v in ("KICAD", "KICAD10", "KICAD9"):
81
+ monkeypatch.delenv(f"{v}_SYMBOL_DIR", raising=False)
82
+ monkeypatch.delenv(f"{v}_FOOTPRINT_DIR", raising=False)
83
+ monkeypatch.setattr(env, "_library_candidates", lambda dir_: [])
84
+ monkeypatch.setenv("NETSPEC_KICAD_CLI", "/nonexistent/kicad-cli")
85
+ monkeypatch.setenv("BOARDWRIGHT_FREEROUTING", "/nonexistent/freerouting")
86
+ return request.param
87
+
88
+
89
+ def test_exit_codes_follow_the_heibench_contract(ldo_copy, monkeypatch, capsys, machine):
90
+ # 64 usage: bad arguments, or a spec naming something that is not there
91
+ assert main(["gen"]) == 64
92
+ assert main(["gen", str(ldo_copy / "nowhere")]) == 64
93
+ assert main(["pins"]) == 64
94
+ assert main(["no-such-command"]) == 64
95
+ assert main(["sch", str(ldo_copy), "set", "R1", "Colour=blue"]) == 64
96
+ assert main(["existing", str(ldo_copy), "no-such-step"]) == 64
97
+ # 2 could not tell: verify with no KiCad reports is not a verdict
98
+ assert main(["verify", str(ldo_copy)]) == 2
99
+ assert "CANNOT TELL" in capsys.readouterr().out
100
+ # 4 environment fault: no KiCad to run
101
+ monkeypatch.setenv("NETSPEC_KICAD_CLI", "/nonexistent/kicad-cli")
102
+ assert main(["check", str(ldo_copy)]) == 4
103
+ # 1 violated: a finding about the design
104
+ spec = ldo_copy / "spec.py"
105
+ spec.write_text('REVIEW = {"maxlen": {"LED_A": 0.1}}\n')
106
+ assert main(["review", str(ldo_copy / "ldo_breakout.kicad_pcb"), str(spec)]) == 1
@@ -1 +0,0 @@
1
- __version__ = "0.1.0"
File without changes