"""
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)