Source code for jitxlib.jlcpcb.parts.chain

"""
The chain this package publishes
================================

`jitxlib-jlcpcb` publishes a parts chain, so a project that exports to JLCPCB
resolves its passives without configuring anything: a board being made by
JLCPCB is a board being assembled from LCSC's shelves, and asking a design to
say so twice is ceremony.

It resolves through `JLCPCBParts` rather than `LCSCParts`. The two read the same
catalogue, but only JLCPCB says which assembly library a part belongs to, and
that is what a board sent to their line is priced on. A default that could not
express the one thing this package exists to care about would be the wrong
default.

It is the lowest-precedence way a chain can be chosen, so naming one is always
enough to override it. That is how to reach for the LCSC source:

    [tool.jitx.parts]
    chain = ["lcsc"]

and it is also how to put an approved-parts list in front of the catalogue, or
to configure a provider itself, which this default cannot do: it takes
`JLCPCBParts()` as it comes.

    [tool.jitx.parts]
    chain = ["csv:parts/approved.csv", "jlcpcb"]

An empty `chain = []` is a legal way to say "no providers here", and it
overrides this the same way a populated one does. Precedence, highest first, is
a `with PartSource(...)` block, a `parts` attribute on the `Design`, the
project's own `chain`, then this; and a project that names its own chain never
evaluates this level at all.

One caveat, which is the price of publishing a chain rather than a provider.
The published-chain level allows exactly one publisher in an environment:
installing this package alongside another that publishes its own chain is a
hard error naming both, and the remedy is to name the chain in the project's
config. Projects that already name one are unaffected.
"""

from __future__ import annotations

from jitxlib.parts import PartSource

from .jlcpcb import JLCPCBParts


[docs] def chain() -> PartSource: """The default chain: JLCPCB, and nothing behind it. Nothing behind it on purpose. An `ideal` fallback would let a design elaborate at a value the catalogue does not stock, but it synthesizes a part with no manufacturer and no C-number, which is not something JLCPCB can assemble. On a board headed for their assembly line, a value nobody sells should be an error rather than a placeholder. `LCSCParts` is not behind it either, for the same reason a fallback chain is usually a mistake here: the two sources read one catalogue, so a part LCSC would find and JLCPCB would not is a part JLCPCB declined to classify, and silently taking it would lose the library information the default exists to provide. A project that wants LCSC should name it. """ return PartSource([JLCPCBParts()], label="jlcpcb")