"""
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.
"""
from __future__ import annotations
from abc import abstractmethod
from collections.abc import Mapping, Sequence
from dataclasses import dataclass, field
from typing import Any
from jitx.units import registry
from pint.errors import DimensionalityError
from jitxlib.parts.error import StalePayload
from jitxlib.parts.provider import (
JSON,
CanonicalQuery,
CategoryProvider,
Exactly,
NoMatch,
Outcome,
PartIdentity,
Predicate,
Resolved,
ResolvedPart,
Scalar,
Unsupported,
apply_fields,
decode_payload,
encode_payload,
match,
rank_by,
satisfies,
)
from ..part import LCSCPart
from .catalog import (
CATEGORIES,
IDENTITY_KEYS,
STRUCTURAL_KEYS,
Category,
Param,
category_for,
has_generator,
numeric,
quantity,
)
from .options import OptionCache, OptionTable, measured, span_magnitude
PAYLOAD_VERSION = 1
# Payload keys that are bookkeeping rather than something a design should see.
PRIVATE_PAYLOAD = frozenset({"v"})
[docs]
@dataclass(frozen=True)
class CatalogPart:
"""A part resolved from the catalogue. Implements ResolvedPart."""
identity: PartIdentity
payload: dict[str, JSON]
[docs]
def materialize(self, component: Any) -> None:
"""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.
"""
from jitxlib.parts.providers.geometry import passive_geometry
from ..landpattern import LCSCLandpattern
identity = self.identity
case = str(identity.attributes.get("case", ""))
polarized = bool(identity.attributes.get("polarized"))
code = str(identity.attributes["lcsc"])
if has_generator(case):
landpattern, symbol = passive_geometry(identity.category, case, polarized)
component.landpattern = landpattern
else:
symbol = passive_symbol(identity.category, polarized)
# No mapping: the default binds the ports in declaration order to
# the pads in catalogue order, which for a two-pin passive is p1/p2
# or a/c onto pads 1 and 2.
component.landpattern = LCSCLandpattern(partnumber=code)
component.symbol = symbol
fields = decode_payload(self.payload)
apply_fields(
component,
{k: v for k, v in fields.items() if k not in PRIVATE_PAYLOAD and v},
)
# `lcsc_part`, not `lcsc`: the core has already set `lcsc` to the
# C-number string from the identity, which is what a query filters on,
# and shadowing it with an object would make `r.lcsc` mean one thing in
# the query language and another on the component. `decompose` finds
# this by type, so the field name is free.
#
# The footprint is the catalogue's own package code. The exporter treats
# an explicit footprint as authoritative and a landpattern-derived one as
# guessed, and the catalogue's package code is exactly the non-guess
# that field is for.
component.lcsc_part = LCSCPart(partnumber=code, footprint=case or None)
[docs]
@dataclass(frozen=True)
class Catalogues:
"""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.
"""
key: str
ids: tuple[Any, ...]
[docs]
@dataclass(frozen=True)
class Row:
"""One catalogue row, read into the shape a lockfile entry is built from.
Args:
code: the LCSC C-number, which both sources carry.
case: the package code as the catalogue spells it.
mpn: manufacturer part number.
manufacturer: manufacturer name, or None where the row states none.
values: queryable attributes, being the category's parameters plus
whatever synthetic ones the source adds, such as `library`.
stock: quantity on hand, for ranking.
price: cheapest USD ladder price, or None where the row quotes none.
reported: payload fields, which a design sees on the component but
cannot query. Snapshots belong here rather than in `values`.
ranked: ranking-only keys, for an ordering that is not a filter.
"""
code: str
case: str
mpn: str
manufacturer: str | None
values: dict[str, Scalar]
stock: float
price: float | None
reported: dict[str, JSON]
ranked: dict[str, Scalar] = field(default_factory=dict)
[docs]
class CatalogSource(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."""
_state: dict[str, Any]
"""Lazily built collaborators, kept out of `config()` and out of equality."""
# -- what a source supplies ---------------------------------------------
[docs]
@abstractmethod
def catalogues(self, category: Category) -> Catalogues | None:
"""Which catalogues serve `category`, or None if this source has none."""
[docs]
@abstractmethod
def vocabulary(self, catalogues: Catalogues) -> OptionTable:
"""The filter vocabulary for a set of catalogues. One request."""
[docs]
@abstractmethod
def search(
self,
query: CanonicalQuery,
category: Category,
catalogues: Catalogues,
table: OptionTable,
) -> Sequence[Mapping[str, Any]] | NoMatch:
"""Rows for one query, or a `NoMatch` naming what could not be asked."""
[docs]
@abstractmethod
def read(
self, row: Mapping[str, Any], category: Category, table: OptionTable
) -> Row | None:
"""One row as a `Row`, or None if it is not a part this source can hand back."""
@property
def sort_fields(self) -> Mapping[str, str]:
"""Rank keys this source pushes to the API's own sort."""
return {}
@property
def extra_keys(self) -> frozenset[str]:
"""Filter keys this source serves beyond the category's parameters."""
return frozenset()
# -- resolution ---------------------------------------------------------
[docs]
def resolve_one(self, query: CanonicalQuery) -> Outcome:
polarized = wants(query.filters.get("polarized"), True, "polarized")
category = category_for(query.category, polarized)
if category is None:
return Unsupported(
(),
f"{self.name} serves {', '.join(sorted(CATEGORIES))}, "
f"not {query.category}",
)
catalogues = self.catalogues(category)
if catalogues is None:
return Unsupported((), f"{self.name} has no catalogue for {query.category}")
unserved = self._unserved(query, category)
if unserved:
return Unsupported(
unserved,
f"{self.name}'s {query.category} catalogue has no such parameter",
)
table = self._options().get(catalogues.key, lambda: self.vocabulary(catalogues))
rows = self.search(query, category, catalogues, table)
if isinstance(rows, NoMatch):
return rows
if not rows:
return NoMatch(f"{self.name} listed nothing for {query.describe()}")
candidates: list[tuple[CatalogPart, dict[str, Scalar]]] = []
for row in rows:
built = self._part(row, category, table)
if built is None:
continue
part, ranking = built
if not match(query.filters, part.identity.attributes, part.identity):
continue
candidates.append((part, ranking))
if not candidates:
return NoMatch(
f"none of {self.name}'s {len(rows)} rows satisfied {query.describe()}"
)
ordered = rank_by(candidates, query.rank, key=lambda pair: pair[1])
limit = max(1, query.limit)
return Resolved(tuple(part for part, _ in ordered[:limit]))
[docs]
def rehydrate(
self, identity: PartIdentity, payload: dict[str, JSON]
) -> ResolvedPart:
"""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.
"""
if payload.get("v") != PAYLOAD_VERSION:
raise StalePayload(
f"{self.name}: unknown payload version {payload.get('v')!r}"
)
if "lcsc" not in identity.attributes:
raise StalePayload(f"{self.name}: entry carries no lcsc part number")
return CatalogPart(identity=identity, payload=dict(payload))
[docs]
def distinct(self, query: CanonicalQuery, key: str) -> Sequence[object] | None:
"""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.
"""
polarized = wants(query.filters.get("polarized"), True, "polarized")
category = category_for(query.category, polarized)
if category is None:
return None
catalogues = self.catalogues(category)
if catalogues is None:
return None
table = self._options().get(catalogues.key, lambda: self.vocabulary(catalogues))
if key == "case":
return list(table.packages)
if key == "manufacturer":
return sorted(table.brands)
param = category.params.get(key)
if param is None:
return None
values = [table.value(param, option) for option in table.options(param)]
return [v for v in values if v is not None]
# -- shared internals ---------------------------------------------------
def _unserved(self, query: CanonicalQuery, category: Category) -> tuple[str, ...]:
"""Query keys this catalogue cannot answer.
Declined per query, as the provider protocol asks: there is no capability
manifest, so this is a statement about what can be done with the
catalogue in hand rather than a declaration made in advance.
"""
served = (
IDENTITY_KEYS | STRUCTURAL_KEYS | set(category.params) | self.extra_keys
)
rankable = served | set(self.sort_fields)
wanted_keys = set(query.filters) | {
r.key for r in query.rank if r.key not in rankable
}
return tuple(sorted(wanted_keys - served))
def _part(
self, row: Mapping[str, Any], category: Category, table: OptionTable
) -> tuple[CatalogPart, dict[str, Scalar]] | None:
"""A resolved part and its ranking view, or None if the row is unusable."""
read = self.read(row, category, table)
if read is None or not read.mpn:
return None
attributes: dict[str, Scalar] = {"case": read.case, "lcsc": read.code}
if category.polarized:
attributes["polarized"] = True
attributes.update(read.values)
identity = PartIdentity(
mpn=read.mpn,
manufacturer=read.manufacturer,
category=category.name,
provider=self.name,
provider_ref=read.code,
attributes=attributes,
)
payload = encode_payload({"v": PAYLOAD_VERSION, **read.reported})
# Stock and price rank but do not filter: they are payload, because they
# go stale between runs, and `PartIdentity.attributes` is a promise to
# serve a key as a query term.
ranking: dict[str, Scalar] = dict(attributes)
ranking.update(read.ranked)
ranking["stock"] = read.stock
ranking["price"] = read.price if read.price is not None else float("inf")
return CatalogPart(identity=identity, payload=payload), ranking
def _options(self) -> OptionCache:
cache = self._state.get("options")
if cache is None:
cache = OptionCache(self.cache_dir)
self._state["options"] = cache
return cache
# --------------------------------------------------------------------------
# Reading a query and a row, the same way on both sources
# --------------------------------------------------------------------------
[docs]
def passive_symbol(category: str, polarized: bool) -> Any:
"""The symbol `passive_geometry` gives a part, without its landpattern."""
from jitxlib.parts.providers.geometry import SYMBOL_FOR
from jitxlib.symbols.capacitor.capacitor import PolarizedCapacitorSymbol
if polarized and category == "capacitor":
return PolarizedCapacitorSymbol()
return SYMBOL_FOR[category]()
[docs]
def wants(predicate: Predicate | None, value: Scalar, key: str) -> bool:
"""Whether a filter asks for `value`. A missing filter asks for nothing."""
if predicate is None:
return False
return satisfies(predicate, value, key)
[docs]
def keyword(filters: Mapping[str, Predicate]) -> str | None:
"""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.
"""
for key in ("lcsc", "mpn"):
predicate = filters.get(key)
if isinstance(predicate, Exactly) and isinstance(predicate.value, str):
return predicate.value
return None
[docs]
def row_value(
table: OptionTable,
param: Param,
text: str,
hint: Any = None,
) -> Scalar | None:
"""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.
"""
text = text.strip()
if not text:
return None
unit, scale = table.unit_of(param)
if unit is None:
return text
if param.span:
option = table.index(param).get(text)
raw = option.magnitude(param.span) if option is not None else None
if raw is not None:
return quantity(raw * scale, unit)
raw = span_magnitude(text)
return quantity(raw * scale, unit) if raw is not None else None
raw = numeric(hint)
if raw is None:
option = table.index(param).get(text)
raw = option.magnitude(param.span) if option is not None else None
if raw is not None:
return quantity(raw * scale, unit)
return _from_text(text, unit)
def _from_text(text: str, unit: str) -> Scalar | None:
"""A displayed value read with the unit written in it, or None.
Its own unit rather than the parameter's, since "50V" says what it is; the
conversion is only there to reject a value that is not the quantity this
parameter measures.
"""
read = measured(text)
if read is None:
return None
number, symbol = read
try:
return quantity(
float(registry.Quantity(number, symbol).to(unit).magnitude), unit
)
except (DimensionalityError, ValueError, TypeError):
return None