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:
objectA part resolved from the catalogue. Implements ResolvedPart.
- Parameters:
identity (PartIdentity)
- identity: PartIdentity#
- 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.
- class JLCPCBClient(base_url='https://jlcpcb.com/api/overseas-pcb-order', timeout=20.0, attempts=2)[source]#
Bases:
JSONClientTalks 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'
- 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.
- 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:
CatalogSourceResolve 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)
- cache_dir: str | None = '.jitx/jlcpcb'#
Where the filter vocabulary is cached, or None for memory only.
- 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.
- 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:
- Parameters:
category (Category)
- vocabulary(catalogues)[source]#
The filter vocabulary for a set of catalogues. One request.
- Return type:
- 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:
- Parameters:
query (CanonicalQuery)
category (Category)
catalogues (Catalogues)
table (OptionTable)
- class JSONClient(base_url, timeout=20.0, attempts=2)[source]#
Bases:
ABCPOSTs JSON to one host and unwraps whatever envelope it answers with.
- Parameters:
- 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.
A ProviderUnavailable naming this client, for unwrap to raise.
- Return type:
- Parameters:
message (str)
- class LCSCClient(base_url='https://wmsc.lcsc.com', timeout=20.0, attempts=2)[source]#
Bases:
JSONClientTalks to the LCSC list API.
>>> client = LCSCClient() >>> body = {"keyword": "C25744", "currentPage": 1, "pageSize": 1} >>> client.product_list(body)["dataList"][0]["productCode"] 'C25744'
- 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.
- 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:
CatalogSourceResolve 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)
- cache_dir: str | None = '.jitx/lcsc'#
Where the filter vocabulary is cached, or None for memory only.
- 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.
- catalogues(category)[source]#
Which catalogues serve category, or None if this source has none.
- Return type:
- Parameters:
category (Category)
- vocabulary(catalogues)[source]#
The filter vocabulary for a set of catalogues. One request.
- Return type:
- Parameters:
catalogues (Catalogues)
- search(query, category, catalogues, table)[source]#
Rows for one query, or a NoMatch naming what could not be asked.
- Return type:
- Parameters:
query (CanonicalQuery)
category (Category)
catalogues (Catalogues)
table (OptionTable)
- 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: