source module#

The resolve flow both part sources share#

CatalogSource is everything about answering a passive query that does not depend on which of the two APIs is being asked: deciding the category, declining what the catalogue cannot serve, fetching the filter vocabulary, matching and ranking the page locally, and turning a row into a lockfile entry.

A source supplies four things and inherits the rest:

catalogues() which catalogues serve a category, and a cache key for them vocabulary() the filter vocabulary for those catalogues search() rows for one query read() one row, as a Row

CatalogPart is shared whole. Both sources resolve to a part with an LCSC C-number, because JLCPCB sells LCSC’s shelves, so both attach the same LCSCPart for the exporter to find.

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 Catalogues(key, ids)[source]#

Bases: object

The catalogues serving one category, and a cache key naming them.

ids is whatever the source numbers a catalogue by; only search and vocabulary look inside it. key names the set in a cache filename and in a provider’s config, so it has to be stable and readable.

Parameters:
key: str#
ids: tuple[Any, ...]#
class Row(code, case, mpn, manufacturer, values, stock, price, reported, ranked=dict())[source]#

Bases: object

One catalogue row, read into the shape a lockfile entry is built from.

Parameters:
  • code (str) – the LCSC C-number, which both sources carry.

  • case (str) – the package code as the catalogue spells it.

  • mpn (str) – manufacturer part number.

  • manufacturer (str | None) – manufacturer name, or None where the row states none.

  • values (dict[str, float | int | str | bool | PlainQuantity]) – queryable attributes, being the category’s parameters plus whatever synthetic ones the source adds, such as library.

  • stock (float) – quantity on hand, for ranking.

  • price (float | None) – cheapest USD ladder price, or None where the row quotes none.

  • reported (dict[str, JSON]) – payload fields, which a design sees on the component but cannot query. Snapshots belong here rather than in values.

  • ranked (dict[str, float | int | str | bool | PlainQuantity]) – ranking-only keys, for an ordering that is not a filter.

code: str#
case: str#
mpn: str#
manufacturer: str | None#
values: dict[str, float | int | str | bool | PlainQuantity]#
stock: float#
price: float | None#
reported: dict[str, JSON]#
ranked: dict[str, float | int | str | bool | PlainQuantity]#
class CatalogSource[source]#

Bases: CategoryProvider

Resolve passives against one of the two catalogue APIs.

What either source serves is resistors, ceramic and polarized capacitors, and fixed inductors, in any package the catalogue lists. A case the stdlib generator builds gets its landpattern; any other gets the catalogue’s own footprint, see CatalogPart.materialize. Anything else in the catalogue is declined per query rather than guessed at.

Not a dataclass itself: a source is one, and these two are fields it supplies, so declaring them here would take the first constructor slots and force every source to put its own arguments behind them.

cache_dir: str | None#

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

abstractmethod catalogues(category)[source]#

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

Return type:

Catalogues | None

Parameters:

category (Category)

abstractmethod vocabulary(catalogues)[source]#

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

Return type:

OptionTable

Parameters:

catalogues (Catalogues)

abstractmethod 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:
abstractmethod read(row, category, table)[source]#

One row as a Row, or None if it is not a part this source can hand back.

Return type:

Row | None

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

resolve_one(query)[source]#

Answer one query. config and rehydrate are still yours to write.

Return type:

Resolved | NoMatch | Unsupported | Deny

Parameters:

query (CanonicalQuery)

rehydrate(identity, payload)[source]#

Rebuild a part from a lockfile entry, without asking the API anything.

The identity carries the case code and the C-number, which is everything materialize needs, so a replay run never touches the network.

Return type:

ResolvedPart

Parameters:
distinct(query, key)[source]#

Values of key in this catalogue’s vocabulary for the category.

Answered from the filter vocabulary rather than from a search, since that is what a catalogue publishes it for: it is the whole catalogue’s set of values, not the ones a particular query happens to reach.

Return type:

Sequence[object] | None

Parameters:
passive_symbol(category, polarized)[source]#

The symbol passive_geometry gives a part, without its landpattern.

Return type:

Any

Parameters:
wants(predicate, value, key)[source]#

Whether a filter asks for value. A missing filter asks for nothing.

Return type:

bool

Parameters:
keyword(filters)[source]#

A free-text term pinning the search to one part, when the query names one.

Neither API has an exact-identity filter, so an mpn or an lcsc number goes in as a keyword and the local match does the rest.

Return type:

str | None

Parameters:

filters (Mapping[str, Predicate])

row_value(table, param, text, hint=None)[source]#

One parameter of one row, as an attribute value.

text is the value as the row displays it and hint is a numeric field the row states alongside it, which LCSC has and JLCPCB does not. Both numbers are in the parameter’s own standard unit, which is why the table rather than the row decides what they mean: a capacitance comes back in pF and an inductance in uH.

Three readings, in order of how much they can be trusted. The row’s own number where it has one; the catalogue’s option table, which is where a range such as a tolerance has to be read from because neither source states one numerically on every row; and finally the display text itself, parsed with the unit written in it.

That last one is not a nicety. A parameter can be absent from the filter vocabulary and present on the row - a chip resistor’s rated voltage is on every JLCPCB row and in none of its aggregations - and without it such a value would be dropped rather than merely unsearchable.

Return type:

float | int | str | bool | PlainQuantity | None

Parameters: