jitxlib.jlcpcb.parts package#

JLCPCB and LCSC parts for JITX#

Two jitxlib-parts providers that resolve passives against the same catalogue from the two ends it is sold from, and attach an LCSCPart to every component they materialize, so a design exports to JLCPCB with its C-numbers already in place.

JLCPCBParts the default. Knows the assembly library a part is in. LCSCParts the same catalogue through LCSC’s own API.

Installing this package is enough: it publishes a chain of its own, so a project that configures nothing resolves through JLCPCBParts.

Choosing the LCSC source instead#

Name a chain. That is the lowest-precedence setting the package’s own published chain loses to, so one line is enough:

[tool.jitx.parts] chain = [“lcsc”]

or in code, which is also how to configure the provider rather than take it as it comes:

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

PartSource([LCSCParts(in_stock=True)])

Naming a chain is also how to put an approved-parts list in front of a catalogue, with either source behind it:

[tool.jitx.parts] chain = [“csv:parts/approved.csv”, “jlcpcb”]

JLCPCBParts is otherwise the more capable of the two. The reasons to reach for LCSC are that it is roughly three times faster per request and that it aggregates a chip resistor’s rated voltage, which JLCPCB does not; both are spelled out on jitxlib.jlcpcb.parts.jlcpcb.

Landpatterns#

A part whose case the stdlib chip generator builds, such as 0402 or 1206, gets that generated landpattern. Any other package, a tantalum CASE-B or an aluminum can, gets the catalogue’s own footprint through LCSCLandpattern, recorded in lcsc.lock.json like any other, with the component’s ports bound to the pads in order.

That order is safe for an unpolarized part. For a polarized one it assumes the catalogue draws the anode as pad 1. No part seen so far contradicts that, but check the polarity of a catalogue-footprint capacitor before ordering boards: one that did would be placed reversed.

Basic, preferred and extended parts#

JLCPCBParts serves a synthetic library attribute, so which assembly library a part comes from is an ordinary query filter and can be set once for a whole design:

from jitxlib.parts import Minimize, ResistorQuery

with ResistorQuery(library=”basic”):

… # every resistor from the basic library

ResistorQuery(rank=Minimize(“library”)) # prefer basic, accept worse

See jitxlib.jlcpcb.parts.library for the three tiers and what they cost.

Selections pin to the parts lockfile like any other provider’s, so a second run asks the catalogue nothing and a run with no network still builds what the lock holds. The two sources are separate providers with separate names, so moving a project from one to the other re-resolves its parts once, deliberately.

class CatalogPart(identity, payload)[source]#

Bases: object

A part resolved from the catalogue. Implements ResolvedPart.

Parameters:
identity: PartIdentity#
payload: dict[str, JSON]#
materialize(component)[source]#

Attach the landpattern, the symbol, and the LCSC part number.

The LCSCPart is the point of either source: the JLCPCB exporter finds it with decompose(component, LCSCPart), so a design resolved through this chain carries its C-numbers without anyone writing one.

The landpattern is the stdlib generator’s where it builds the case, and the catalogue footprint otherwise. That footprint is bound with the default in-order mapping, which for a polarized part assumes the catalogue draws the anode as pad 1; no part seen so far contradicts that, but one that does would be placed reversed.

Return type:

None

Parameters:

component (Any)

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:
class JSONClient(base_url, timeout=20.0, attempts=2)[source]#

Bases: ABC

POSTs JSON to one host and unwraps whatever envelope it answers with.

Parameters:
  • base_url (str) – API host, for pointing at a mirror or a recording proxy.

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

  • attempts (int) – how many times a request is tried before giving up.

base_url: str#
timeout: float = 20.0#
attempts: int = 2#
abstract 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.

abstractmethod 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:
post(path, body)[source]#

The result of one request, or ProviderUnavailable naming why not.

Return type:

dict[str, Any]

Parameters:
unavailable(message)[source]#

A ProviderUnavailable naming this client, for unwrap to raise.

Return type:

ProviderUnavailable

Parameters:

message (str)

class LCSCClient(base_url='https://wmsc.lcsc.com', timeout=20.0, attempts=2)[source]#

Bases: JSONClient

Talks to the LCSC list API.

>>> client = LCSCClient()
>>> body = {"keyword": "C25744", "currentPage": 1, "pageSize": 1}
>>> client.product_list(body)["dataList"][0]["productCode"]
'C25744'
Parameters:
base_url: str = 'https://wmsc.lcsc.com'#
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:
product_list(body)[source]#

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

Return type:

dict[str, Any]

Parameters:

body (dict[str, Any])

param_group(catalog_ids)[source]#

The filter vocabulary for a set of catalogs. Returns result.

Return type:

dict[str, Any]

Parameters:

catalog_ids (Sequence[int])

class LCSCParts(base_url='https://wmsc.lcsc.com', in_stock=True, page_size=25, cache_dir='.jitx/lcsc', timeout=20.0, name='lcsc')[source]#

Bases: CatalogSource

Resolve passives against the LCSC catalogue.

>>> from jitxlib.parts import PartSource
>>> source = PartSource([LCSCParts()])
Parameters:
  • base_url (str) – the API host.

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

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

  • 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://wmsc.lcsc.com'#
in_stock: bool = True#
page_size: int = 25#
cache_dir: str | None = '.jitx/lcsc'#

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

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

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

dict[str, JSON]

property sort_fields: Mapping[str, str]#

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

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, or a NoMatch naming what could not be asked.

Return type:

Sequence[Mapping[str, Any]] | NoMatch

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

A row of dataList, as a Row.

None when it has no C-number.

Return type:

Row | None

Parameters:
chain()[source]#

The default chain: JLCPCB, and nothing behind it.

Nothing behind it on purpose. An ideal fallback would let a design elaborate at a value the catalogue does not stock, but it synthesizes a part with no manufacturer and no C-number, which is not something JLCPCB can assemble. On a board headed for their assembly line, a value nobody sells should be an error rather than a placeholder.

LCSCParts is not behind it either, for the same reason a fallback chain is usually a mistake here: the two sources read one catalogue, so a part LCSC would find and JLCPCB would not is a part JLCPCB declined to classify, and silently taking it would lose the library information the default exists to provide. A project that wants LCSC should name it.

Return type:

PartSource

Submodules#