Source code for jitxlib.jlcpcb.parts.jlcpcb

"""
The JLCPCB part source
======================

`JLCPCBParts` resolves passives against JLCPCB's own view of the LCSC
catalogue. This is the chain the package publishes, so a project that configures
nothing resolves through it.

    from jitxlib.parts import PartSource
    from jitxlib.jlcpcb.parts import JLCPCBParts

    PartSource([JLCPCBParts()])

or by name, since the package registers the provider:

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

Why this one rather than LCSC
-----------------------------

The two read the same catalogue - an LCSC `productId` and a JLCPCB
`componentId` are the same row, and the JLCPCB filter vocabulary carries an
`lcscUnitTemplateId` per parameter - but only JLCPCB says which assembly library
a part belongs to, and that is what a board sent to their line is priced on.
See `library` for the attribute that exposes it.

Two things LCSC does better, and both are reasons a project might name the
`lcsc` chain instead:

- JLCPCB does not aggregate a rated-voltage parameter for chip resistors, so a
  resistor query that *filters* on `rated_voltage_dc` is a no-match here and
  resolves on LCSC. The value is still read off the row and shows up as an
  attribute on the resolved part; it just cannot be searched.
- A request takes around 1.7 s against LCSC's 0.5 to 0.9 s, and a
  polarized-capacitor or inductor query costs two requests rather than one,
  because JLCPCB's search takes a single second-level category where LCSC takes
  a list. Resistors and ceramic capacitors, which are most passive queries, stay
  at one request.

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

Two endpoints, unauthenticated, under `https://jlcpcb.com/api/overseas-pcb-order`:

    POST /v1/shoppingCart/smtGood/selectSmtComponentList/v2   the product list
    POST /v1/componentSearch/filterComponentAttribute         the filter vocabulary

Both answer `{"code": 200, "data": ...}` and report failure in the body. Unlike
LCSC there is no WAF: a request with no headers at all is answered.

A catalogue is identified by a (first, second) pair of ids **and** names, all
four of which have to be sent; naming only the ids, or only the names, is
silently ignored and answers the whole catalogue. The names are the ones a row
reports, not the ones in a URL slug - `Inductors, Coils, Chokes`, not
`Inductors_Coils_Chokes`.

The parametric filter is `componentAttributeList`, a list of single-key
`{name: [values]}` maps. The `paramList` field in the same schema is accepted
and ignored, which is worth knowing because getting it wrong returns unfiltered
results rather than an error.
"""

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 . import library
from .catalog import Category, numeric
from .client import JSONClient
from .options import (
    Option,
    OptionTable,
    ParamOptions,
    derive_unit,
    matching_brands,
    matching_packages,
    measured,
    names_for,
)
from .source import Catalogues, CatalogSource, Row, keyword, row_value

BASE_URL = "https://jlcpcb.com/api/overseas-pcb-order"

COMPONENT_LIST = "/v1/shoppingCart/smtGood/selectSmtComponentList/v2"
FILTER_ATTRIBUTE = "/v1/componentSearch/filterComponentAttribute"

PRODUCT_URL = "https://jlcpcb.com/partdetail/{code}"

# Where the option-list cache goes when none is given. Its own directory rather
# than LCSC's: the two vocabularies are keyed by different catalogue numberings
# and spell some parameters differently.
DEFAULT_CACHE_DIR = ".jitx/jlcpcb"


[docs] @dataclass(frozen=True) class Sort: """One second-level JLCPCB catalogue, with the first level it sits under. All four fields go into a request. The ids alone do not filter and neither do the names alone. """ first_id: int first: str second_id: int second: str
RESISTORS = "Resistors" CAPACITORS = "Capacitors" INDUCTORS = "Inductors, Coils, Chokes" # Second-level catalogues per category key. Where a category has more than one, # each is searched and the rows are pooled, which is what LCSC does in a single # request with a catalog list. SORTS: dict[str, tuple[Sort, ...]] = { "resistor": (Sort(1, RESISTORS, 2980, "Chip Resistor - Surface Mount"),), "capacitor": ( Sort(2, CAPACITORS, 2929, "Multilayer Ceramic Capacitors MLCC - SMD/SMT"), ), "polarized_capacitor": ( # Tantalum first: it is the chip-package family, which the landpattern # generator builds, where an aluminum can takes the catalogue footprint. Sort(2, CAPACITORS, 2930, "Tantalum Capacitors"), Sort(2, CAPACITORS, 2965, "Aluminum Electrolytic Capacitors - SMD"), ), "inductor": ( Sort(3, INDUCTORS, 2936, "Inductors (SMD)"), Sort(3, INDUCTORS, 3050, "Power Inductors"), ), } # Rank keys served by the API's own sort rather than by a local ordering. SORT_FIELDS: dict[str, str] = {"price": "PRICE_SORT", "stock": "STOCK_SORT"}
[docs] @dataclass(frozen=True) class JLCPCBClient(JSONClient): """Talks to the JLCPCB parts API. >>> client = JLCPCBClient() >>> body = {"currentPage": 1, "pageSize": 1, "keyword": "C25744"} >>> rows = client.component_list(body)["componentPageInfo"]["list"] >>> rows[0]["componentLibraryType"] # doctest: +SKIP 'base' """ base_url: str = BASE_URL @property def label(self) -> str: return "jlcpcb" @property def origin(self) -> dict[str, str]: return {"Origin": "https://jlcpcb.com", "Referer": "https://jlcpcb.com/parts"}
[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("message") or message) raise self.unavailable(f"{path} refused the request: {message}") data = payload.get("data") if not isinstance(data, dict): raise self.unavailable(f"{path} answered without a data object") return data
[docs] def component_list(self, body: dict[str, Any]) -> dict[str, Any]: """Search results for one query body. Returns the `data` object.""" return self.post(COMPONENT_LIST, body)
[docs] def component_attributes(self, type_ids: Sequence[int]) -> dict[str, Any]: """The filter vocabulary for a set of second-level catalogues.""" return self.post( FILTER_ATTRIBUTE, { "baseQueryDto": { "componentBrandList": [], "componentSpecificationList": [], "componentTypeIdList": list(type_ids), "orderLibraryTypeList": [], "packageTypeList": [], "filterType": 1, "keyword": None, "productTypeIdList": [], "queryShelveStatus": None, }, "catalogLevel": 2, "nowCondition": "", "paramList": [], "queryString": "", }, )
[docs] @dataclass(frozen=True) class JLCPCBParts(CatalogSource): """Resolve passives against JLCPCB's view of the LCSC catalogue. >>> from jitxlib.parts import PartSource >>> source = PartSource([JLCPCBParts()]) Serves the `library` filter, and an ordering on that same key, on top of what either source serves; see the `library` module. Args: base_url: the API host. in_stock: restrict the search to parts JLCPCB has in stock. page_size: how many rows to ask for per query, per catalogue. 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 = "jlcpcb" _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 catalogue 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: [sort.second_id for sort in sorts] for key, sorts in sorted(SORTS.items()) }, }
@property def sort_fields(self) -> Mapping[str, str]: return SORT_FIELDS @property def extra_keys(self) -> frozenset[str]: return frozenset({library.LIBRARY}) # -- the catalogue ------------------------------------------------------
[docs] def catalogues(self, category: Category) -> Catalogues | None: sorts = SORTS.get(category.key) if sorts is None: return None return Catalogues( key="-".join(str(sort.second_id) for sort in sorts), ids=sorts )
[docs] def vocabulary(self, catalogues: Catalogues) -> OptionTable: ids = [sort.second_id for sort in _sorts(catalogues)] return _parse_attributes(self._client().component_attributes(ids))
# -- searching ----------------------------------------------------------
[docs] def search( self, query: CanonicalQuery, category: Category, catalogues: Catalogues, table: OptionTable, ) -> Sequence[Mapping[str, Any]] | NoMatch: """Rows for one query, pooling a category served by several catalogues. JLCPCB's search takes a single `secondSortId`, so a category with two catalogues is two requests whose rows are concatenated. They are pooled rather than tried in turn: stopping at the first catalogue that answered would let the catalogue order decide the part rather than the query's own ranking. """ shared = self._filters(query, category, table) if isinstance(shared, NoMatch): return shared rows: list[Mapping[str, Any]] = [] for sort in _sorts(catalogues): data = self._client().component_list({**shared, **_catalogue(sort)}) page = (data.get("componentPageInfo") or {}).get("list") or [] rows.extend(row for row in page if isinstance(row, dict)) return rows
def _filters( self, query: CanonicalQuery, category: Category, table: OptionTable ) -> dict[str, Any] | NoMatch: """Everything in the request body that does not name a catalogue. A `NoMatch` instead when a filter names a value JLCPCB's vocabulary does not hold, which is a plain no-match rather than something to ask about. """ attributes: list[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"JLCPCB lists no {param.name} for this catalogue") if not names: return NoMatch( f"no JLCPCB {param.name} value satisfies {query.describe()}" ) spelling = table.spelling(param) or param.name attributes.append({spelling: list(names)}) body: dict[str, Any] = { "currentPage": 1, "pageSize": min(100, max(self.page_size, query.limit)), "keyword": keyword(query.filters), "componentLibraryType": None, "stockFlag": self.in_stock, "stockSort": None, "searchSource": "search", "searchType": 3, "sortASC": "", "sortMode": "", "componentBrandList": [], "componentSpecificationList": [], "componentAttributeList": attributes, "paramList": [], "startStockNumber": None, } case = query.filters.get("case") if case is not None: packages = matching_packages(table, case) if not packages: return NoMatch(f"JLCPCB lists no package matching {query.describe()}") body["componentSpecificationList"] = packages manufacturer = query.filters.get("manufacturer") if manufacturer is not None: brands = matching_brands(table, manufacturer) if brands: body["componentBrandList"] = brands # Narrowing towards the requested library tiers. Always a superset of # what the local match keeps, so it can never drop a wanted row. body.update(library.filters(library.wanted(query.filters.get(library.LIBRARY)))) if query.rank: primary = query.rank[0] sort = SORT_FIELDS.get(primary.key) if sort is not None: body["sortMode"] = sort body["sortASC"] = "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 `componentPageInfo.list`, as a `Row`. None when it has no C-number. """ code = str(row.get("componentCode") or "").strip() case = str(row.get("componentSpecificationEn") or "").strip() if not code: return None texts = { str(entry.get("attribute_name_en")): str( entry.get("attribute_value_name") or "" ) for entry in row.get("attributes") or () if isinstance(entry, dict) and entry.get("attribute_name_en") } values: dict[str, Scalar] = {} for key, param in category.params.items(): text = next((texts[n] for n in param.spellings if n in texts), None) if text is None: continue # No numeric hint: a JLCPCB row states a parameter as display text # only, so the option table is what turns it into a number. value = row_value(table, param, text) if value is not None: values[key] = value tier = library.tier( str(row.get("componentLibraryType") or ""), bool(row.get("preferredComponentFlag")), ) values[library.LIBRARY] = tier stock = numeric(row.get("stockCount")) or 0.0 price = _unit_price(row) return Row( code=code, case=case, mpn=str(row.get("componentModelEn") or "").strip(), manufacturer=str(row.get("componentBrandEn") or "").strip() or None, values=values, stock=stock, price=price, reported={ "datasheet": str(row.get("dataManualUrl") or "") or None, "description": str(row.get("describe") or "") or None, "stock": int(stock), "price": price, "min_order_qty": int(numeric(row.get("minPurchaseNum")) or 0), # What JLCPCB will actually load onto the line for this part, # which is a different number from the purchase minimum and the # one that bites on a small assembly order. "min_assembly_qty": int(numeric(row.get("leastPatchNumber")) or 0), "product_url": PRODUCT_URL.format(code=code), }, # The same key the filter uses, stated as a number: a tier is one # property, and ordering by its name would put extended ahead of # preferred. ranked={library.LIBRARY: library.rank(tier)}, )
def _client(self) -> JLCPCBClient: client = self._state.get("client") if client is None: client = JLCPCBClient(base_url=self.base_url, timeout=self.timeout) self._state["client"] = client return client
def _sorts(catalogues: Catalogues) -> tuple[Sort, ...]: """The catalogue ids, which for this source are `Sort`s.""" return tuple(sort for sort in catalogues.ids if isinstance(sort, Sort)) def _catalogue(sort: Sort) -> dict[str, Any]: """The four fields naming one catalogue. All four or none of them bite.""" return { "firstSortId": sort.first_id, "firstSortName": sort.first, "firstSortNameNew": sort.first, "secondSortId": sort.second_id, "secondSortName": sort.second, "secondSortNameNew": sort.second, } def _unit_price(row: Mapping[str, Any]) -> float | None: """The cheapest USD ladder price JLCPCB quotes for the row.""" prices = [ numeric(entry.get("productPrice")) for entry in row.get("componentPrices") 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 _aggregations(data: Mapping[str, Any]) -> Sequence[Mapping[str, Any]]: """The parameter aggregations, from whichever field carries them. At `catalogLevel` 2 the answer arrives on `parentParamRangeList` with `paramRangeList` empty, consistently across all four categories. Preferring the leaf field and falling back is cheaper than depending on that. """ for key in ("paramRangeList", "parentParamRangeList"): found = data.get(key) if isinstance(found, list) and found: return [entry for entry in found if isinstance(entry, dict)] return () def _names(entries: Any) -> tuple[str, ...]: """The `name` of each aggregation bucket.""" if not isinstance(entries, list): return () return tuple( str(entry["name"]) for entry in entries if isinstance(entry, dict) and entry.get("name") ) def _bucket(bucket: Mapping[str, Any]) -> Option: """One aggregation bucket as an `Option`. A scalar states its number in `numericalNormValue` with the interval fields zeroed; a span such as a tolerance states the interval with `numericalNormValue` zeroed. A bucket with neither is either the "-" placeholder or a text value, and carries no number at all - except for a real zero such as "0Ohm", which reads as a measurement and so keeps its 0. """ name = str(bucket["name"]) norm = numeric(bucket.get("numericalNormValue")) if norm: return Option(name=name, start=norm) start = numeric(bucket.get("intervalStartValue")) end = numeric(bucket.get("intervalEndValue")) if start or end: return Option(name=name, start=start, end=end) if measured(name) is not None: return Option(name=name, start=0.0) return Option(name=name) def _parse_attributes(data: Mapping[str, Any]) -> OptionTable: """Read a `filterComponentAttribute` response into an OptionTable.""" packages = _names(data.get("componentSpecificationList")) # JLCPCB names a manufacturer by name in a request, where LCSC wants an id, # so the token a brand maps to is the brand itself. brands = {name: name for name in _names(data.get("componentBrandList"))} params: dict[str, ParamOptions] = {} for entry in _aggregations(data): name = str(entry.get("name") or "") if not name: continue options = tuple( _bucket(bucket) for bucket in entry.get("subAggs") or () if isinstance(bucket, dict) and bucket.get("name") ) # A span is what a two-ended bucket makes it; nothing in the response # says so, and the `Param` table's own `span` is not in reach here. span = any(option.end is not None for option in options) params[name] = ParamOptions(options=options, unit=derive_unit(options, span)) return OptionTable(packages=packages, brands=brands, params=params)