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.
- traceforge/__init__.py +3 -0
- traceforge/__main__.py +3 -0
- traceforge/acp_server.py +570 -0
- traceforge/agent.py +680 -0
- traceforge/altium/__init__.py +6 -0
- traceforge/altium/cfb.py +70 -0
- traceforge/altium/cli.py +60 -0
- traceforge/altium/model.py +163 -0
- traceforge/altium/outputs.py +24 -0
- traceforge/altium/pcb.py +301 -0
- traceforge/altium/project.py +328 -0
- traceforge/altium/schematic.py +400 -0
- traceforge/altium/tools.py +166 -0
- traceforge/approval.py +219 -0
- traceforge/attachments.py +346 -0
- traceforge/background.py +253 -0
- traceforge/bench/__init__.py +5 -0
- traceforge/bench/adapters.py +337 -0
- traceforge/bench/checks.py +410 -0
- traceforge/bench/cli.py +121 -0
- traceforge/bench/design.py +439 -0
- traceforge/bench/kicad.py +99 -0
- traceforge/bench/partscheck.py +159 -0
- traceforge/bench/review.py +100 -0
- traceforge/bench/runner.py +226 -0
- traceforge/bench/score.py +204 -0
- traceforge/bench/tasks.py +102 -0
- traceforge/chat.py +1185 -0
- traceforge/checks.py +328 -0
- traceforge/checks_sides.py +118 -0
- traceforge/cli.py +2224 -0
- traceforge/clipboard.py +107 -0
- traceforge/config.py +299 -0
- traceforge/context.py +276 -0
- traceforge/design/__init__.py +1 -0
- traceforge/design/constraints.py +397 -0
- traceforge/design/generate.py +1789 -0
- traceforge/design/outline.py +905 -0
- traceforge/design/schematic_layout.py +932 -0
- traceforge/design/schematic_lint.py +329 -0
- traceforge/design/schematic_route.py +207 -0
- traceforge/design/sheets.py +854 -0
- traceforge/design/sides.py +328 -0
- traceforge/design/spec.py +462 -0
- traceforge/design/specsheet.py +2351 -0
- traceforge/design/specsheet_render.py +183 -0
- traceforge/desktop/__init__.py +109 -0
- traceforge/desktop/keys.py +90 -0
- traceforge/desktop/project.py +443 -0
- traceforge/desktop/review.py +20 -0
- traceforge/desktop/server.py +1277 -0
- traceforge/desktop/static/app.css +223 -0
- traceforge/desktop/static/app.js +683 -0
- traceforge/desktop/static/highlight.js +77 -0
- traceforge/desktop/static/index.html +89 -0
- traceforge/desktop/static/md.js +90 -0
- traceforge/desktop/static/viewer.js +213 -0
- traceforge/desktop/symbols.py +212 -0
- traceforge/desktop/update.py +65 -0
- traceforge/diagnostics.py +67 -0
- traceforge/errata.py +219 -0
- traceforge/fab.py +108 -0
- traceforge/fab_layers.py +44 -0
- traceforge/features/__init__.py +6 -0
- traceforge/features/candidates.py +117 -0
- traceforge/features/cli.py +200 -0
- traceforge/features/package.py +433 -0
- traceforge/features/revdiff.py +224 -0
- traceforge/features/sarif.py +145 -0
- traceforge/features/viewer.py +265 -0
- traceforge/firmware/__init__.py +3 -0
- traceforge/firmware/cli.py +174 -0
- traceforge/firmware/drivers.py +372 -0
- traceforge/firmware/drivers_data.py +256 -0
- traceforge/firmware/mcus.py +177 -0
- traceforge/firmware/netlist.py +55 -0
- traceforge/firmware/pinmap.py +296 -0
- traceforge/firmware/scaffold.py +466 -0
- traceforge/firmware/toolchain.py +262 -0
- traceforge/hooks.py +237 -0
- traceforge/kicad/__init__.py +0 -0
- traceforge/kicad/cli.py +519 -0
- traceforge/kicad/diffpair.py +174 -0
- traceforge/kicad/edgegeom.py +191 -0
- traceforge/kicad/edit.py +405 -0
- traceforge/kicad/escape.py +1410 -0
- traceforge/kicad/formats.py +1073 -0
- traceforge/kicad/impedance.py +320 -0
- traceforge/kicad/install.py +75 -0
- traceforge/kicad/libraries.py +490 -0
- traceforge/kicad/models3d.py +942 -0
- traceforge/kicad/outputs.py +81 -0
- traceforge/kicad/pcb.py +787 -0
- traceforge/kicad/planes.py +1242 -0
- traceforge/kicad/project.py +136 -0
- traceforge/kicad/route.py +2698 -0
- traceforge/kicad/routegeom.py +164 -0
- traceforge/kicad/schematic.py +268 -0
- traceforge/kicad/sides.py +34 -0
- traceforge/kicad/stackup.py +424 -0
- traceforge/kicad_plugin/__init__.py +12 -0
- traceforge/kicad_plugin/actions.py +92 -0
- traceforge/kicad_plugin/cli.py +66 -0
- traceforge/kicad_plugin/client.py +86 -0
- traceforge/kicad_plugin/context.py +257 -0
- traceforge/kicad_plugin/discovery.py +81 -0
- traceforge/kicad_plugin/install.py +203 -0
- traceforge/kicad_plugin/overlay.py +60 -0
- traceforge/kicad_plugin/payload/action_plugin.py +65 -0
- traceforge/kicad_plugin/payload/ipc_main.py +42 -0
- traceforge/kicad_plugin/payload/plugin.json +90 -0
- traceforge/kicad_plugin/payload/requirements.txt +1 -0
- traceforge/kicad_plugin/views.py +202 -0
- traceforge/langchain.py +57 -0
- traceforge/local.py +580 -0
- traceforge/mcp_server.py +304 -0
- traceforge/models.py +310 -0
- traceforge/next_steps.py +110 -0
- traceforge/parts/__init__.py +52 -0
- traceforge/parts/alternates.py +488 -0
- traceforge/parts/bom.py +423 -0
- traceforge/parts/brief.py +705 -0
- traceforge/parts/catalog.py +297 -0
- traceforge/parts/cli_sourcing.py +156 -0
- traceforge/parts/data/duty_rates.yaml +37 -0
- traceforge/parts/data/hs_codes.yaml +103 -0
- traceforge/parts/datasheet.py +278 -0
- traceforge/parts/fx.py +100 -0
- traceforge/parts/model.py +185 -0
- traceforge/parts/net.py +187 -0
- traceforge/parts/offers.py +46 -0
- traceforge/parts/packages.py +397 -0
- traceforge/parts/pinout.py +714 -0
- traceforge/parts/providers/__init__.py +17 -0
- traceforge/parts/providers/base.py +100 -0
- traceforge/parts/providers/jlc.py +364 -0
- traceforge/parts/providers/keyed.py +661 -0
- traceforge/parts/report.py +508 -0
- traceforge/parts/supply.py +330 -0
- traceforge/parts/verify.py +455 -0
- traceforge/parts/web.py +575 -0
- traceforge/plans.py +70 -0
- traceforge/preferences.py +127 -0
- traceforge/prices.py +130 -0
- traceforge/prices.yaml +28 -0
- traceforge/prompts/__init__.py +54 -0
- traceforge/prompts/system.md +103 -0
- traceforge/providers.py +764 -0
- traceforge/remote/__init__.py +33 -0
- traceforge/remote/client.py +422 -0
- traceforge/remote/oidc.py +240 -0
- traceforge/remote/orgs.py +510 -0
- traceforge/remote/server.py +690 -0
- traceforge/remote/store.py +100 -0
- traceforge/review_changes.py +187 -0
- traceforge/routing.py +99 -0
- traceforge/runtime.py +435 -0
- traceforge/sessions.py +324 -0
- traceforge/sexpr.py +279 -0
- traceforge/sim/__init__.py +17 -0
- traceforge/sim/acmath.py +234 -0
- traceforge/sim/circuit.py +499 -0
- traceforge/sim/cli.py +162 -0
- traceforge/sim/engine.py +172 -0
- traceforge/sim/ltspice.py +175 -0
- traceforge/sim/measure.py +123 -0
- traceforge/sim/models.py +76 -0
- traceforge/sim/project.py +218 -0
- traceforge/sim/rawfile.py +123 -0
- traceforge/sim/results.py +298 -0
- traceforge/sim/tune.py +172 -0
- traceforge/skill_commands.py +165 -0
- traceforge/skill_library/circuit-simulation/SKILL.md +30 -0
- traceforge/skill_library/compliance-review/SKILL.md +51 -0
- traceforge/skill_library/design-review/SKILL.md +47 -0
- traceforge/skill_library/errata-hunt/SKILL.md +30 -0
- traceforge/skill_library/firmware/SKILL.md +26 -0
- traceforge/skill_library/power-budget/SKILL.md +27 -0
- traceforge/skill_library/release-package/SKILL.md +29 -0
- traceforge/skill_library/sourcing-brief/SKILL.md +24 -0
- traceforge/skill_library/thermal-review/SKILL.md +15 -0
- traceforge/skills.py +131 -0
- traceforge/thermal.py +557 -0
- traceforge/tools/__init__.py +48 -0
- traceforge/tools/agent_tools.py +213 -0
- traceforge/tools/base.py +303 -0
- traceforge/tools/batch.py +155 -0
- traceforge/tools/connections.py +245 -0
- traceforge/tools/files.py +777 -0
- traceforge/tools/firmware_tools.py +218 -0
- traceforge/tools/kicad_tools.py +1072 -0
- traceforge/tools/models3d_tools.py +141 -0
- traceforge/tools/parts_tools.py +473 -0
- traceforge/tools/processes.py +246 -0
- traceforge/tools/review_tools.py +178 -0
- traceforge/tools/sim_tools.py +230 -0
- traceforge/tui.py +620 -0
- traceforge/updates.py +124 -0
- traceforge/validate/__init__.py +77 -0
- traceforge/validate/builtins.py +1091 -0
- traceforge/validate/circuits.py +1240 -0
- traceforge/validate/config.py +410 -0
- traceforge/validate/default.yaml +113 -0
- traceforge/validate/design.py +191 -0
- traceforge/validate/explain.py +112 -0
- traceforge/validate/grounding.py +169 -0
- traceforge/validate/ipc2221.py +350 -0
- traceforge/validate/multilayer.py +805 -0
- traceforge/validate/netmodel.py +261 -0
- traceforge/validate/partcheck.py +472 -0
- traceforge/validate/report.py +280 -0
- traceforge/validate/review.py +322 -0
- traceforge/validate/runner.py +662 -0
- traceforge/workspace.py +171 -0
- traceforge_pcb-1.0.0.dist-info/METADATA +463 -0
- traceforge_pcb-1.0.0.dist-info/RECORD +219 -0
- traceforge_pcb-1.0.0.dist-info/WHEEL +4 -0
- traceforge_pcb-1.0.0.dist-info/entry_points.txt +2 -0
- 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("&", "&")
|
|
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
|