options module#

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.

class Option(name, start=None, end=None)[source]#

Bases: object

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.

Parameters:
name: str#
start: float | None = None#
end: float | None = None#
magnitude(span)[source]#

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.

Return type:

float | None

Parameters:

span (bool)

class ParamOptions(options, unit=None)[source]#

Bases: object

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.

Parameters:
options: tuple[Option, ...]#
unit: str | None = None#
class OptionTable(packages, brands, params, _index=dict())[source]#

Bases: object

The filter vocabulary of one category’s catalogues.

Parameters:
  • packages (tuple[str, ...]) – package codes the catalogues carry.

  • brands (Mapping[str, str]) – 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 (Mapping[str, ParamOptions]) – parameter name to its options and their unit.

  • _index (dict[str, dict[str, Option]])

packages: tuple[str, ...]#
brands: Mapping[str, str]#
params: Mapping[str, ParamOptions]#
spelling(param)[source]#

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.

Return type:

str | None

Parameters:

param (Param)

index(param)[source]#

This parameter’s options by name, built once per table.

Return type:

Mapping[str, Option]

Parameters:

param (Param)

options(param)[source]#
Return type:

tuple[Option, ...]

Parameters:

param (Param)

unit_of(param)[source]#

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.

Return type:

tuple[str | None, float]

Parameters:

param (Param)

value(param, option)[source]#

An option as something a predicate can be tested against.

Return type:

float | int | str | bool | PlainQuantity | None

Parameters:
number(param, raw)[source]#

A number the catalogue reported for this parameter, as a value.

Return type:

float | int | str | bool | PlainQuantity | None

Parameters:
measured(name)[source]#

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.

Return type:

tuple[float, str] | None

Parameters:

name (str)

derive_unit(options, span)[source]#

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.

Return type:

str | None

Parameters:
class OptionCache(directory)[source]#

Bases: object

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.

Parameters:

directory (str | None)

get(key, fetch)[source]#

The vocabulary for key, calling fetch if this is the first ask.

Return type:

OptionTable

Parameters:
centre(predicate)[source]#

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.

Return type:

float | None

Parameters:

predicate (Predicate)

names_for(table, param, predicate, key)[source]#

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.

Return type:

tuple[str, ...] | None

Parameters:
matching_packages(table, predicate)[source]#

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 type:

list[str]

Parameters:
matching_brands(table, predicate)[source]#

Manufacturer tokens in this vocabulary satisfying predicate.

Return type:

list[str]

Parameters:
span_magnitude(text)[source]#

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.

Return type:

float | None

Parameters:

text (str)