traceforge-pcb 1.0.0__py3-none-any.whl

traceforge/parts/providers/__init__.py

@@ -0,0 +1,17 @@
+"""Part data providers. See :mod:`traceforge.parts.catalog` for how they are combined."""
+
+from traceforge.parts.providers.base import NotSupported, PartProvider, SearchQuery
+from traceforge.parts.providers.jlc import JlcpcbProvider, JlcsearchProvider, LcscProvider
+from traceforge.parts.providers.keyed import DigikeyProvider, MouserProvider, NexarProvider
+
+__all__ = [
+    "DigikeyProvider",
+    "JlcpcbProvider",
+    "JlcsearchProvider",
+    "LcscProvider",
+    "MouserProvider",
+    "NexarProvider",
+    "NotSupported",
+    "PartProvider",
+    "SearchQuery",
+]

traceforge/parts/providers/base.py

@@ -0,0 +1,100 @@
+"""Provider interface for part catalogues."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from traceforge.parts.model import PartInfo
+from traceforge.parts.net import Net
+
+
+@dataclass
+class SearchQuery:
+    text: str
+    package: str | None = None
+    basic_only: bool = False
+    in_stock: bool = True
+    limit: int = 10
+
+
+class NotSupported(Exception):
+    """This provider cannot answer this kind of request."""
+
+
+class PartProvider:
+    """A source of part data. Subclasses override what they support.
+
+    ``lookup_code`` answers for a distributor code (LCSC "C2286");
+    ``lookup_mpn`` for a manufacturer part number; ``search`` for free text or
+    parametric queries. Each returns None / [] when the provider answered and
+    has nothing, raises :class:`traceforge.parts.net.Offline` when it could not
+    be reached, and :class:`NotSupported` when it does not do that.
+    """
+
+    name = "provider"
+    # Environment variables that must be set for this provider to run.
+    env_keys: tuple[str, ...] = ()
+    codes = False  # can look up LCSC codes
+    mpns = False  # can look up manufacturer part numbers
+    searches = False
+
+    def __init__(self, net: Net):
+        self.net = net
+
+    def configured(self) -> bool:
+        return True
+
+    def lookup_code(self, code: str) -> PartInfo | None:
+        raise NotSupported(self.name)
+
+    def lookup_mpn(self, mpn: str) -> PartInfo | None:
+        if not self.searches:
+            raise NotSupported(self.name)
+        return best_mpn_match(mpn, self.search(SearchQuery(mpn, in_stock=False, limit=20)))
+
+    def search(self, query: SearchQuery) -> list[PartInfo]:
+        raise NotSupported(self.name)
+
+
+def norm_mpn(text: str) -> str:
+    return re.sub(r"[^A-Z0-9]", "", (text or "").upper())
+
+
+# Packaging suffixes that do not change the device (tape and reel, tray, lead-free).
+_PACKAGING_SUFFIX = re.compile(r"(TR|T|R|RL|REEL|CT|ND|PBF|G4|E3|LF)$")
+
+
+def same_device(a: str, b: str) -> bool:
+    """MPNs equal apart from punctuation, case and a packaging suffix."""
+    na, nb = norm_mpn(a), norm_mpn(b)
+    if not na or not nb:
+        return False
+    if na == nb:
+        return True
+    longer, shorter = (na, nb) if len(na) > len(nb) else (nb, na)
+    if longer.startswith(shorter):
+        rest = longer[len(shorter) :]
+        return bool(_PACKAGING_SUFFIX.fullmatch(rest))
+    return False
+
+
+def best_mpn_match(mpn: str, results: list[PartInfo]) -> PartInfo | None:
+    exact = [p for p in results if norm_mpn(p.mpn) == norm_mpn(mpn)]
+    close = exact or [p for p in results if same_device(p.mpn, mpn)]
+    if not close:
+        return None
+    # Prefer what can actually be bought or assembled.
+    return sorted(
+        close,
+        key=lambda p: (
+            not (p.stock or 0) > 0,
+            {"basic": 0, "preferred": 1}.get(p.library_type, 2),
+            -(p.stock or 0),
+        ),
+    )[0]
+
+
+def first_number(text: str) -> float | None:
+    match = re.search(r"-?\d+(?:\.\d+)?", (text or "").replace(",", ""))
+    return float(match.group(0)) if match else None

traceforge/parts/providers/jlc.py

@@ -0,0 +1,364 @@
+"""Keyless providers: JLCPCB parts library, LCSC product data, tscircuit's jlcsearch.
+
+These are the public JSON endpoints the respective web sites use. They need no
+account, which is why they are the defaults; none of them is a contractual
+API, so every parser here is defensive about missing fields.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+from urllib.parse import quote
+
+from traceforge.parts.model import PartInfo, PriceBreak, is_lcsc_code, normalize_lcsc
+from traceforge.parts.net import ProviderError
+from traceforge.parts.providers.base import PartProvider, SearchQuery
+
+JLC_DETAIL = "https://cart.jlcpcb.com/shoppingCart/smtGood/getComponentDetail?componentCode={code}"
+JLC_SEARCH = (
+    "https://jlcpcb.com/api/overseas-pcb-order/v1/shoppingCart/smtGood/selectSmtComponentList"
+)
+LCSC_DETAIL = "https://wmsc.lcsc.com/ftps/wm/product/detail?productCode={code}"
+JLCSEARCH = "https://jlcsearch.tscircuit.com"
+
+CHIP_CODES = {"01005", "0201", "0402", "0603", "0805", "1206", "1210", "1812", "2010", "2512"}
+
+
+def _library_type(raw: str | None, preferred: Any = False) -> str:
+    raw = (raw or "").lower()
+    if raw in {"base", "basic"}:
+        return "basic"
+    if preferred in (True, "true", 1):
+        return "preferred"
+    if raw in {"expand", "extended"}:
+        return "extended"
+    return ""
+
+
+def _mounting(process: str | None) -> str:
+    process = (process or "").upper()
+    return {"SMT": "smd", "THT": "tht"}.get(process, "")
+
+
+class JlcpcbProvider(PartProvider):
+    """JLCPCB's assembly parts library: library type, assembly stock, search."""
+
+    name = "jlcpcb"
+    codes = True
+    mpns = True
+    searches = True
+
+    def lookup_code(self, code: str) -> PartInfo | None:
+        code = normalize_lcsc(code)
+        data = self.net.json("GET", JLC_DETAIL.format(code=quote(code)))
+        if not isinstance(data, dict):
+            raise ProviderError("jlcpcb: unexpected response")
+        item = data.get("data")
+        if data.get("code") != 200 or not item:
+            return None  # JLCPCB answers code 400 / data null for unknown parts
+        return self.parse(item)
+
+    def _query(self, keyword: str, query: SearchQuery, package: str | None, size: int):
+        body: dict[str, Any] = {
+            "keyword": keyword,
+            "currentPage": 1,
+            "pageSize": min(size, 100),
+            "searchSource": "search",
+        }
+        if query.basic_only:
+            body["componentLibraryType"] = "base"
+        if query.in_stock:
+            body["stockFlag"] = True
+        if package:
+            body["componentSpecificationList"] = [package]
+        data = self.net.json("POST", JLC_SEARCH, json=body)
+        page = ((data or {}).get("data") or {}).get("componentPageInfo") or {}
+        parts = [self.parse(item) for item in page.get("list") or []]
+        # C99xxxxxxxx entries are customer-consigned placeholders, not orderable parts.
+        return [p for p in parts if p.lcsc and not re.match(r"^C99\d{8,}$", p.lcsc)]
+
+    def search(self, query: SearchQuery) -> list[PartInfo]:
+        words = query.text.split()
+        package = query.package.strip() if query.package else None
+        if package not in CHIP_CODES:
+            package = None
+        chip = [w for w in words if w in CHIP_CODES]
+        if chip and package is None:
+            package = chip[0]
+        if package:
+            words = [w for w in words if w != package]
+        keyword = " ".join(words) or query.text
+        size = max(query.limit * 3, 25) if query.package else max(query.limit, 10)
+        parts = self._query(keyword, query, package, size)
+        if not parts and len(words) > 1:
+            # The index matches names and specs, not prose: drop one word at a time and
+            # require the dropped word to appear in what comes back.
+            for drop in sorted(words, key=lambda w: (any(c.isdigit() for c in w), len(w)))[:3]:
+                rest = [w for w in words if w != drop]
+                found = self._query(" ".join(rest), query, package, 50)
+                haystack = lambda p: f"{p.mpn} {p.description} {p.category}".lower()  # noqa: E731
+                parts = [p for p in found if drop.lower() in haystack(p)]
+                if parts:
+                    break
+        if not query.basic_only and parts and not any(p.is_basic for p in parts):
+            # Basic parts carry no setup fee at JLCPCB: look for them explicitly.
+            basic = SearchQuery(query.text, query.package, True, query.in_stock, query.limit)
+            try:
+                parts = self._query(keyword, basic, package, size) + parts
+            except Exception:  # noqa: BLE001 - the main result is still good
+                pass
+        return parts
+
+    @staticmethod
+    def parse(item: dict[str, Any]) -> PartInfo:
+        attributes = {}
+        for attr in item.get("attributes") or []:
+            name = attr.get("attribute_name_en")
+            value = attr.get("attribute_value_name")
+            if name and value not in (None, "", "-"):
+                attributes[str(name)] = str(value)
+        prices = item.get("prices") or item.get("componentPrices") or []
+        breaks = [
+            PriceBreak(int(p.get("startNumber") or 1), float(p.get("productPrice")))
+            for p in prices
+            if p.get("productPrice") is not None
+        ]
+        breaks.sort(key=lambda b: b.quantity)
+        stock = item.get("stockCount")
+        code = str(item.get("componentCode") or "")
+        category = item.get("secondTypeNameEn") or item.get("secondSortName") or ""
+        first = item.get("firstTypeNameEn") or item.get("firstSortName") or ""
+        if category and first and category != first:
+            category = f"{first} / {category}"
+        status = str(item.get("componentStatus") or "").lower()
+        return PartInfo(
+            lcsc=code,
+            mpn=str(item.get("componentModelEn") or ""),
+            manufacturer=str(item.get("componentBrandEn") or ""),
+            description=str(item.get("describe") or item.get("componentNameEn") or ""),
+            package=str(item.get("componentSpecificationEn") or ""),
+            category=str(category or item.get("componentTypeEn") or ""),
+            stock=int(stock) if isinstance(stock, int | float) else None,
+            stock_by_source={"jlcpcb": int(stock)} if isinstance(stock, int | float) else {},
+            price_breaks=breaks,
+            library_type=_library_type(
+                item.get("componentLibraryType"), item.get("preferredComponentFlag")
+            ),
+            datasheet_url=str(item.get("dataManualUrl") or ""),
+            product_url=(
+                f"https://jlcpcb.com/partdetail/{item['urlSuffix']}"
+                if item.get("urlSuffix")
+                else (f"https://jlcpcb.com/partdetail/{code}" if code else "")
+            ),
+            lifecycle="discontinued" if status in {"no", "discontinued"} else "",
+            mounting=_mounting(item.get("assemblyProcess")),
+            attributes=attributes,
+            sources=["jlcpcb"],
+        )
+
+
+class LcscProvider(PartProvider):
+    """LCSC product detail: package, lifecycle, distributor stock, datasheet, alternates."""
+
+    name = "lcsc"
+    codes = True
+
+    def lookup_code(self, code: str) -> PartInfo | None:
+        code = normalize_lcsc(code)
+        data = self.net.json("GET", LCSC_DETAIL.format(code=quote(code)))
+        if not isinstance(data, dict):
+            raise ProviderError("lcsc: unexpected response")
+        result = data.get("result")
+        if not result:
+            return None
+        return self.parse(result)
+
+    @staticmethod
+    def parse(result: dict[str, Any]) -> PartInfo:
+        attributes = {}
+        for param in result.get("paramVOList") or []:
+            name, value = param.get("paramNameEn"), param.get("paramValueEn")
+            if name and value not in (None, "", "-"):
+                attributes[str(name)] = str(value)
+        breaks = [
+            PriceBreak(int(p.get("ladder") or 1), float(p.get("usdPrice") or p.get("productPrice")))
+            for p in result.get("productPriceList") or []
+            if (p.get("usdPrice") or p.get("productPrice")) is not None
+        ]
+        stock = result.get("stockNumber")
+        catalog = result.get("catalogName") or ""
+        parent = result.get("parentCatalogName") or ""
+        alternates = [
+            str(a.get("productCode"))
+            for a in (result.get("alternatePartList") or [])
+            if a.get("productCode")
+        ]
+        label = str(result.get("smtLabel") or "").upper()
+        code = str(result.get("productCode") or "")
+        return PartInfo(
+            lcsc=code,
+            mpn=str(result.get("productModel") or ""),
+            manufacturer=str(result.get("brandNameEn") or ""),
+            description=str(result.get("productIntroEn") or result.get("productNameEn") or ""),
+            package=str(result.get("encapStandard") or ""),
+            category=f"{parent} / {catalog}" if parent and catalog else str(catalog),
+            stock=int(stock) if isinstance(stock, int | float) else None,
+            stock_by_source={"lcsc": int(stock)} if isinstance(stock, int | float) else {},
+            price_breaks=breaks,
+            library_type={"BASE": "basic", "EXPAND": "extended"}.get(label, ""),
+            datasheet_url=str(result.get("pdfUrl") or ""),
+            product_url=f"https://www.lcsc.com/product-detail/{code}.html" if code else "",
+            lifecycle=str(result.get("productCycle") or ""),
+            attributes=attributes,
+            alternatives=alternates[:10],
+            sources=["lcsc"],
+        )
+
+
+# ------------------------------------------------------------------ jlcsearch
+
+_PREFIX = {"p": 1e-12, "n": 1e-9, "u": 1e-6, "µ": 1e-6, "m": 1e-3, "k": 1e3, "K": 1e3, "M": 1e6}
+
+
+def parse_value(text: str, unit: str = "") -> float | None:
+    """'10k' -> 10000, '4k7' -> 4700, '100nF' -> 1e-7, '0R1' -> 0.1, '10' -> 10."""
+    text = (text or "").strip().replace("Ω", "").replace("ohm", "").replace(",", ".")
+    if unit:
+        text = re.sub(unit + r"\b", "", text, flags=re.IGNORECASE)
+    match = re.match(r"^(\d+)([pnuµmkKMGR])(\d+)\b", text)  # 4k7, 4R7
+    if match:
+        whole, prefix, frac = match.groups()
+        scale = 1.0 if prefix == "R" else _PREFIX.get(prefix, 1.0)
+        return float(f"{whole}.{frac}") * scale
+    match = re.match(r"^(\d+(?:\.\d+)?)\s*([pnuµmkKMG]?)", text)
+    if match and match.group(1):
+        value = float(match.group(1))
+        return value * _PREFIX.get(match.group(2), 1.0) if match.group(2) else value
+    return None
+
+
+def _parametric(text: str) -> tuple[str, dict[str, str]] | None:
+    """Recognise '10k 0603 1%', '100nF 0402', 'red led 0603' for the category endpoints."""
+    lowered = text.lower()
+    package = next((t for t in re.findall(r"\b\d{4}\b", text) if t in CHIP_CODES), None)
+    params: dict[str, str] = {}
+    if package:
+        params["package"] = package
+    if re.search(r"\bleds?\b", lowered):
+        color = re.search(r"\b(red|green|blue|white|yellow|orange|amber|warm white)\b", lowered)
+        if color:
+            params["color"] = color.group(1)
+        return "leds", params
+    cap = re.search(r"\b(\d+(?:\.\d+)?\s*[pnuµ])f?\b", lowered)
+    if cap and ("cap" in lowered or re.search(r"\d\s*[pnuµ]f\b", lowered) or package):
+        value = parse_value(cap.group(1).replace(" ", ""))
+        if value:
+            params["capacitance"] = f"{value:.4g}"
+            return "capacitors", params
+    res = re.search(r"\b(\d+(?:\.\d+)?[kKmMR]?\d*)\s*(?:ohm|Ω|r\b)?", text)
+    if res and (
+        "res" in lowered or "ohm" in lowered or "Ω" in text or re.search(r"\d[kKM]\b|\dR\d", text)
+    ):
+        value = parse_value(res.group(1))
+        if value is not None:
+            params["resistance"] = f"{value:g}"
+            return "resistors", params
+    return None
+
+
+class JlcsearchProvider(PartProvider):
+    """tscircuit's jlcsearch index of JLCPCB in-stock parts, with parametric category endpoints."""
+
+    name = "jlcsearch"
+    codes = True
+    searches = True
+
+    def lookup_code(self, code: str) -> PartInfo | None:
+        code = normalize_lcsc(code)
+        data = self.net.json("GET", f"{JLCSEARCH}/api/search", params={"q": code, "limit": 5})
+        for item in (data or {}).get("components") or []:
+            if f"C{item.get('lcsc')}" == code:
+                return self.parse(item)
+        return None
+
+    def search(self, query: SearchQuery) -> list[PartInfo]:
+        parametric = _parametric(query.text)
+        if parametric:
+            category, params = parametric
+            if query.package and query.package in CHIP_CODES:
+                params["package"] = query.package
+            params["limit"] = str(max(query.limit * 3, 20))
+            data = self.net.json("GET", f"{JLCSEARCH}/{category}/list.json", params=params)
+            items = (data or {}).get(category) or []
+            parts = [self.parse(i) for i in items]
+            tolerance = re.search(r"(\d+(?:\.\d+)?)\s*%", query.text)
+            if tolerance and category in {"resistors", "capacitors"}:
+                wanted = float(tolerance.group(1)) / 100
+                parts = [
+                    p
+                    for p, i in zip(parts, items)
+                    if i.get("tolerance_fraction") is None
+                    or float(i["tolerance_fraction"]) <= wanted + 1e-9
+                ]
+            return parts
+        params = {"q": query.text, "limit": str(max(query.limit * 3, 20))}
+        if query.package:
+            params["package"] = query.package
+        data = self.net.json("GET", f"{JLCSEARCH}/api/search", params=params)
+        parts = [self.parse(i) for i in (data or {}).get("components") or []]
+        # The free-text index returns loosely related parts; keep those that mention a query word.
+        words = [w.lower() for w in re.findall(r"[A-Za-z0-9.+-]{3,}", query.text)]
+        return [
+            p
+            for p in parts
+            if not words
+            or any(w in (p.mpn + " " + p.description + " " + p.lcsc).lower() for w in words)
+        ]
+
+    @staticmethod
+    def parse(item: dict[str, Any]) -> PartInfo:
+        import json as _json
+
+        attributes: dict[str, str] = {}
+        raw = item.get("attributes")
+        if isinstance(raw, str):
+            try:
+                raw = _json.loads(raw)
+            except ValueError:
+                raw = {}
+        if isinstance(raw, dict):
+            attributes = {str(k): str(v) for k, v in raw.items() if v not in (None, "", "-")}
+        price = item.get("price1", item.get("price"))
+        breaks: list[PriceBreak] = []
+        if isinstance(price, int | float):
+            breaks = [PriceBreak(1, float(price))]
+        elif isinstance(price, str):  # "1-9:4.26,10-29:4.15"
+            for chunk in price.split(","):
+                match = re.match(r"(\d+)-\d*:(\d+(?:\.\d+)?)", chunk.strip())
+                if match:
+                    breaks.append(PriceBreak(int(match.group(1)), float(match.group(2))))
+        stock = item.get("stock")
+        code = f"C{item['lcsc']}" if item.get("lcsc") else ""
+        if item.get("forward_voltage") and "Voltage - Forward(Vf)" not in attributes:
+            attributes["Voltage - Forward(Vf)"] = f"{item['forward_voltage']}V"
+        return PartInfo(
+            lcsc=code,
+            mpn=str(item.get("mfr") or ""),
+            description=str(item.get("description") or ""),
+            package=str(item.get("package") or ""),
+            category=" / ".join(str(item[k]) for k in ("category", "subcategory") if item.get(k)),
+            stock=int(stock) if isinstance(stock, int | float) else None,
+            stock_by_source={"jlcsearch": int(stock)} if isinstance(stock, int | float) else {},
+            price_breaks=breaks,
+            library_type=_library_type(
+                "base" if item.get("is_basic") else "expand", item.get("is_preferred")
+            ),
+            product_url=f"https://jlcpcb.com/partdetail/{code}" if code else "",
+            attributes=attributes,
+            sources=["jlcsearch"],
+        )
+
+
+def looks_like_code(text: str) -> bool:
+    return is_lcsc_code(text)