Source code for jitxlib.jlcpcb.parts.lcsc

"""
The LCSC part source
====================

`LCSCParts` resolves passives against the LCSC catalogue and attaches the
LCSC part number to every component it materializes, so a design resolved
through it exports to JLCPCB without anyone writing a C-number by hand.

    from jitxlib.parts import PartSource
    from jitxlib.jlcpcb.parts import LCSCParts

    PartSource([LCSCParts()])

or by name, since the package registers the provider:

    [tool.jitx.parts]
    chain = ["lcsc"]

This is no longer the chain the package publishes; `JLCPCBParts` is. The two
read the same catalogue, and the reason to name this one is that a query needs a
parameter JLCPCB does not aggregate - a resistor's `rated_voltage_dc` is the one
known case - or that LCSC's roughly threefold lower latency matters more than
knowing which assembly library a part comes from. `JLCPCBParts` is otherwise
strictly more capable.

The wire API
------------

Two endpoints, which is what the LCSC product-list page itself uses:

    POST /ftps/wm/product/query/list          the parametric product list
    POST /ftps/wm/product/query/param/group   the filter vocabulary per catalog

Neither needs authentication. Both answer `{"code": 200, "result": ...}` and
report failure in the body rather than the status line.

LCSC ships two catalog numberings. A product record carries both a `catalogId`
(439 for chip resistors) and a `wmCatalogId` (1199 for the same rows); the
filter endpoints take the second, and asking `param/group` for the first answers
with an empty vocabulary rather than an error. Every id in `CATALOGS` is a
`wmCatalogId`.
"""

from __future__ import annotations

from collections.abc import Mapping, Sequence
from dataclasses import dataclass, field
from typing import Any

from jitxlib.parts.provider import (
    JSON,
    CanonicalQuery,
    NoMatch,
    Scalar,
)

from .catalog import Category, Param, numeric, pint_unit
from .client import JSONClient
from .options import (
    Option,
    OptionTable,
    ParamOptions,
    matching_brands,
    matching_packages,
    names_for,
)
from .source import Catalogues, CatalogSource, Row, keyword, row_value

BASE_URL = "https://wmsc.lcsc.com"

PRODUCT_LIST = "/ftps/wm/product/query/list"
PARAM_GROUP = "/ftps/wm/product/query/param/group"

PRODUCT_URL = "https://www.lcsc.com/product-detail/{code}.html"

# Where the option-list cache goes when none is given. Inside the project, next
# to the rest of the JITX state a checkout carries.
DEFAULT_CACHE_DIR = ".jitx/lcsc"

# `wmCatalogId` per category key. Tantalum before aluminum for polarized
# capacitors: it is the chip-package family, which the landpattern generator
# builds, where an aluminum can takes the catalogue footprint.
CATALOGS: dict[str, tuple[int, ...]] = {
    "resistor": (1199,),  # Chip Resistor - Surface Mount
    "capacitor": (1142,),  # Ceramic Capacitors
    "polarized_capacitor": (1150, 1140),
    "inductor": (1181,),  # Fixed Inductors
}

# Rank keys served by the API's own sort rather than by a local ordering.
SORT_FIELDS: dict[str, str] = {"price": "price", "stock": "stock"}


[docs] @dataclass(frozen=True) class LCSCClient(JSONClient): """Talks to the LCSC list API. >>> client = LCSCClient() >>> body = {"keyword": "C25744", "currentPage": 1, "pageSize": 1} >>> client.product_list(body)["dataList"][0]["productCode"] # doctest: +SKIP 'C25744' """ base_url: str = BASE_URL @property def label(self) -> str: return "lcsc" @property def origin(self) -> dict[str, str]: return {"Origin": "https://www.lcsc.com", "Referer": "https://www.lcsc.com/"}
[docs] def unwrap(self, path: str, payload: Any) -> dict[str, Any]: if not isinstance(payload, dict) or payload.get("code") != 200: message = "no message" if isinstance(payload, dict): message = str(payload.get("msg") or message) raise self.unavailable(f"{path} refused the request: {message}") result = payload.get("result") if not isinstance(result, dict): raise self.unavailable(f"{path} answered without a result object") return result
[docs] def product_list(self, body: dict[str, Any]) -> dict[str, Any]: """Search results for one query body. Returns the `result` object.""" return self.post(PRODUCT_LIST, body)
[docs] def param_group(self, catalog_ids: Sequence[int]) -> dict[str, Any]: """The filter vocabulary for a set of catalogs. Returns `result`.""" return self.post(PARAM_GROUP, {"catalogIdList": list(catalog_ids)})
[docs] @dataclass(frozen=True) class LCSCParts(CatalogSource): """Resolve passives against the LCSC catalogue. >>> from jitxlib.parts import PartSource >>> source = PartSource([LCSCParts()]) Args: base_url: the API host. in_stock: restrict the search to parts LCSC has in stock. page_size: how many rows to ask for per query. cache_dir: where the filter vocabulary is cached, relative to the project. None disables the on-disk copy. timeout: per-request timeout in seconds. """ base_url: str = BASE_URL in_stock: bool = True page_size: int = 25 cache_dir: str | None = field(default=DEFAULT_CACHE_DIR, compare=False) timeout: float = field(default=20.0, compare=False) name: str = "lcsc" _state: dict[str, Any] = field( default_factory=dict, init=False, repr=False, compare=False )
[docs] def config(self) -> dict[str, JSON]: """What identifies this provider, and nothing that does not. The host, the stock policy and the catalog mapping, because each of them changes which part can be selected. The cache directory, the timeout and the page size are out: they change how long an answer takes, never what it is. """ return { "base_url": self.base_url, "in_stock": self.in_stock, "catalogs": {key: list(ids) for key, ids in sorted(CATALOGS.items())}, }
@property def sort_fields(self) -> Mapping[str, str]: return SORT_FIELDS # -- the catalogue ------------------------------------------------------
[docs] def catalogues(self, category: Category) -> Catalogues | None: ids = CATALOGS.get(category.key) if ids is None: return None return Catalogues(key="-".join(str(i) for i in ids), ids=ids)
[docs] def vocabulary(self, catalogues: Catalogues) -> OptionTable: result = self._client().param_group([int(i) for i in catalogues.ids]) return _parse_group(result)
# -- searching ----------------------------------------------------------
[docs] def search( self, query: CanonicalQuery, category: Category, catalogues: Catalogues, table: OptionTable, ) -> Sequence[Mapping[str, Any]] | NoMatch: body = self._body(query, category, catalogues, table) if isinstance(body, NoMatch): return body result = self._client().product_list(body) rows = result.get("dataList") or [] return [row for row in rows if isinstance(row, dict)]
def _body( self, query: CanonicalQuery, category: Category, catalogues: Catalogues, table: OptionTable, ) -> dict[str, Any] | NoMatch: """The `product/query/list` request body for one query. A `NoMatch` instead when a filter names a value LCSC's vocabulary does not hold, which is a plain no-match rather than something to ask about. """ params: dict[str, list[str]] = {} for key, predicate in query.filters.items(): param = category.params.get(key) if param is None: continue names = names_for(table, param, predicate, key) if names is None: return NoMatch(f"LCSC lists no {param.name} for this catalogue") if not names: return NoMatch( f"no LCSC {param.name} value satisfies {query.describe()}" ) spelling = table.spelling(param) or param.name params[spelling] = list(names) body: dict[str, Any] = { "catalogIdList": [int(i) for i in catalogues.ids], "paramNameValueMap": params, "currentPage": 1, "pageSize": min(100, max(self.page_size, query.limit)), } if self.in_stock: body["isStock"] = True case = query.filters.get("case") if case is not None: packages = matching_packages(table, case) if not packages: return NoMatch(f"LCSC lists no package matching {query.describe()}") body["encapValueList"] = packages manufacturer = query.filters.get("manufacturer") if manufacturer is not None: ids = matching_brands(table, manufacturer) if ids: body["brandIdList"] = ids term = keyword(query.filters) if term is not None: body["keyword"] = term if query.rank: primary = query.rank[0] sort = SORT_FIELDS.get(primary.key) if sort is not None: body["sortField"] = sort body["sortType"] = "asc" if primary.direction == "min" else "desc" return body # -- reading a row ------------------------------------------------------
[docs] def read( self, row: Mapping[str, Any], category: Category, table: OptionTable ) -> Row | None: """A row of `dataList`, as a `Row`. None when it has no C-number. """ code = str(row.get("productCode") or "").strip() case = str(row.get("encapStandard") or "").strip() if not code: return None entries = { str(entry.get("paramNameEn")): entry for entry in row.get("paramVOList") or () if isinstance(entry, dict) and entry.get("paramNameEn") } values: dict[str, Scalar] = {} for key, param in category.params.items(): entry = _entry_for(entries, param) if entry is None: continue value = row_value( table, param, str(entry.get("paramValueEn") or ""), entry.get("paramValueEnForSearch"), ) if value is not None: values[key] = value return Row( code=code, case=case, mpn=str(row.get("productModel") or "").strip(), manufacturer=str(row.get("brandNameEn") or "").strip() or None, values=values, stock=numeric(row.get("stockNumber")) or 0.0, price=_unit_price(row), reported={ "datasheet": str(row.get("pdfUrl") or "") or None, "description": str(row.get("productDescEn") or "") or None, "stock": int(numeric(row.get("stockNumber")) or 0), "price": _unit_price(row), "min_order_qty": int(numeric(row.get("minBuyNumber")) or 0), "product_url": PRODUCT_URL.format(code=code), }, )
def _client(self) -> LCSCClient: client = self._state.get("client") if client is None: client = LCSCClient(base_url=self.base_url, timeout=self.timeout) self._state["client"] = client return client
def _entry_for( entries: Mapping[str, Mapping[str, Any]], param: Param ) -> Mapping[str, Any] | None: """The row entry for a parameter, under whichever spelling the row used.""" for name in param.spellings: found = entries.get(name) if found is not None: return found return None def _unit_price(row: Mapping[str, Any]) -> float | None: """The cheapest USD ladder price LCSC quotes for the row.""" prices = [ numeric(entry.get("usdPrice")) for entry in row.get("productPriceList") or () if isinstance(entry, dict) ] found = [p for p in prices if p is not None and p > 0] return min(found) if found else None def _parse_group(result: Mapping[str, Any]) -> OptionTable: """Read a `param/group` response into an OptionTable.""" packages = tuple( str(entry["name"]) for entry in result.get("Package") or () if isinstance(entry, dict) and entry.get("name") ) brands = { str(entry["name"]): str(entry["id"]) for entry in result.get("Manufacturer") or () if isinstance(entry, dict) and entry.get("name") and entry.get("id") } params: dict[str, ParamOptions] = {} for name, group in (result.get("paramNameValueMap") or {}).items(): if not isinstance(group, dict): continue units = group.get("unitList") or () params[str(name)] = ParamOptions( options=tuple( Option( name=str(detail["name"]), start=numeric(detail.get("standardUnitValue")), end=numeric(detail.get("standardUnitEndValue")), ) for detail in group.get("paramDetailList") or () if isinstance(detail, dict) and detail.get("name") ), unit=pint_unit(str(units[0])) if units else None, ) return OptionTable(packages=packages, brands=brands, params=params)