Source code for jitxlib.jlcpcb.parts.options

"""
Turning a predicate into catalogue option names
===============================================

Neither source has a numeric range filter. Both take option names as the
catalogue spells them, so "resistance between 9k and 11k" cannot be asked for
directly: LCSC refuses a start and end value with `Invalid request param`, and
JLCPCB's own range UI does the filtering in the browser and sends the names it
arrived at.

What makes it workable is the filter-vocabulary endpoint, which returns every
option name for a catalogue together with its numeric value. Translation is
therefore: fetch the option list, keep the names whose value satisfies the JITX
predicate, and send those names. This module is that translation, and it is the
same on both sources.

The option list is the one thing worth caching. It is large, 1200 to 4097
entries for resistance depending on which source is asked, it changes slowly,
and nothing can be asked before it is in hand. Search results are deliberately
not cached: the parts lockfile is what makes a second run reproducible, and a
result cache would be a second, weaker answer to the same question.
"""

from __future__ import annotations

import dataclasses
import json
import re
import time
from collections.abc import Callable, Mapping, Sequence
from dataclasses import dataclass
from pathlib import Path

from jitx.units import registry
from jitxlib.parts.provider import (
    Exactly,
    OneOf,
    Predicate,
    Range,
    Scalar,
    Tolerance,
    is_quantity,
    satisfies,
)

from .catalog import Param, numeric, pint_unit

CACHE_VERSION = 3

# How many option names one filter may send. A broad range over 4097 resistance
# values is not a useful thing to put in a request body, so the options nearest
# the predicate's centre go in and the local match does the rest.
MAX_OPTIONS = 50

# Numbers inside a value stated as text, such as "+/-1%" or "-30%~0%".
NUMBERS = re.compile(r"[-+]?\d*\.?\d+")

# An option name that is one number and one unit, such as "10kOhm" or "0.08pF".
# The leading sign covers "+/-1%"; anything with a second number, such as
# "-20%~+25%", deliberately fails to match.
MEASURED = re.compile(r"^[-+\u00b1]?\s*(\d*\.?\d+)\s*([^\d\s][^\d]*)$")


[docs] @dataclass(frozen=True) class Option: """One selectable value of a catalogue parameter. A plain value carries only `start`; a range option such as a tolerance carries both. LCSC states these as `standardUnitValue` and `standardUnitEndValue`, JLCPCB as `numericalNormValue` and the `intervalStartValue` / `intervalEndValue` pair. """ name: str start: float | None = None end: float | None = None
[docs] def magnitude(self, span: bool) -> float | None: """This option's number, in whatever unit the parameter is stated in. A span option is reduced to its half width, since that is what a tolerance means: a catalogue's "+/-1%" is -1 to 1, and a design asking for `AtMost(1 * pct)` is asking about the half width. """ if self.start is None: return None if span: end = self.end if self.end is not None else self.start return max(abs(self.start), abs(end)) return self.start
[docs] @dataclass(frozen=True) class ParamOptions: """One parameter's selectable values, and the unit they are stated in. `unit` is the unit every number for that parameter is expressed in, read off whatever the source's response declares. None where the source declares none, which is both a text parameter and the ppm case. """ options: tuple[Option, ...] unit: str | None = None
[docs] @dataclass(frozen=True) class OptionTable: """The filter vocabulary of one category's catalogues. Args: packages: package codes the catalogues carry. brands: manufacturer name to the token a request names it by. That is an id on LCSC and the name itself on JLCPCB, so a caller sends the values and never builds one. params: parameter name to its options and their unit. """ packages: tuple[str, ...] brands: Mapping[str, str] params: Mapping[str, ParamOptions] _index: dict[str, dict[str, Option]] = dataclasses.field( default_factory=dict, compare=False, repr=False )
[docs] def spelling(self, param: Param) -> str | None: """The name this vocabulary lists `param` under, or None if it does not. This is what a request has to say, which is why it comes off the table rather than off the `Param`: the canonical name is a statement about the catalogue in general and this is a statement about the answer in hand. """ for name in param.spellings: if name in self.params: return name return None
[docs] def index(self, param: Param) -> Mapping[str, Option]: """This parameter's options by name, built once per table.""" key = self.spelling(param) or param.name found = self._index.get(key) if found is None: found = {option.name: option for option in self.options(param)} self._index[key] = found return found
[docs] def options(self, param: Param) -> tuple[Option, ...]: found = self._entry(param) return found.options if found is not None else ()
[docs] def unit_of(self, param: Param) -> tuple[str | None, float]: """The unit to read this parameter's numbers in, and their scale to it. The catalogue's own declaration wins, in which case the numbers are already in that unit and the scale is 1. The `Param` table is the fallback, for a parameter stated without a unit: a temperature coefficient is reported in ppm and read as 1e-6 per kelvin. """ found = self._entry(param) if found is not None and found.unit is not None and param.unit is not None: return found.unit, 1.0 return param.unit, param.scale
[docs] def value(self, param: Param, option: Option) -> Scalar | None: """An option as something a predicate can be tested against.""" unit, scale = self.unit_of(param) if unit is None: return option.name magnitude = option.magnitude(param.span) if magnitude is None: return None return registry.Quantity(magnitude * scale, unit)
[docs] def number(self, param: Param, raw: float) -> Scalar | None: """A number the catalogue reported for this parameter, as a value.""" unit, scale = self.unit_of(param) if unit is None: return None return registry.Quantity(raw * scale, unit)
def _entry(self, param: Param) -> ParamOptions | None: name = self.spelling(param) return self.params.get(name) if name is not None else None
[docs] def measured(name: str) -> tuple[float, str] | None: """An option name read as a number and a unit the registry knows. None for a name that is not a single measurement, which is how a text parameter such as "Thick Film Resistor" and a two-ended range such as "-20%~+25%" stay out of unit calibration. """ found = MEASURED.match(name.strip()) if found is None: return None unit = pint_unit(found.group(2)) if unit is None: return None return float(found.group(1)), unit
[docs] def derive_unit(options: Sequence[Option], span: bool) -> str | None: """The unit a parameter's numbers are stated in, read off its own options. For a source that does not declare it. Each option carries both a name with a unit in it and a normalized number, and the ratio between them *is* the unit: 0.08pF against 0.08 says the numbers are picofarads, and 0.1nH against 0.0001 says they are microhenries. Derived rather than mapped from a unit-template id because it needs no table to be kept in step with the catalogue, and rather than read off the response's unit list because JLCPCB's is the units its UI offers to display in, whose first entry is the smallest rather than the one in use. The commonest answer across the options wins, so one malformed name cannot decide it. None when no option could be read, which leaves the `Param` table's own fallback in charge. """ votes: dict[str, int] = {} for option in options: magnitude = option.magnitude(span) if not magnitude: continue read = measured(option.name) if read is None: continue number, unit = read if not number: continue try: ratio = registry.Quantity(number / magnitude, unit).to_compact() except (ValueError, TypeError): # pragma: no cover - pint is tolerant continue # The ratio should be a round 1 of some unit; anything else means the # name and the number are not talking about the same quantity. if abs(float(ratio.magnitude) - 1.0) > 1e-6: continue symbol = str(ratio.units) votes[symbol] = votes.get(symbol, 0) + 1 if not votes: return None return max(votes, key=lambda symbol: votes[symbol])
def _encode(table: OptionTable, key: str) -> str: return json.dumps( { "v": CACHE_VERSION, "fetched": time.time(), "catalogs": key, "packages": list(table.packages), "brands": dict(table.brands), "params": { name: { "unit": entry.unit, "options": [[o.name, o.start, o.end] for o in entry.options], } for name, entry in table.params.items() }, } ) def _decode(text: str) -> OptionTable | None: """An OptionTable from a cache file, or None if it cannot be used. A cache file is on disk where a person can edit it and where a half-written one can be left by an interrupted run, so anything unexpected means refetch rather than fail. """ try: data = json.loads(text) except ValueError: return None if not isinstance(data, dict) or data.get("v") != CACHE_VERSION: return None try: return OptionTable( packages=tuple(str(p) for p in data["packages"]), brands={str(k): str(v) for k, v in data["brands"].items()}, params={ str(name): ParamOptions( options=tuple( Option(str(o[0]), numeric(o[1]), numeric(o[2])) for o in entry["options"] ), unit=entry["unit"], ) for name, entry in data["params"].items() }, ) except (KeyError, TypeError, IndexError): return None
[docs] class OptionCache: """Option tables, held in memory and optionally on disk. Keyed by a string the caller chooses, which is how one cache serves a source whose catalogues are numbered however that source numbers them. The fetch is passed per lookup rather than held, so the cache knows nothing about which API it is standing in front of. The disk copy lives in the project directory rather than a user-level cache, so a checkout carries its own and two projects cannot disagree about what a third wrote. It is an accelerator with no bearing on which part is selected, which is why the directory is not part of a provider's config. """ def __init__(self, directory: str | None): self.directory = Path(directory) if directory else None self._memory: dict[str, OptionTable] = {}
[docs] def get(self, key: str, fetch: Callable[[], OptionTable]) -> OptionTable: """The vocabulary for `key`, calling `fetch` if this is the first ask.""" cached = self._memory.get(key) if cached is not None: return cached path = self._path(key) if path is not None and path.is_file(): table = _decode(path.read_text(encoding="utf-8")) if table is not None: self._memory[key] = table return table table = fetch() self._memory[key] = table if path is not None: try: path.parent.mkdir(parents=True, exist_ok=True) path.write_text(_encode(table, key), encoding="utf-8") except OSError: # A read-only checkout still resolves; it just asks every run. pass return table
def _path(self, key: str) -> Path | None: if self.directory is None: return None return self.directory / f"params-{key}.json"
[docs] def centre(predicate: Predicate) -> float | None: """The value a predicate is about, for ordering options by nearness. Used only to decide which options to send when a predicate matches more of them than a request should carry. It has no bearing on what matches. """ def magnitude(value: object) -> float | None: if is_quantity(value): return float(value.to_base_units().magnitude) if isinstance(value, bool): return None if isinstance(value, (int, float)): return float(value) return None if isinstance(predicate, Exactly): return magnitude(predicate.value) if isinstance(predicate, Tolerance): return magnitude(predicate.typ) if isinstance(predicate, Range): low, high = magnitude(predicate.min), magnitude(predicate.max) if low is not None and high is not None: return (low + high) / 2 return low if low is not None else high if isinstance(predicate, OneOf): values = [m for m in (magnitude(v) for v in predicate.values) if m is not None] return sum(values) / len(values) if values else None return None
[docs] def names_for( table: OptionTable, param: Param, predicate: Predicate, key: str ) -> tuple[str, ...] | None: """The option names satisfying `predicate`, or None if the catalogue has none. None means the parameter is not in this catalogue's vocabulary at all, which the caller reports as unsupported. An empty tuple means the vocabulary was read and nothing in it satisfies the predicate, which is a plain no-match. """ options = table.options(param) if not options: return None matched: list[tuple[float, str]] = [] target = centre(predicate) for option in options: value = table.value(param, option) if value is None: continue if not satisfies(predicate, value, key): continue # Ordering is by base-unit magnitude, so it is comparable with the # predicate's centre however the catalogue chose to state the parameter. magnitude = None if is_quantity(value): magnitude = float(value.to_base_units().magnitude) distance = 0.0 if target is not None and magnitude is not None: distance = abs(magnitude - target) matched.append((distance, option.name)) if len(matched) > MAX_OPTIONS: matched.sort(key=lambda pair: pair[0]) matched = matched[:MAX_OPTIONS] return tuple(name for _, name in matched)
[docs] def matching_packages(table: OptionTable, predicate: Predicate) -> list[str]: """Packages in this vocabulary that satisfy a `case` filter. Not capped the way parameter options are. The packages in a category run to a few hundred names, which is a small request body, where a broad parameter range runs to thousands. """ return [p for p in table.packages if satisfies(predicate, p, "case")]
[docs] def matching_brands(table: OptionTable, predicate: Predicate) -> list[str]: """Manufacturer tokens in this vocabulary satisfying `predicate`.""" tokens = [ token for name, token in table.brands.items() if satisfies(predicate, name, "manufacturer") ] return tokens[:MAX_OPTIONS]
[docs] def span_magnitude(text: str) -> float | None: """The half width of a value stated as text, such as "+/-1%". Shared because neither source states a range parameter numerically on every row: LCSC leaves the numeric field null for one, JLCPCB has no numeric field at all, and both write the range out in the display text. """ found = [abs(float(n)) for n in NUMBERS.findall(text)] return max(found) if found else None