"""
The basic / preferred / extended library tier
=============================================
JLCPCB charges assembly per distinct part number that is not in their basic
library, so which library a part comes from is a cost decision a design should
be able to make. Nothing in the catalogue data says it: it is JLCPCB's own
classification of LCSC's shelves, which is why only the JLCPCB source can
answer it and the LCSC source cannot.
It reaches a design as a synthetic query attribute, `library`, taking one of
three values:
basic no per-part setup fee. A small, curated set.
preferred reduced setup fee. JLCPCB's "preferred extended" parts.
extended full setup fee per part number.
Being an attribute rather than a request knob is what makes it work from a
design-level query context, and what makes any predicate over it work:
from jitxlib.parts import OneOf, ResistorQuery
with ResistorQuery(library="basic"):
... # every resistor from the basic library
ResistorQuery(resistance=10 * kohm, library=OneOf(("basic", "preferred")))
The value is read off every row, so it lands in `PartIdentity.attributes` and
the ordinary local match decides. It is an attribute and not payload on purpose:
stock and price are snapshots that go stale between runs, but library membership
is a catalogue property like the package code, and a design that asked for a
basic part *should* re-resolve if JLCPCB moves it rather than quietly keep a
part that now carries a fee. So it pins to the lockfile with everything else.
A hard filter cannot say "prefer basic, accept extended", which is what most
designs actually want, because the basic library is small enough that a strict
predicate often finds nothing: 351 parts across all of SMT, of which 182 are
chip resistors and 2 are SMD inductors. So the same key ranks:
ResistorQuery(resistance=10 * kohm, rank=Minimize("library"))
One key rather than two, because a tier is one property of a part and a design
should not have to know that asking to filter on it and asking to order by it
are different questions. A filter sees the name and an ordering sees `rank`
below, which is what `Row.ranked` is for: the ranking view of a row is not
obliged to state a value the same way the attributes do.
Ordering by the name instead would be quietly wrong rather than merely
unavailable. Alphabetically "extended" sorts before "preferred", so the more
expensive tier would come out ahead of the cheaper one and the result would
still look plausible.
Narrowing the request
---------------------
The tiers compose as a union on JLCPCB's side, which was probed rather than
assumed: `componentLibraryType: "base"` sent together with
`preferredComponentFlag: true` answers the basic parts *plus* the preferred
ones. `componentLibTypes: ["expand"]` answers preferred and extended together,
since a preferred part is an `expand` part carrying a flag, and
`preferredComponentFlag: false` is ignored rather than meaning "not preferred".
So some tier sets narrow exactly, some narrow to a superset, and one cannot
narrow at all. `filters` below is that table. Correctness never rests on it:
the attribute is on the row and the local match is authoritative. It exists so
a basic-only query does not page through 109 496 extended chip resistors to
find the 30 basic ones.
"""
from __future__ import annotations
from typing import Any
from jitxlib.parts.provider import Predicate, satisfies
#: The query key, for both filtering and ranking.
LIBRARY = "library"
BASIC = "basic"
PREFERRED = "preferred"
EXTENDED = "extended"
#: Every tier, cheapest to assemble first. This order is what `rank` returns.
TIERS: tuple[str, ...] = (BASIC, PREFERRED, EXTENDED)
# JLCPCB's own spelling of the two library types a row carries.
BASE_TYPE = "base"
EXPAND_TYPE = "expand"
[docs]
def tier(library_type: str, preferred: bool) -> str:
"""The tier of a row, from its library type and preferred flag.
Anything JLCPCB does not call `base` is an extended part, preferred or not,
so an unrecognized library type reads as extended rather than as an error:
the conservative answer is the one that assumes a fee.
"""
if library_type.strip().lower() == BASE_TYPE:
return BASIC
return PREFERRED if preferred else EXTENDED
[docs]
def rank(name: str) -> int:
"""A tier as a number to order by: 0 basic, 1 preferred, 2 extended.
What `Minimize("library")` sorts on. Cheapest to assemble is lowest, so
minimizing means preferring the parts that cost least to place.
"""
try:
return TIERS.index(name)
except ValueError: # pragma: no cover - `tier` only returns known names
return len(TIERS)
[docs]
def wanted(predicate: Predicate | None) -> frozenset[str]:
"""The tiers a predicate admits. Every tier when it asks for nothing.
Evaluated against the three known values rather than inspected, so any
predicate the query language can express works without this module knowing
which kinds there are.
"""
if predicate is None:
return frozenset(TIERS)
return frozenset(t for t in TIERS if satisfies(predicate, t, LIBRARY))
[docs]
def filters(tiers: frozenset[str]) -> dict[str, Any]:
"""Request fields narrowing the search towards `tiers`.
A superset is allowed and an empty dict is always correct, so this only ever
returns fields that cannot exclude a row the local match would have kept.
"""
if not tiers or tiers == frozenset(TIERS):
return {}
narrowed: dict[str, Any] = {}
if BASIC in tiers:
narrowed["componentLibraryType"] = BASE_TYPE
if PREFERRED in tiers:
# The two compose as a union, so this widens rather than intersects.
narrowed["preferredComponentFlag"] = True
elif EXTENDED in tiers:
# Basic or extended but not preferred: no field says that, and
# naming either one alone would drop the other half.
return {}
elif PREFERRED in tiers and EXTENDED in tiers:
narrowed["componentLibTypes"] = [EXPAND_TYPE]
elif PREFERRED in tiers:
narrowed["preferredComponentFlag"] = True
else:
# Extended alone. `expand` also carries the preferred parts, so this is
# the superset and the local match drops them.
narrowed["componentLibTypes"] = [EXPAND_TYPE]
return narrowed