jlcpcb module#

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.

class Sort(first_id, first, second_id, second)[source]#

Bases: object

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.

Parameters:
first_id: int#
first: str#
second_id: int#
second: str#
class JLCPCBClient(base_url='https://jlcpcb.com/api/overseas-pcb-order', timeout=20.0, attempts=2)[source]#

Bases: 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"]
'base'
Parameters:
base_url: str = 'https://jlcpcb.com/api/overseas-pcb-order'#
property label: str#

How this client names itself in a ProviderUnavailable message.

property origin: dict[str, str]#

Extra headers this host wants, such as an Origin and a Referer.

unwrap(path, payload)[source]#

The result object inside a decoded response body.

Raises ProviderUnavailable when the body says the request failed, which is where the two APIs’ envelopes differ: LCSC answers {“code”: 200, “result”: …} and JLCPCB {“code”: 200, “data”: …}, both reporting failure with a non-200 code and HTTP 200.

Return type:

dict[str, Any]

Parameters:
component_list(body)[source]#

Search results for one query body. Returns the data object.

Return type:

dict[str, Any]

Parameters:

body (dict[str, Any])

component_attributes(type_ids)[source]#

The filter vocabulary for a set of second-level catalogues.

Return type:

dict[str, Any]

Parameters:

type_ids (Sequence[int])

class JLCPCBParts(base_url='https://jlcpcb.com/api/overseas-pcb-order', in_stock=True, page_size=25, cache_dir='.jitx/jlcpcb', timeout=20.0, name='jlcpcb')[source]#

Bases: 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.

Parameters:
  • base_url (str) – the API host.

  • in_stock (bool) – restrict the search to parts JLCPCB has in stock.

  • page_size (int) – how many rows to ask for per query, per catalogue.

  • cache_dir (str | None) – where the filter vocabulary is cached, relative to the project. None disables the on-disk copy.

  • timeout (float) – per-request timeout in seconds.

  • name (str)

base_url: str = 'https://jlcpcb.com/api/overseas-pcb-order'#
in_stock: bool = True#
page_size: int = 25#
cache_dir: str | None = '.jitx/jlcpcb'#

Where the filter vocabulary is cached, or None for memory only.

timeout: float = 20.0#
name: str = 'jlcpcb'#

How this provider is named in diagnostics and lockfile entries.

Supply it as a dataclass field, a plain class attribute, or an assignment in __init__. A property or a ClassVar is an incompatible override; for a derived name, use field(init=False) and set it in __post_init__.

config()[source]#

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 type:

dict[str, JSON]

property sort_fields: Mapping[str, str]#

Rank keys this source pushes to the API’s own sort.

property extra_keys: frozenset[str]#

Filter keys this source serves beyond the category’s parameters.

catalogues(category)[source]#

Which catalogues serve category, or None if this source has none.

Return type:

Catalogues | None

Parameters:

category (Category)

vocabulary(catalogues)[source]#

The filter vocabulary for a set of catalogues. One request.

Return type:

OptionTable

Parameters:

catalogues (Catalogues)

search(query, category, catalogues, table)[source]#

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.

Return type:

Sequence[Mapping[str, Any]] | NoMatch

Parameters:
read(row, category, table)[source]#

A row of componentPageInfo.list, as a Row.

None when it has no C-number.

Return type:

Row | None

Parameters: