Source code for jitxlib.parts.providers.geometry

"""
Geometry for the shipped providers
==================================

How `CsvParts` and `IdealPassives` build a two-pin passive from a case code:
:py:func:`passive_geometry` returns the landpattern and symbol instance for one,
and a `materialize` assigns them to the component.

Not core API, and not a contract either provider imposes on a third. The core
neither declares nor inspects geometry, so another provider is free to build its
own however it likes; this is the shortest thing that works for standard passives.

A case code the landpattern table does not know cannot be built, so a provider
checks :py:func:`known_case` while resolving and declines such a part there,
rather than letting `materialize` fail on it later.

A polarized part needs `PolarizedSMT` and `PolarizedCapacitorSymbol` together, so
that the `.a`/`.c` pads and the symbol agree.
"""

from __future__ import annotations

from typing import Any

from jitx import Symbol
from jitxlib.landpatterns.twopin.SMT_table import SMT_CHIP_DEFS
from jitxlib.landpatterns.twopin.smt import SMT, PolarizedSMT
from jitxlib.symbols.capacitor.capacitor import (
    CapacitorSymbol,
    PolarizedCapacitorSymbol,
)
from jitxlib.symbols.inductor.inductor import InductorSymbol
from jitxlib.symbols.resistor.resistor import ResistorSymbol

SYMBOL_FOR: dict[str, type[Symbol]] = {
    "resistor": ResistorSymbol,
    "capacitor": CapacitorSymbol,
    "inductor": InductorSymbol,
}




def known_case(case: str) -> bool:
    """Whether :py:func:`passive_geometry` can build a landpattern for `case`."""
    return case in SMT_CHIP_DEFS





def passive_geometry(
    category: str, case: str, polarized: bool = False
) -> tuple[Any, Any]:
    """A landpattern and symbol instance for a two-pin passive in `case`.

    Raises `KeyError` for a case code :py:func:`known_case` rejects, or a category
    with no symbol generator.
    """

    if not known_case(case):
        raise KeyError(f"no landpattern for case {case!r}")
    if polarized:
        landpattern = PolarizedSMT
    else:
        landpattern = SMT

    symbol = SYMBOL_FOR.get(category)
    if polarized and symbol is CapacitorSymbol:
        symbol = PolarizedCapacitorSymbol

    if symbol is None:
        raise KeyError(
            f"no symbol generator for category {category!r}; a provider serving "
            f"it has to supply its own geometry"
        )
    return landpattern(case), symbol()