Source code for jitxlib.jlcpcb.parts.catalog

"""
What the catalogue calls things
===============================

The static half of the translation, shared by both sources in this package:
which parameter name carries a JITX query key, and what unit the API states that
parameter's numbers in.

LCSC and JLCPCB are two front ends over one catalogue, so this table serves
both. The parameter names are the same on either side, with the two exceptions
`aliases` exists for. What is *not* shared is how a catalogue is identified - an
LCSC `wmCatalogId` against a JLCPCB (first, second) sort pair - so each source
module owns its own id table, keyed by `Category.key`.

Numbers come back in the parameter's own standard unit rather than in an SI base
unit: a capacitance in pF, an inductance in uH, a resistance in ohms. The
response declares which in its unit list, and that declaration is what the
values are read with; `Param.unit` and `Param.scale` are the fallback for a
parameter stated without one, which is how a temperature coefficient in ppm is
handled.

The parameter tables are not exhaustive. They name the parameters a JITX passive
query can ask about; a catalogue reports plenty more, and those reach the
component through the payload rather than being queryable.
"""

from __future__ import annotations

from dataclasses import dataclass
from typing import Any

from jitx.units import PlainQuantity, registry
from jitxlib.landpatterns.twopin.SMT_table import SMT_CHIP_DEFS


[docs] @dataclass(frozen=True) class Param: """One queryable catalogue parameter. Args: name: the parameter name as the filter vocabulary spells it. This is the spelling that goes into a request. unit: unit to read the numbers in when the API declares none, or None for a text parameter. scale: factor from the API's number to `unit`, on that same fallback path. span: whether the option is a symmetric range, such as a tolerance, in which case its magnitude is the half width rather than an endpoint. aliases: other spellings the same parameter goes by, tried when reading a row. Needed because the two sources disagree in two places, and because JLCPCB itself spells saturation current with an extra space in a row than in its own vocabulary. """ name: str unit: str | None = None scale: float = 1.0 span: bool = False aliases: tuple[str, ...] = () @property def spellings(self) -> tuple[str, ...]: """Every name this parameter answers to, canonical one first.""" return (self.name, *self.aliases)
[docs] @dataclass(frozen=True) class Category: """How one JITX category maps onto the catalogue's vocabulary. Args: key: this category's name in a source's catalogue id table. Distinct from `name` because polarized and ceramic capacitors are one JITX category served by two different sets of catalogues. name: the JITX category these catalogues serve. params: JITX query key to the parameter carrying it. polarized: whether parts from these catalogues are polarized. """ key: str name: str params: dict[str, Param] polarized: bool = False
TOLERANCE = Param("Tolerance", "percent", span=True) RESISTOR = Category( key="resistor", name="resistor", params={ "resistance": Param("Resistance", "ohm"), "tolerance": TOLERANCE, "max_power": Param("Power(Watts)", "W"), # JLCPCB spells this one differently on a row, and does not aggregate it # for chip resistors at all, so it is readable there but not filterable. "rated_voltage_dc": Param( "Voltage Rating", "V", aliases=("Voltage-Supply(Max)",) ), "tcr": Param("Temperature Coefficient", "1/kelvin", scale=1e-6, span=True), "composition": Param("Type"), }, ) CAPACITOR = Category( key="capacitor", name="capacitor", params={ "capacitance": Param("Capacitance", "F"), "tolerance": TOLERANCE, "rated_voltage_dc": Param("Voltage Rating", "V"), "temperature_coefficient_code": Param("Temperature Coefficient"), }, ) POLARIZED_CAPACITOR = Category( key="polarized_capacitor", name="capacitor", params={ "capacitance": Param("Capacitance", "F"), "tolerance": TOLERANCE, "rated_voltage_dc": Param("Voltage Rating", "V"), "esr": Param("Equivalent Series Resistance(ESR)", "ohm"), }, polarized=True, ) INDUCTOR = Category( key="inductor", name="inductor", params={ "inductance": Param("Inductance", "H"), "tolerance": TOLERANCE, "max_current": Param("Current Rating", "A"), # The space before the bracket is JLCPCB's row spelling of its own # vocabulary's name. Both are real; neither is a typo here. "saturation_current": Param( "Current - Saturation(Isat)", "A", aliases=("Current - Saturation (Isat)",) ), "dc_resistance": Param("DC Resistance(DCR)", "ohm"), "type": Param("Type"), }, ) # By `Category.key`, which is what a source's id table is keyed by. CATALOG: dict[str, Category] = { category.key: category for category in (RESISTOR, CAPACITOR, POLARIZED_CAPACITOR, INDUCTOR) } # By JITX category name, for saying what is served and what is not. CATEGORIES: dict[str, Category] = { "resistor": RESISTOR, "capacitor": CAPACITOR, "inductor": INDUCTOR, } # Keys every category answers, handled outside the parameter tables. IDENTITY_KEYS = frozenset({"mpn", "manufacturer", "category"}) # Not `mounting`: neither catalogue search takes it, and a package is not # enough to decide it. STRUCTURAL_KEYS = frozenset({"case", "polarized", "lcsc"})
[docs] def category_for(name: str, polarized: bool) -> Category | None: """The vocabulary for a JITX category, or None if unserved.""" if name == "capacitor": return POLARIZED_CAPACITOR if polarized else CAPACITOR return CATEGORIES.get(name)
# The catalogue's unit symbols mapped onto names the unit registry knows. An SI # prefix in front of one of these is carried over, so "mohm" and "uH" fall out # of the base symbols rather than being listed. UNIT_SYMBOLS: dict[str, str] = { "Ω": "ohm", "F": "F", "H": "H", "V": "V", "A": "A", "W": "W", "Hz": "Hz", "%": "percent", "‰": "permille", } SI_PREFIXES = frozenset("fpnumkMG")
[docs] def pint_unit(symbol: str) -> str | None: """A unit the registry understands, from the catalogue's spelling of one. None when the symbol is not a unit this package recognizes, which is how a parameter whose values are text rather than measurements stays text. """ symbol = symbol.strip() if symbol in UNIT_SYMBOLS: return UNIT_SYMBOLS[symbol] if len(symbol) > 1 and symbol[0] in SI_PREFIXES and symbol[1:] in UNIT_SYMBOLS: return symbol[0] + UNIT_SYMBOLS[symbol[1:]] return None
[docs] def quantity(magnitude: float, unit: str) -> PlainQuantity: """A quantity in engineering notation, as it should read on a schematic. A raw base-unit number is unreadable on a drawing: 1e-07 F is not what anyone calls that part. `to_compact` picks the prefix, and the rounding is because the rescale is a float division that lands on 99.99999999999999 nanofarad without it. """ compact = registry.Quantity(magnitude, unit).to_compact() return registry.Quantity(round(float(compact.magnitude), 9), compact.units)
[docs] def has_generator(case: str) -> bool: """Whether `passive_geometry` can build a landpattern for this package. A package it cannot build gets the catalogue's own footprint instead. """ # The table `SMT(case)` looks the case up in, so this cannot disagree with # what the generator accepts. return case.strip() in SMT_CHIP_DEFS
[docs] def numeric(value: Any) -> float | None: """A float from whatever the API put in a numeric field, or None.""" if value is None or isinstance(value, bool): return None try: return float(value) except (TypeError, ValueError): return None