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:
objectOne 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.
- class ParamOptions(options, unit=None)[source]#
Bases:
objectOne 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.
- class OptionTable(packages, brands, params, _index=dict())[source]#
Bases:
objectThe 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.
- 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.
- 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.
- 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.
- 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.
- class OptionCache(directory)[source]#
Bases:
objectOption 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:
- Parameters:
key (str)
fetch (Callable[[], OptionTable])
- 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.
- 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.
- 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:
- Parameters:
table (OptionTable)
predicate (Predicate)
- matching_brands(table, predicate)[source]#
Manufacturer tokens in this vocabulary satisfying predicate.
- Return type:
- Parameters:
table (OptionTable)
predicate (Predicate)