datasheets-md 2.2.0__tar.gz → 2.3.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 (30) hide show
  1. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/PKG-INFO +2 -1
  2. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/README.md +1 -0
  3. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/src/datasheets_md/__init__.py +1 -1
  4. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/src/datasheets_md/agents.md +45 -2
  5. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/src/datasheets_md/cli.py +21 -0
  6. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/src/datasheets_md/sync.py +53 -1
  7. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/src/datasheets_md.egg-info/PKG-INFO +2 -1
  8. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/tests/test_sync.py +38 -1
  9. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/pyproject.toml +0 -0
  10. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/setup.cfg +0 -0
  11. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/src/datasheets_md/auth.py +0 -0
  12. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/src/datasheets_md/gui/__init__.py +0 -0
  13. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/src/datasheets_md/gui/__main__.py +0 -0
  14. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/src/datasheets_md/gui/app.py +0 -0
  15. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/src/datasheets_md/gui/icon.png +0 -0
  16. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/src/datasheets_md/http.py +0 -0
  17. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/src/datasheets_md/library.py +0 -0
  18. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/src/datasheets_md/merge.py +0 -0
  19. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/src/datasheets_md/repo.py +0 -0
  20. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/src/datasheets_md/update.py +0 -0
  21. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/src/datasheets_md.egg-info/SOURCES.txt +0 -0
  22. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/src/datasheets_md.egg-info/dependency_links.txt +0 -0
  23. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/src/datasheets_md.egg-info/entry_points.txt +0 -0
  24. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/src/datasheets_md.egg-info/requires.txt +0 -0
  25. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/src/datasheets_md.egg-info/top_level.txt +0 -0
  26. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/tests/test_gui_launcher.py +0 -0
  27. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/tests/test_gui_package.py +0 -0
  28. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/tests/test_merge.py +0 -0
  29. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/tests/test_resume.py +0 -0
  30. {datasheets_md-2.2.0 → datasheets_md-2.3.0}/tests/test_update.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: datasheets-md
3
- Version: 2.2.0
3
+ Version: 2.3.0
4
4
  Summary: dsmd: a git-like working copy of your datasheets.md workspace (parameters, pins, CAD config, KiCad library)
5
5
  Author: datasheets.md
6
6
  License-Expression: MIT
@@ -70,6 +70,7 @@ dsmd categories # catalogue category ids, for mapping file
70
70
  dsmd feedback "a setting I need" # tell the datasheets.md team (--kind bug|suggestion)
71
71
  dsmd gui # the desktop app (needs datasheets-md-gui)
72
72
  dsmd self-update # upgrade to the latest release (--check only asks)
73
+ dsmd confirm <part> [item ...] # confirm CAD review items or rows; push sends them
73
74
  dsmd help agents # the guide for AI agents
74
75
  ```
75
76
 
@@ -51,6 +51,7 @@ dsmd categories # catalogue category ids, for mapping file
51
51
  dsmd feedback "a setting I need" # tell the datasheets.md team (--kind bug|suggestion)
52
52
  dsmd gui # the desktop app (needs datasheets-md-gui)
53
53
  dsmd self-update # upgrade to the latest release (--check only asks)
54
+ dsmd confirm <part> [item ...] # confirm CAD review items or rows; push sends them
54
55
  dsmd help agents # the guide for AI agents
55
56
  ```
56
57
 
@@ -1,7 +1,7 @@
1
1
  """datasheets-md: the `dsmd` CLI and the dBsync GUI on one sync engine."""
2
2
  from pathlib import Path
3
3
 
4
- __version__ = "2.2.0"
4
+ __version__ = "2.3.0"
5
5
  APP_NAME = "dBsync"
6
6
 
7
7
 
@@ -35,14 +35,57 @@ shell; add `--json` to any command for machine-readable output.
35
35
  `dsmd pdf <part>` downloads the original PDF.
36
36
  - When you correct a value, set `source` to the element you read it from:
37
37
  `"source": {"element_id": "<id>"}`.
38
- - To confirm a row is right, change its `review` from `unchecked` to
39
- `confirmed`. Unconfirming is not supported.
38
+ - To confirm a row is right, run `dsmd confirm <part> <k>` (or change its
39
+ `review` from `unchecked` to `confirmed`). Unconfirming a parameter row is
40
+ not supported. Every confirmation carries your name and the time.
40
41
  - Never edit `library/` (generated), `part.yaml` or `datasheet.md`
41
42
  (read-only); `push` refuses them. `dsmd restore <path>` undoes a local edit.
42
43
  - Conflict markers (`<<<<<<< local` / `=======` / `>>>>>>> server`) after a
43
44
  pull surround one row (or, in a YAML file, the whole file): keep the right
44
45
  side, delete the markers, push.
45
46
 
47
+ ## Reviewing a part's CAD
48
+
49
+ The last lines of `parameters.jsonl` (section `cad_review`, `k` = `cad:<item>`)
50
+ are the part's CAD review checklist, the same one the web page shows at the
51
+ top of the CAD data tab:
52
+
53
+ | item | what you check | against |
54
+ |---|---|---|
55
+ | `package_type` | the part number comes in this package | the ordering / package table in `datasheet.md` and the `Package / Case` row |
56
+ | `package_dimensions` | the body and lead dimensions the footprint is built from | the package drawing |
57
+ | `pin_table` | every pin's number, name and electrical type | the pin table; `pins.csv` |
58
+ | `pin_map` | which pins are on the symbol and which pad each pin is | the pinout figure; `pins.csv` (`on_symbol`), `cad.yaml` (`pad_map`, `pin_map`) |
59
+ | `footprint` | the land pattern | the recommended land pattern; `cad.yaml` `footprint` |
60
+ | `symbol` | the symbol you place | `cad.yaml` `symbol` |
61
+
62
+ Only `review` of these lines is yours to change; their `name`, `value` and
63
+ `version` say what the item is now. A part without CAD or a package drawing
64
+ lists fewer items. To review:
65
+
66
+ 1. `dsmd pull`, then `dsmd confirm <part>` lists the items and their state.
67
+ 2. Compare each item with the datasheet (`datasheet.md` next to the part's
68
+ PDF, or `dsmd pdf <part>`). Look at the figures in `images/` for pinouts,
69
+ package drawings and land patterns.
70
+ 3. If something is wrong, correct it first, in the file that holds it:
71
+ `pins.csv` for pins, `cad.yaml` for symbol and footprint, the row in
72
+ `parameters.jsonl` for the package type (and `source.element_id` to say
73
+ where you read it). Package dimensions are not in the files yet: when they
74
+ are wrong, leave `package_dimensions` unchecked and tell the user.
75
+ 4. `dsmd confirm <part> pin_table pin_map ...` for each item you checked and
76
+ found right. Confirming `pin_map` also confirms `pin_table`. Never confirm
77
+ an item you did not compare. `--undo` sets an item back before the push,
78
+ and after it takes back your own confirmation.
79
+ 5. `dsmd diff`, show it to the user, then `dsmd push -m "CAD review: ..."`.
80
+ Corrections are applied first, so what you confirm is the corrected data.
81
+ The confirmations are recorded under your name with the time; the web
82
+ page shows "Reviewed by <name>" once you have confirmed every item.
83
+
84
+ A later change to an item's data (a pin renamed, the footprint swapped, a
85
+ dimension corrected) reopens that item: after a pull its line says
86
+ `unchecked` again with a new `version`. `package_dimensions` is refused while
87
+ the drawing misses a dimension the package needs; the push says so.
88
+
46
89
  ## Workspace settings
47
90
 
48
91
  Both files are YAML, pushed with the parts (settings first, so a category you
@@ -195,6 +195,21 @@ def cmd_part(args, out):
195
195
  out.result(done, f"Removed {path}")
196
196
 
197
197
 
198
+ def cmd_confirm(args, out):
199
+ repo = Repo.find(args.C or ".")
200
+ with repo.lock():
201
+ done = sync.confirm(repo, args.part, args.items, undo=args.undo)
202
+ if args.items:
203
+ word = "unchecked" if args.undo else "confirmed"
204
+ text = "\n".join(f"{word:<10}{key}" for key in done["changed"]) or "Nothing changed."
205
+ if done["changed"]:
206
+ text += f"\nIn {done['path']} only; dsmd push -m \"...\" sends it."
207
+ else:
208
+ text = "\n".join(f"{i['review']:<10}{i['item']:<20}{i.get('value') or ''} ({i.get('version') or '-'})"
209
+ for i in done["items"]) or "This part has no CAD review items (no CAD yet, or run dsmd pull)."
210
+ out.result(done, text)
211
+
212
+
198
213
  def cmd_pdf(args, out):
199
214
  repo, client = _repo_client(args)
200
215
  path = sync.pdf(repo, client, args.part)
@@ -328,6 +343,12 @@ def parser():
328
343
  prm = part_sub.add_parser("rm", parents=[common], help="remove a part from the workspace")
329
344
  prm.add_argument("ident", help="part number, uuid or folder")
330
345
  prm.add_argument("--yes", "-y", action="store_true", help="do not ask")
346
+ cmd = add("confirm", cmd_confirm, "confirm review items of a part (CAD review items or parameter rows); "
347
+ "without items, list its CAD review items")
348
+ cmd.add_argument("part", help="part number, uuid or folder")
349
+ cmd.add_argument("items", nargs="*", help="package_type, package_dimensions, pin_table, pin_map, footprint, symbol, "
350
+ "or a parameter row's k")
351
+ cmd.add_argument("--undo", action="store_true", help="set the items back to unchecked")
331
352
  add("pdf", cmd_pdf, "download a part's PDF into .dsmd/cache and print its path").add_argument("part")
332
353
  add("open", cmd_open, "open a part's web page").add_argument("part")
333
354
  add("categories", cmd_categories, "list the catalogue categories (the ids a mapping file's category_map uses)")
@@ -694,6 +694,58 @@ def feedback(client, message, kind="other"):
694
694
  "context": {"client": f"dsmd {__version__}"}})
695
695
 
696
696
 
697
+ REVIEW_SECTION, REVIEW_PREFIX = "cad_review", "cad:"
698
+
699
+
700
+ def _line(obj):
701
+ """A parameters.jsonl line as the server writes it, so a confirm diffs as one word."""
702
+ return json.dumps(obj, ensure_ascii=False, separators=(",", ":"))
703
+
704
+
705
+ def confirm(repo, ident, items=(), undo=False):
706
+ """Mark review items of a part `confirmed` (or `unchecked` with `undo`) in its working
707
+ parameters.jsonl; `dsmd push` sends them. An item is a CAD review item (`pin_map` or
708
+ `cad:pin_map`) or a parameter row's `k`. No items: list the part's CAD review items."""
709
+ uuid = repo.resolve(ident)
710
+ rel = f"{repo.parts()[uuid]['path']}/parameters.jsonl"
711
+ text = repo.read(repo.working(rel))
712
+ if text is None:
713
+ raise RepoError(f"{rel} is missing; run dsmd restore {rel}")
714
+ if has_conflict(text):
715
+ raise RepoError(f"{rel} has conflict markers; resolve them first")
716
+ lines = text.splitlines()
717
+ rows = {}
718
+ for index, raw in enumerate(lines):
719
+ try:
720
+ obj = json.loads(raw) if raw.strip() else None
721
+ except ValueError:
722
+ raise RepoError(f"{rel}:{index + 1} is not valid JSON; fix it first") from None
723
+ if isinstance(obj, dict) and obj.get("k"):
724
+ rows[obj["k"]] = (index, obj)
725
+ review = [obj for _, obj in rows.values() if obj.get("section") == REVIEW_SECTION]
726
+ if not items:
727
+ return {"path": rel, "items": [{"item": obj["k"][len(REVIEW_PREFIX):], **obj} for obj in review], "changed": []}
728
+ want = "unchecked" if undo else "confirmed"
729
+ changed = []
730
+ for item in items:
731
+ key = item if item in rows else REVIEW_PREFIX + item
732
+ if key not in rows:
733
+ names = ", ".join(obj["k"][len(REVIEW_PREFIX):] for obj in review) or "none (no CAD, or run dsmd pull)"
734
+ raise RepoError(f"{rel} has no item {item!r}; CAD review items: {names}")
735
+ index, obj = rows[key]
736
+ if obj.get("review") == "edited":
737
+ if undo:
738
+ raise RepoError(f"{key} was edited, which confirms it; it cannot be unchecked")
739
+ continue
740
+ if obj.get("review") != want:
741
+ obj["review"] = want
742
+ lines[index] = _line(obj)
743
+ changed.append(key)
744
+ if changed:
745
+ repo.write(repo.working(rel), "\n".join(lines) + "\n")
746
+ return {"path": rel, "items": [{"item": obj["k"][len(REVIEW_PREFIX):], **obj} for obj in review], "changed": changed}
747
+
748
+
697
749
  def web_url(repo, ident):
698
750
  uuid = repo.resolve(ident)
699
751
  text = repo.read(repo.base(f"{repo.parts()[uuid]['path']}/part.yaml")) or "{}"
@@ -709,4 +761,4 @@ def open_part(repo, ident):
709
761
 
710
762
 
711
763
  __all__ = ["ApiError", "RepoError", "PushRefused", "clone", "fetch", "pull", "status", "diff", "restore",
712
- "push", "log", "part_add", "part_rm", "pdf", "open_part", "build_library", "resolve_workspace", "feedback", "categories"]
764
+ "push", "log", "part_add", "part_rm", "confirm", "pdf", "open_part", "build_library", "resolve_workspace", "feedback", "categories"]
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: datasheets-md
3
- Version: 2.2.0
3
+ Version: 2.3.0
4
4
  Summary: dsmd: a git-like working copy of your datasheets.md workspace (parameters, pins, CAD config, KiCad library)
5
5
  Author: datasheets.md
6
6
  License-Expression: MIT
@@ -70,6 +70,7 @@ dsmd categories # catalogue category ids, for mapping file
70
70
  dsmd feedback "a setting I need" # tell the datasheets.md team (--kind bug|suggestion)
71
71
  dsmd gui # the desktop app (needs datasheets-md-gui)
72
72
  dsmd self-update # upgrade to the latest release (--check only asks)
73
+ dsmd confirm <part> [item ...] # confirm CAD review items or rows; push sends them
73
74
  dsmd help agents # the guide for AI agents
74
75
  ```
75
76
 
@@ -1,7 +1,7 @@
1
1
  import json
2
2
 
3
3
  import pytest
4
- from conftest import PART, PATH, SHEET, etag
4
+ from conftest import PART, PATH, SHEET, etag, jsonl, row
5
5
 
6
6
  from datasheets_md import cli, sync
7
7
  from datasheets_md.repo import Repo, RepoError
@@ -344,3 +344,40 @@ def test_incremental_pull_reads_only_changes_and_deletions(tmp_path, server):
344
344
  server.delete(PART)
345
345
  assert sync.pull(repo, server)["removed_parts"] == 1
346
346
  assert repo.parts() == {} and repo.state["cursor"] == "1.1"
347
+
348
+
349
+ def _review_rows(repo):
350
+ rel = f"{PATH}/parameters.jsonl"
351
+ text = repo.read(repo.working(rel)) + jsonl(row("cad:pin_map", "Pin mapping", "2 symbol pins, 0 pads", section="cad_review"),
352
+ row("cad:symbol", "Symbol", "Generated", section="cad_review"))
353
+ repo.put(rel, text)
354
+ return rel
355
+
356
+
357
+ def test_confirm_lists_and_flips_only_the_review_word(repo):
358
+ rel = _review_rows(repo)
359
+ listed = sync.confirm(repo, "SN74HC00N")
360
+ assert [i["item"] for i in listed["items"]] == ["pin_map", "symbol"] and not listed["changed"]
361
+ done = sync.confirm(repo, "SN74HC00N", ["pin_map", "a1"])
362
+ assert done["changed"] == ["cad:pin_map", "a1"]
363
+ changed = [line for line in sync.diff(repo).splitlines() if line[:1] in "+-" and line[1:2] == "{"]
364
+ assert sorted(line.replace("confirmed", "unchecked")[1:] for line in changed if line[0] == "+") == \
365
+ sorted(line[1:] for line in changed if line[0] == "-")
366
+ assert sync.confirm(repo, "SN74HC00N", ["pin_map"])["changed"] == []
367
+ sync.confirm(repo, "SN74HC00N", ["pin_map", "a1"], undo=True)
368
+ assert sync.diff(repo) == "" and repo.read(repo.working(rel)) == repo.read(repo.base(rel))
369
+
370
+
371
+ def test_confirm_names_the_items_it_knows(repo):
372
+ _review_rows(repo)
373
+ with pytest.raises(RepoError, match="pin_map, symbol"):
374
+ sync.confirm(repo, "SN74HC00N", ["footprint"])
375
+
376
+
377
+ def test_cli_confirm(repo, capsys):
378
+ _review_rows(repo)
379
+ assert cli.main(["-C", str(repo.root), "confirm", "SN74HC00N", "symbol"]) == 0
380
+ assert "confirmed cad:symbol" in capsys.readouterr().out.replace(" ", " ").replace(" ", " ")
381
+ assert cli.main(["--json", "-C", str(repo.root), "confirm", "SN74HC00N"]) == 0
382
+ items = json.loads(capsys.readouterr().out)["items"]
383
+ assert {i["item"]: i["review"] for i in items} == {"pin_map": "unchecked", "symbol": "confirmed"}
File without changes