traceforge-pcb 1.0.0__py3-none-any.whl

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 (219) hide show
  1. traceforge/__init__.py +3 -0
  2. traceforge/__main__.py +3 -0
  3. traceforge/acp_server.py +570 -0
  4. traceforge/agent.py +680 -0
  5. traceforge/altium/__init__.py +6 -0
  6. traceforge/altium/cfb.py +70 -0
  7. traceforge/altium/cli.py +60 -0
  8. traceforge/altium/model.py +163 -0
  9. traceforge/altium/outputs.py +24 -0
  10. traceforge/altium/pcb.py +301 -0
  11. traceforge/altium/project.py +328 -0
  12. traceforge/altium/schematic.py +400 -0
  13. traceforge/altium/tools.py +166 -0
  14. traceforge/approval.py +219 -0
  15. traceforge/attachments.py +346 -0
  16. traceforge/background.py +253 -0
  17. traceforge/bench/__init__.py +5 -0
  18. traceforge/bench/adapters.py +337 -0
  19. traceforge/bench/checks.py +410 -0
  20. traceforge/bench/cli.py +121 -0
  21. traceforge/bench/design.py +439 -0
  22. traceforge/bench/kicad.py +99 -0
  23. traceforge/bench/partscheck.py +159 -0
  24. traceforge/bench/review.py +100 -0
  25. traceforge/bench/runner.py +226 -0
  26. traceforge/bench/score.py +204 -0
  27. traceforge/bench/tasks.py +102 -0
  28. traceforge/chat.py +1185 -0
  29. traceforge/checks.py +328 -0
  30. traceforge/checks_sides.py +118 -0
  31. traceforge/cli.py +2224 -0
  32. traceforge/clipboard.py +107 -0
  33. traceforge/config.py +299 -0
  34. traceforge/context.py +276 -0
  35. traceforge/design/__init__.py +1 -0
  36. traceforge/design/constraints.py +397 -0
  37. traceforge/design/generate.py +1789 -0
  38. traceforge/design/outline.py +905 -0
  39. traceforge/design/schematic_layout.py +932 -0
  40. traceforge/design/schematic_lint.py +329 -0
  41. traceforge/design/schematic_route.py +207 -0
  42. traceforge/design/sheets.py +854 -0
  43. traceforge/design/sides.py +328 -0
  44. traceforge/design/spec.py +462 -0
  45. traceforge/design/specsheet.py +2351 -0
  46. traceforge/design/specsheet_render.py +183 -0
  47. traceforge/desktop/__init__.py +109 -0
  48. traceforge/desktop/keys.py +90 -0
  49. traceforge/desktop/project.py +443 -0
  50. traceforge/desktop/review.py +20 -0
  51. traceforge/desktop/server.py +1277 -0
  52. traceforge/desktop/static/app.css +223 -0
  53. traceforge/desktop/static/app.js +683 -0
  54. traceforge/desktop/static/highlight.js +77 -0
  55. traceforge/desktop/static/index.html +89 -0
  56. traceforge/desktop/static/md.js +90 -0
  57. traceforge/desktop/static/viewer.js +213 -0
  58. traceforge/desktop/symbols.py +212 -0
  59. traceforge/desktop/update.py +65 -0
  60. traceforge/diagnostics.py +67 -0
  61. traceforge/errata.py +219 -0
  62. traceforge/fab.py +108 -0
  63. traceforge/fab_layers.py +44 -0
  64. traceforge/features/__init__.py +6 -0
  65. traceforge/features/candidates.py +117 -0
  66. traceforge/features/cli.py +200 -0
  67. traceforge/features/package.py +433 -0
  68. traceforge/features/revdiff.py +224 -0
  69. traceforge/features/sarif.py +145 -0
  70. traceforge/features/viewer.py +265 -0
  71. traceforge/firmware/__init__.py +3 -0
  72. traceforge/firmware/cli.py +174 -0
  73. traceforge/firmware/drivers.py +372 -0
  74. traceforge/firmware/drivers_data.py +256 -0
  75. traceforge/firmware/mcus.py +177 -0
  76. traceforge/firmware/netlist.py +55 -0
  77. traceforge/firmware/pinmap.py +296 -0
  78. traceforge/firmware/scaffold.py +466 -0
  79. traceforge/firmware/toolchain.py +262 -0
  80. traceforge/hooks.py +237 -0
  81. traceforge/kicad/__init__.py +0 -0
  82. traceforge/kicad/cli.py +519 -0
  83. traceforge/kicad/diffpair.py +174 -0
  84. traceforge/kicad/edgegeom.py +191 -0
  85. traceforge/kicad/edit.py +405 -0
  86. traceforge/kicad/escape.py +1410 -0
  87. traceforge/kicad/formats.py +1073 -0
  88. traceforge/kicad/impedance.py +320 -0
  89. traceforge/kicad/install.py +75 -0
  90. traceforge/kicad/libraries.py +490 -0
  91. traceforge/kicad/models3d.py +942 -0
  92. traceforge/kicad/outputs.py +81 -0
  93. traceforge/kicad/pcb.py +787 -0
  94. traceforge/kicad/planes.py +1242 -0
  95. traceforge/kicad/project.py +136 -0
  96. traceforge/kicad/route.py +2698 -0
  97. traceforge/kicad/routegeom.py +164 -0
  98. traceforge/kicad/schematic.py +268 -0
  99. traceforge/kicad/sides.py +34 -0
  100. traceforge/kicad/stackup.py +424 -0
  101. traceforge/kicad_plugin/__init__.py +12 -0
  102. traceforge/kicad_plugin/actions.py +92 -0
  103. traceforge/kicad_plugin/cli.py +66 -0
  104. traceforge/kicad_plugin/client.py +86 -0
  105. traceforge/kicad_plugin/context.py +257 -0
  106. traceforge/kicad_plugin/discovery.py +81 -0
  107. traceforge/kicad_plugin/install.py +203 -0
  108. traceforge/kicad_plugin/overlay.py +60 -0
  109. traceforge/kicad_plugin/payload/action_plugin.py +65 -0
  110. traceforge/kicad_plugin/payload/ipc_main.py +42 -0
  111. traceforge/kicad_plugin/payload/plugin.json +90 -0
  112. traceforge/kicad_plugin/payload/requirements.txt +1 -0
  113. traceforge/kicad_plugin/views.py +202 -0
  114. traceforge/langchain.py +57 -0
  115. traceforge/local.py +580 -0
  116. traceforge/mcp_server.py +304 -0
  117. traceforge/models.py +310 -0
  118. traceforge/next_steps.py +110 -0
  119. traceforge/parts/__init__.py +52 -0
  120. traceforge/parts/alternates.py +488 -0
  121. traceforge/parts/bom.py +423 -0
  122. traceforge/parts/brief.py +705 -0
  123. traceforge/parts/catalog.py +297 -0
  124. traceforge/parts/cli_sourcing.py +156 -0
  125. traceforge/parts/data/duty_rates.yaml +37 -0
  126. traceforge/parts/data/hs_codes.yaml +103 -0
  127. traceforge/parts/datasheet.py +278 -0
  128. traceforge/parts/fx.py +100 -0
  129. traceforge/parts/model.py +185 -0
  130. traceforge/parts/net.py +187 -0
  131. traceforge/parts/offers.py +46 -0
  132. traceforge/parts/packages.py +397 -0
  133. traceforge/parts/pinout.py +714 -0
  134. traceforge/parts/providers/__init__.py +17 -0
  135. traceforge/parts/providers/base.py +100 -0
  136. traceforge/parts/providers/jlc.py +364 -0
  137. traceforge/parts/providers/keyed.py +661 -0
  138. traceforge/parts/report.py +508 -0
  139. traceforge/parts/supply.py +330 -0
  140. traceforge/parts/verify.py +455 -0
  141. traceforge/parts/web.py +575 -0
  142. traceforge/plans.py +70 -0
  143. traceforge/preferences.py +127 -0
  144. traceforge/prices.py +130 -0
  145. traceforge/prices.yaml +28 -0
  146. traceforge/prompts/__init__.py +54 -0
  147. traceforge/prompts/system.md +103 -0
  148. traceforge/providers.py +764 -0
  149. traceforge/remote/__init__.py +33 -0
  150. traceforge/remote/client.py +422 -0
  151. traceforge/remote/oidc.py +240 -0
  152. traceforge/remote/orgs.py +510 -0
  153. traceforge/remote/server.py +690 -0
  154. traceforge/remote/store.py +100 -0
  155. traceforge/review_changes.py +187 -0
  156. traceforge/routing.py +99 -0
  157. traceforge/runtime.py +435 -0
  158. traceforge/sessions.py +324 -0
  159. traceforge/sexpr.py +279 -0
  160. traceforge/sim/__init__.py +17 -0
  161. traceforge/sim/acmath.py +234 -0
  162. traceforge/sim/circuit.py +499 -0
  163. traceforge/sim/cli.py +162 -0
  164. traceforge/sim/engine.py +172 -0
  165. traceforge/sim/ltspice.py +175 -0
  166. traceforge/sim/measure.py +123 -0
  167. traceforge/sim/models.py +76 -0
  168. traceforge/sim/project.py +218 -0
  169. traceforge/sim/rawfile.py +123 -0
  170. traceforge/sim/results.py +298 -0
  171. traceforge/sim/tune.py +172 -0
  172. traceforge/skill_commands.py +165 -0
  173. traceforge/skill_library/circuit-simulation/SKILL.md +30 -0
  174. traceforge/skill_library/compliance-review/SKILL.md +51 -0
  175. traceforge/skill_library/design-review/SKILL.md +47 -0
  176. traceforge/skill_library/errata-hunt/SKILL.md +30 -0
  177. traceforge/skill_library/firmware/SKILL.md +26 -0
  178. traceforge/skill_library/power-budget/SKILL.md +27 -0
  179. traceforge/skill_library/release-package/SKILL.md +29 -0
  180. traceforge/skill_library/sourcing-brief/SKILL.md +24 -0
  181. traceforge/skill_library/thermal-review/SKILL.md +15 -0
  182. traceforge/skills.py +131 -0
  183. traceforge/thermal.py +557 -0
  184. traceforge/tools/__init__.py +48 -0
  185. traceforge/tools/agent_tools.py +213 -0
  186. traceforge/tools/base.py +303 -0
  187. traceforge/tools/batch.py +155 -0
  188. traceforge/tools/connections.py +245 -0
  189. traceforge/tools/files.py +777 -0
  190. traceforge/tools/firmware_tools.py +218 -0
  191. traceforge/tools/kicad_tools.py +1072 -0
  192. traceforge/tools/models3d_tools.py +141 -0
  193. traceforge/tools/parts_tools.py +473 -0
  194. traceforge/tools/processes.py +246 -0
  195. traceforge/tools/review_tools.py +178 -0
  196. traceforge/tools/sim_tools.py +230 -0
  197. traceforge/tui.py +620 -0
  198. traceforge/updates.py +124 -0
  199. traceforge/validate/__init__.py +77 -0
  200. traceforge/validate/builtins.py +1091 -0
  201. traceforge/validate/circuits.py +1240 -0
  202. traceforge/validate/config.py +410 -0
  203. traceforge/validate/default.yaml +113 -0
  204. traceforge/validate/design.py +191 -0
  205. traceforge/validate/explain.py +112 -0
  206. traceforge/validate/grounding.py +169 -0
  207. traceforge/validate/ipc2221.py +350 -0
  208. traceforge/validate/multilayer.py +805 -0
  209. traceforge/validate/netmodel.py +261 -0
  210. traceforge/validate/partcheck.py +472 -0
  211. traceforge/validate/report.py +280 -0
  212. traceforge/validate/review.py +322 -0
  213. traceforge/validate/runner.py +662 -0
  214. traceforge/workspace.py +171 -0
  215. traceforge_pcb-1.0.0.dist-info/METADATA +463 -0
  216. traceforge_pcb-1.0.0.dist-info/RECORD +219 -0
  217. traceforge_pcb-1.0.0.dist-info/WHEEL +4 -0
  218. traceforge_pcb-1.0.0.dist-info/entry_points.txt +2 -0
  219. traceforge_pcb-1.0.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,278 @@
1
+ """Download datasheets and return the parts of them that matter.
2
+
3
+ PDFs are stored in the workspace under ``.traceforge/datasheets/`` with the
4
+ extracted text next to them (``<name>.pages.json``), so a second look costs no
5
+ download. Text extraction uses ``pypdf`` (``pip install 'traceforge-pcb[datasheets]'``)
6
+ and falls back to poppler's ``pdftotext`` when that is installed.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import hashlib
12
+ import io
13
+ import json
14
+ import logging
15
+ import re
16
+ import shutil
17
+ import subprocess
18
+ import tempfile
19
+ from pathlib import Path
20
+ from typing import Any
21
+
22
+ from traceforge.parts.net import Net, ProviderError, default_net
23
+ from traceforge.parts.web import check_url, html_to_text
24
+
25
+ MAX_BYTES = 40 * 1024 * 1024
26
+
27
+
28
+ class ExtractionUnavailable(ProviderError):
29
+ """Neither pypdf nor pdftotext is available."""
30
+
31
+
32
+ def pdf_pages(data: bytes) -> list[str]:
33
+ """Text of every page of a PDF."""
34
+ pypdf_error: Exception | None = None
35
+ try:
36
+ from pypdf import PdfReader
37
+ except ImportError:
38
+ PdfReader = None # noqa: N806
39
+ if PdfReader is not None:
40
+ logging.getLogger("pypdf").setLevel(logging.ERROR) # font warnings are noise here
41
+ try:
42
+ reader = PdfReader(io.BytesIO(data))
43
+ return [_clean(page.extract_text() or "") for page in reader.pages]
44
+ except Exception as exc: # noqa: BLE001 - malformed PDFs raise many kinds
45
+ pypdf_error = exc
46
+ tool = shutil.which("pdftotext")
47
+ if tool:
48
+ with tempfile.TemporaryDirectory() as tmp:
49
+ src = Path(tmp) / "in.pdf"
50
+ src.write_bytes(data)
51
+ result = subprocess.run(
52
+ [tool, "-layout", str(src), "-"], capture_output=True, timeout=120, check=False
53
+ )
54
+ if result.returncode == 0:
55
+ return [_clean(p) for p in result.stdout.decode("utf-8", "replace").split("\f")]
56
+ if pypdf_error is not None:
57
+ raise ProviderError(f"could not read the PDF: {pypdf_error}")
58
+ raise ExtractionUnavailable(
59
+ "PDF text extraction needs pypdf (pip install 'traceforge-pcb[datasheets]') or pdftotext"
60
+ )
61
+
62
+
63
+ def pdf_outline(data: bytes) -> list[dict[str, Any]]:
64
+ try:
65
+ from pypdf import PdfReader
66
+
67
+ reader = PdfReader(io.BytesIO(data))
68
+ out: list[dict[str, Any]] = []
69
+
70
+ def walk(items, depth=0):
71
+ for item in items:
72
+ if isinstance(item, list):
73
+ walk(item, depth + 1)
74
+ continue
75
+ try:
76
+ page = reader.get_destination_page_number(item) + 1
77
+ except Exception: # noqa: BLE001
78
+ page = None
79
+ out.append({"title": str(item.title).strip(), "page": page, "level": depth})
80
+ if len(out) >= 300:
81
+ return
82
+
83
+ walk(reader.outline)
84
+ return out
85
+ except Exception: # noqa: BLE001 - outline is optional
86
+ return []
87
+
88
+
89
+ def _clean(text: str) -> str:
90
+ text = text.replace("\x00", "")
91
+ text = re.sub(r"[ \t]+", " ", text)
92
+ return re.sub(r"\n{3,}", "\n\n", text).strip()
93
+
94
+
95
+ def _safe_name(text: str) -> str:
96
+ return re.sub(r"[^A-Za-z0-9._-]+", "_", text).strip("_")[:80] or "datasheet"
97
+
98
+
99
+ def parse_pages(spec: str | None, count: int) -> list[int]:
100
+ """'1-3,7' -> [1, 2, 3, 7] (1-based, clipped to the document)."""
101
+ pages: list[int] = []
102
+ for chunk in (spec or "").split(","):
103
+ chunk = chunk.strip()
104
+ if not chunk:
105
+ continue
106
+ if "-" in chunk:
107
+ a, b = chunk.split("-", 1)
108
+ start, end = int(a or 1), int(b or count)
109
+ pages.extend(range(start, end + 1))
110
+ else:
111
+ pages.append(int(chunk))
112
+ return [p for p in dict.fromkeys(pages) if 1 <= p <= count][:60]
113
+
114
+
115
+ def fetch_datasheet(
116
+ folder: Path,
117
+ *,
118
+ url: str | None = None,
119
+ name: str | None = None,
120
+ local: Path | None = None,
121
+ net: Net | None = None,
122
+ _follow: bool = True,
123
+ ) -> tuple[Path, list[str], list[dict[str, Any]]]:
124
+ """Download (or reuse) a datasheet; returns (pdf path, page texts, outline)."""
125
+ folder.mkdir(parents=True, exist_ok=True)
126
+ if local is not None:
127
+ data = local.read_bytes()
128
+ target = local
129
+ else:
130
+ if not url:
131
+ raise ProviderError("no datasheet URL")
132
+ url = check_url(url)
133
+ stem = _safe_name(name or Path(url.split("?")[0]).stem)
134
+ digest = hashlib.sha1(url.encode()).hexdigest()[:8]
135
+ target = folder / f"{stem}-{digest}.pdf"
136
+ cached = target.with_suffix(".pages.json")
137
+ if target.exists() and cached.exists():
138
+ meta = json.loads(cached.read_text(encoding="utf-8"))
139
+ return target, meta["pages"], meta.get("outline", [])
140
+ net = net or default_net()
141
+ response = net.request("GET", url)
142
+ if response.status_code >= 400:
143
+ raise ProviderError(f"HTTP {response.status_code} downloading {url}")
144
+ data = response.content
145
+ if len(data) > MAX_BYTES:
146
+ raise ProviderError(f"datasheet is larger than {MAX_BYTES // 2**20} MB")
147
+ if data[:5] != b"%PDF-":
148
+ kind = response.headers.get("content-type", "")
149
+ if "html" in kind or b"<html" in data[:1000].lower():
150
+ title, text, links = html_to_text(response.text)
151
+ pdf_links = [h for _, h in links if ".pdf" in h.lower()][:5]
152
+ follow = _pdf_link(response.text, url)
153
+ if follow and _follow:
154
+ try:
155
+ return fetch_datasheet(
156
+ folder, url=follow, name=name, net=net, _follow=False
157
+ )
158
+ except ProviderError:
159
+ pass
160
+ target = target.with_suffix(".html")
161
+ target.write_bytes(data)
162
+ pages = [text[i : i + 6000] for i in range(0, min(len(text), 120_000), 6000)]
163
+ note = [
164
+ {"title": f"HTML page: {title}; PDF links: {pdf_links}", "page": 1, "level": 0}
165
+ ]
166
+ return target, pages or [""], note
167
+ raise ProviderError(f"{url} is not a PDF ({kind or 'unknown type'})")
168
+ target.write_bytes(data)
169
+ pages = pdf_pages(data)
170
+ outline = pdf_outline(data)
171
+ meta_path = target.with_suffix(".pages.json")
172
+ try:
173
+ meta_path.write_text(
174
+ json.dumps({"source": url or str(local), "pages": pages, "outline": outline}),
175
+ encoding="utf-8",
176
+ )
177
+ except OSError:
178
+ pass
179
+ return target, pages, outline
180
+
181
+
182
+ def _pdf_link(html: str, url: str) -> str:
183
+ """The PDF a datasheet viewer page (LCSC's, for one) points at."""
184
+ for match in re.finditer(r"https?://[^\"'\s<>]+?\.pdf(?:\?[^\"'\s<>]*)?", html):
185
+ link = match.group(0).replace("&amp;", "&")
186
+ if link != url and "viewer.html" not in link:
187
+ return link
188
+ return ""
189
+
190
+
191
+ def layout_pages(path: Path) -> list[str]:
192
+ """Page texts with the layout kept (columns of pin diagrams stay on one line).
193
+
194
+ Uses poppler's ``pdftotext -layout``, else pypdf's layout mode; cached next to
195
+ the PDF as ``<name>.layout.json``. Empty when neither works.
196
+ """
197
+ cached = path.with_suffix(".layout.json")
198
+ if cached.exists():
199
+ try:
200
+ return json.loads(cached.read_text(encoding="utf-8"))["pages"]
201
+ except (OSError, ValueError, KeyError):
202
+ pass
203
+ pages: list[str] = []
204
+ tool = shutil.which("pdftotext")
205
+ if tool:
206
+ result = subprocess.run(
207
+ [tool, "-layout", str(path), "-"], capture_output=True, timeout=120, check=False
208
+ )
209
+ if result.returncode == 0:
210
+ pages = result.stdout.decode("utf-8", "replace").split("\f")
211
+ if not pages:
212
+ try:
213
+ from pypdf import PdfReader
214
+
215
+ logging.getLogger("pypdf").setLevel(logging.ERROR)
216
+ reader = PdfReader(str(path))
217
+ pages = [p.extract_text(extraction_mode="layout") or "" for p in reader.pages]
218
+ except Exception: # noqa: BLE001 - optional dependency or malformed PDF
219
+ return []
220
+ pages = ["\n".join(line.rstrip() for line in p.replace("\x00", "").splitlines()) for p in pages]
221
+ try:
222
+ cached.write_text(json.dumps({"pages": pages}), encoding="utf-8")
223
+ except OSError:
224
+ pass
225
+ return pages
226
+
227
+
228
+ def select(
229
+ pages: list[str],
230
+ outline: list[dict[str, Any]],
231
+ *,
232
+ page_spec: str | None = None,
233
+ query: str | None = None,
234
+ max_chars: int = 24_000,
235
+ ) -> dict[str, Any]:
236
+ """Pick the useful text: requested pages, pages matching a query, or an overview."""
237
+ count = len(pages)
238
+ chosen: list[int]
239
+ hits: dict[int, int] = {}
240
+ if page_spec:
241
+ chosen = parse_pages(page_spec, count)
242
+ elif query:
243
+ words = [w.lower() for w in re.findall(r"[\w.+-]{2,}", query)]
244
+ phrase = query.lower().strip()
245
+ for index, text in enumerate(pages, start=1):
246
+ lowered = text.lower()
247
+ score = sum(lowered.count(w) for w in words) + 5 * lowered.count(phrase)
248
+ if words and all(w in lowered for w in words):
249
+ score += 10
250
+ if score:
251
+ hits[index] = score
252
+ for item in outline: # a section title that matches is a strong hint
253
+ if item.get("page") and any(w in item["title"].lower() for w in words):
254
+ hits[item["page"]] = hits.get(item["page"], 0) + 15
255
+ chosen = sorted(hits, key=lambda p: -hits[p])[:8]
256
+ chosen.sort()
257
+ else:
258
+ chosen = list(range(1, min(count, 2) + 1))
259
+ out_pages = []
260
+ used = 0
261
+ for number in chosen:
262
+ text = pages[number - 1]
263
+ if used + len(text) > max_chars:
264
+ text = text[: max(0, max_chars - used)] + " …[truncated]"
265
+ out_pages.append({"page": number, "text": text})
266
+ used += len(text)
267
+ if used >= max_chars:
268
+ break
269
+ result: dict[str, Any] = {"page_count": count, "pages": out_pages}
270
+ if not page_spec and not query and outline:
271
+ result["outline"] = [
272
+ f"{' ' * o['level']}{o['title']} (p{o['page']})" for o in outline[:120]
273
+ ]
274
+ if query and not chosen:
275
+ result["note"] = f"no page mentions {query!r}; try other words or read the outline"
276
+ if query and hits:
277
+ result["matching_pages"] = sorted(hits, key=lambda p: -hits[p])[:20]
278
+ return result
traceforge/parts/fx.py ADDED
@@ -0,0 +1,100 @@
1
+ """Currency conversion with an explicit, dated source for every rate.
2
+
3
+ Order of preference: (1) live rates from the free ECB-based frankfurter.app API,
4
+ cached on disk; (2) the last cached live table, however old (marked stale);
5
+ (3) the built-in reference table below. The table used is always named in the
6
+ result, so a converted figure never hides which rates produced it. A currency
7
+ no source knows raises :class:`FxError`; nothing is guessed.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import time
13
+ from dataclasses import dataclass
14
+
15
+ from traceforge.parts.net import Cache, Net, Offline, ProviderError, default_net
16
+
17
+ API = "https://api.frankfurter.app/latest"
18
+ LIVE_TTL = 24 * 3600.0
19
+
20
+ # Built-in reference rates: units of currency per 1 USD. APPROXIMATE, hand-entered, not live.
21
+ # They exist so an offline run can still compare suppliers; the output labels them as such.
22
+ # Edit BUILTIN_DATE and the numbers together when refreshing them.
23
+ BUILTIN_DATE = "2026-01-15"
24
+ BUILTIN_PER_USD: dict[str, float] = {
25
+ "USD": 1.0,
26
+ "EUR": 0.92,
27
+ "GBP": 0.79,
28
+ "JPY": 150.0,
29
+ "CNY": 7.2,
30
+ "INR": 85.0,
31
+ "CAD": 1.38,
32
+ "AUD": 1.55,
33
+ "CHF": 0.89,
34
+ "SEK": 10.6,
35
+ "NOK": 10.8,
36
+ "DKK": 6.9,
37
+ "PLN": 4.1,
38
+ "CZK": 23.5,
39
+ "HKD": 7.8,
40
+ "SGD": 1.35,
41
+ "KRW": 1400.0,
42
+ "MXN": 18.5,
43
+ "BRL": 5.6,
44
+ "ILS": 3.7,
45
+ "TWD": 32.0,
46
+ }
47
+
48
+
49
+ class FxError(Exception):
50
+ """No rate is known for a currency."""
51
+
52
+
53
+ @dataclass
54
+ class FxTable:
55
+ per_usd: dict[str, float]
56
+ source: str # frankfurter | cached frankfurter | builtin
57
+ date: str
58
+
59
+ def convert(self, amount: float, src: str, dst: str) -> float:
60
+ src, dst = src.upper(), dst.upper()
61
+ if src == dst:
62
+ return amount
63
+ if src not in self.per_usd or dst not in self.per_usd:
64
+ missing = src if src not in self.per_usd else dst
65
+ raise FxError(f"no exchange rate for {missing} ({self.source} table, {self.date})")
66
+ return amount / self.per_usd[src] * self.per_usd[dst]
67
+
68
+ def describe(self) -> str:
69
+ note = " (approximate built-in reference, not live)" if self.source == "builtin" else ""
70
+ return f"{self.source} rates dated {self.date}{note}"
71
+
72
+
73
+ def builtin() -> FxTable:
74
+ return FxTable(dict(BUILTIN_PER_USD), "builtin", BUILTIN_DATE)
75
+
76
+
77
+ def load_rates(
78
+ *, net: Net | None = None, cache: Cache | None = None, refresh: bool = False
79
+ ) -> FxTable:
80
+ """Live rates when reachable, else the last cached live rates, else the built-in table."""
81
+ cache = cache or Cache(ttl=LIVE_TTL)
82
+ key = "usd"
83
+ if not refresh:
84
+ hit = cache.get("fx", key)
85
+ if hit is not None:
86
+ return FxTable(hit[0]["per_usd"], "cached frankfurter", hit[0]["date"])
87
+ try:
88
+ data = (net or default_net()).json("GET", API, params={"from": "USD"})
89
+ rates = {k.upper(): float(v) for k, v in (data or {}).get("rates", {}).items()}
90
+ if not rates:
91
+ raise ProviderError("frankfurter: no rates in response")
92
+ rates["USD"] = 1.0
93
+ date = str(data.get("date") or time.strftime("%Y-%m-%d"))
94
+ cache.put("fx", key, {"per_usd": rates, "date": date})
95
+ return FxTable(rates, "frankfurter", date)
96
+ except (Offline, ProviderError, ValueError, TypeError, AttributeError):
97
+ stale = cache.get("fx", key, allow_stale=True)
98
+ if stale is not None:
99
+ return FxTable(stale[0]["per_usd"], "cached frankfurter (stale)", stale[0]["date"])
100
+ return builtin()
@@ -0,0 +1,185 @@
1
+ """Provider-neutral part record."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import re
6
+ from dataclasses import asdict, dataclass, field
7
+ from typing import Any
8
+
9
+ LCSC_RE = re.compile(r"^C\d{1,10}$", re.IGNORECASE)
10
+
11
+
12
+ def is_lcsc_code(text: str | None) -> bool:
13
+ return bool(text and LCSC_RE.match(text.strip()))
14
+
15
+
16
+ def normalize_lcsc(text: str) -> str:
17
+ return text.strip().upper()
18
+
19
+
20
+ @dataclass
21
+ class PriceBreak:
22
+ quantity: int
23
+ unit_price: float
24
+ currency: str = "USD"
25
+
26
+
27
+ @dataclass
28
+ class SupplierOffer:
29
+ """One supplier's offer for a part: what it costs, how much it has, how it ships.
30
+
31
+ ``moq`` is the minimum order quantity, ``multiple`` the order multiple,
32
+ ``lead_time_days`` the factory/restock lead time when the supplier states one.
33
+ ``source`` is the provider that produced the figures (jlcpcb, digikey, ...);
34
+ ``authorised`` is True/False only when the API says so, None when unknown.
35
+ """
36
+
37
+ supplier: str
38
+ sku: str = ""
39
+ stock: int | None = None
40
+ price_breaks: list[PriceBreak] = field(default_factory=list)
41
+ moq: int | None = None
42
+ multiple: int | None = None
43
+ lead_time_days: int | None = None
44
+ packaging: str = ""
45
+ lifecycle: str = ""
46
+ region: str = "" # where it ships from or serves, as the API states it
47
+ authorised: bool | None = None
48
+ url: str = ""
49
+ source: str = ""
50
+ notes: list[str] = field(default_factory=list)
51
+
52
+ @property
53
+ def currency(self) -> str:
54
+ return self.price_breaks[0].currency if self.price_breaks else ""
55
+
56
+ @classmethod
57
+ def from_dict(cls, data: dict[str, Any]) -> SupplierOffer:
58
+ data = dict(data)
59
+ data.pop("currency", None)
60
+ breaks = [PriceBreak(**b) for b in data.pop("price_breaks", []) or []]
61
+ known = {f for f in cls.__dataclass_fields__}
62
+ return cls(price_breaks=breaks, **{k: v for k, v in data.items() if k in known})
63
+
64
+
65
+ def normalize_lifecycle(text: str | None) -> str:
66
+ """Map distributor lifecycle wording onto normal | nrnd | last_time_buy | obsolete | discontinued."""
67
+ t = (text or "").strip().lower()
68
+ if not t:
69
+ return ""
70
+ if re.search(r"not for new|nrnd|not recommended", t):
71
+ return "nrnd"
72
+ if re.search(r"last time|\bltb\b", t):
73
+ return "last_time_buy"
74
+ if re.search(r"obsolete|end of life|\beol\b", t):
75
+ return "obsolete"
76
+ if "discontinu" in t:
77
+ return "discontinued"
78
+ if re.search(r"active|new product|new at|in production|production|normal", t):
79
+ return "normal"
80
+ return t
81
+
82
+
83
+ @dataclass
84
+ class PartInfo:
85
+ """What a catalogue knows about one orderable part.
86
+
87
+ ``library_type`` is JLCPCB's assembly library class: ``basic`` (no setup
88
+ fee), ``preferred`` (extended part without the fee) or ``extended``.
89
+ ``stock`` is the quantity the assembler can use (JLCPCB's stock when it is
90
+ known, otherwise the distributor's); ``stock_by_source`` keeps each figure.
91
+ """
92
+
93
+ lcsc: str = ""
94
+ mpn: str = ""
95
+ manufacturer: str = ""
96
+ description: str = ""
97
+ package: str = ""
98
+ category: str = ""
99
+ pin_count: int | None = None
100
+ stock: int | None = None
101
+ stock_by_source: dict[str, int] = field(default_factory=dict)
102
+ price_breaks: list[PriceBreak] = field(default_factory=list)
103
+ library_type: str = "" # basic | preferred | extended | "" (unknown)
104
+ datasheet_url: str = ""
105
+ product_url: str = ""
106
+ lifecycle: str = "" # normal | sold_out | discontinued | nrnd | ...
107
+ mounting: str = "" # smd | tht | ""
108
+ attributes: dict[str, str] = field(default_factory=dict)
109
+ alternatives: list[str] = field(default_factory=list) # LCSC codes of drop-in alternates
110
+ sources: list[str] = field(default_factory=list)
111
+ offers: list[SupplierOffer] = field(default_factory=list) # per-supplier detail
112
+ stale: bool = False # served from an expired cache entry because the network failed
113
+
114
+ @property
115
+ def in_stock(self) -> bool | None:
116
+ return None if self.stock is None else self.stock > 0
117
+
118
+ @property
119
+ def is_basic(self) -> bool:
120
+ return self.library_type == "basic"
121
+
122
+ def to_dict(self, *, brief: bool = False) -> dict[str, Any]:
123
+ data = asdict(self)
124
+ data["in_stock"] = self.in_stock
125
+ if brief:
126
+ for key in ("price_breaks", "stock_by_source", "alternatives", "attributes", "offers"):
127
+ data.pop(key, None)
128
+ if self.price_breaks:
129
+ data["unit_price"] = self.price_breaks[0].unit_price
130
+ data["attributes"] = dict(list(self.attributes.items())[:8])
131
+ return {k: v for k, v in data.items() if v not in ("", None, [], {}) or k == "stock"}
132
+
133
+ @classmethod
134
+ def from_dict(cls, data: dict[str, Any]) -> PartInfo:
135
+ data = dict(data)
136
+ data.pop("in_stock", None)
137
+ data.pop("unit_price", None)
138
+ breaks = [PriceBreak(**b) for b in data.pop("price_breaks", []) or []]
139
+ offers = [SupplierOffer.from_dict(o) for o in data.pop("offers", []) or []]
140
+ known = {f for f in cls.__dataclass_fields__}
141
+ return cls(
142
+ price_breaks=breaks, offers=offers, **{k: v for k, v in data.items() if k in known}
143
+ )
144
+
145
+ def merge(self, other: PartInfo) -> PartInfo:
146
+ """Fill empty fields from another source's record for the same part."""
147
+ for name in self.__dataclass_fields__:
148
+ mine, theirs = getattr(self, name), getattr(other, name)
149
+ if name == "stock_by_source":
150
+ self.stock_by_source = {**theirs, **mine}
151
+ elif name == "attributes":
152
+ self.attributes = {**theirs, **mine}
153
+ elif name == "sources":
154
+ self.sources = list(dict.fromkeys([*mine, *theirs]))
155
+ elif name == "alternatives":
156
+ self.alternatives = list(dict.fromkeys([*mine, *theirs]))[:10]
157
+ elif name == "offers":
158
+ seen = {(o.supplier, o.sku, o.packaging, o.source) for o in mine}
159
+ self.offers = [
160
+ *mine,
161
+ *[o for o in theirs if (o.supplier, o.sku, o.packaging, o.source) not in seen],
162
+ ]
163
+ elif name == "stale":
164
+ self.stale = mine or theirs
165
+ elif mine in ("", None, [], {}) and theirs not in ("", None, [], {}):
166
+ setattr(self, name, theirs)
167
+ return self
168
+
169
+
170
+ def pin_count_from_text(*texts: str) -> int | None:
171
+ """Pin or position count stated in words ("16P", "10 Position", "2x6P", "8 Pins")."""
172
+ for text in texts:
173
+ if not text:
174
+ continue
175
+ grid = re.search(r"\b(\d{1,2})\s*[xX*]\s*(\d{1,3})\s*P\b", text)
176
+ if grid:
177
+ return int(grid.group(1)) * int(grid.group(2))
178
+ match = re.search(
179
+ r"(?<![\w.=])(\d{1,3})\s*(?:P|Pin|Pins|Position|Positions|Contacts?|Way)\b",
180
+ text,
181
+ flags=re.IGNORECASE,
182
+ )
183
+ if match and 1 <= int(match.group(1)) <= 1000:
184
+ return int(match.group(1))
185
+ return None