Source code for jitxlib.jlcpcb.export.naming

"""JLCPCB's recommended gerber filenames, as a `jitxlib-gerber` strategy.

Registered in the `jitxlib.gerber.naming` entry-point group, so
`jitx design export gerber --names jlcpcb` picks it up with nothing to patch
in that package. The table is from JLCPCB's "Suggested Naming Patterns" and
their gerber preparation article.
"""

from __future__ import annotations

from collections.abc import Sequence

from jitxlib.gerber.format.naming import FileNaming, register
from jitxlib.gerber.format.model import (
    Copper,
    Drill,
    DrillFormat,
    FileFunction,
    FileKind,
    HoleType,
    Legend,
    Side,
    Soldermask,
)

XLN_EXT = ".XLN"
"""JLCPCB's preferred drill extension. `.TXT` is understood but multiple
`.TXT` files raise a merge warning on their side."""


[docs] @register("jlcpcb") class JLCPCBNaming(FileNaming): """Protel-style names, which JLCPCB recommends over descriptive ones. Defers (returns None) for paste, component and job files: those conventions predate X3 entirely and inventing extensions for them would be worse than falling back to `descriptive`. """
[docs] def name( self, function: FileFunction, stem: str, file_set: Sequence[FileFunction] ) -> str | None: match function.kind: case FileKind.COPPER: return stem + _copper(function) case FileKind.SOLDERMASK: return stem + _soldermask(function) case FileKind.LEGEND: return stem + _legend(function) case FileKind.PROFILE: # Their gerber article: put only one outline layer in the # file and delete the others. `.GM1` is also accepted. return stem + ".GKO" case FileKind.DRILL: return _drill(function, stem, file_set) case _: return None
def _copper(function: FileFunction) -> str: """`.GTL`, `.GBL`, or `.G<k>L` for an inner layer. Inner layers are numbered by absolute position with an `L` suffix, not by a count of inner layers. """ if not isinstance(function, Copper): # pragma: no cover - kind implies the type return ".GTL" match function.side: case Side.TOP: return ".GTL" case Side.BOTTOM: return ".GBL" case _: return f".G{function.index}L" def _soldermask(function: FileFunction) -> str: if not isinstance(function, Soldermask): # pragma: no cover return ".GTS" return ".GBS" if function.side == Side.BOTTOM else ".GTS" def _legend(function: FileFunction) -> str: if not isinstance(function, Legend): # pragma: no cover return ".GTO" return ".GBO" if function.side == Side.BOTTOM else ".GTO" def _drill( function: FileFunction, stem: str, file_set: Sequence[FileFunction] ) -> str | None: """`<stem>.XLN`, decorated only when the set holds more than one drill file. JLCPCB lists a single `boardname.XLN` while the format mandates separate plated and non-plated files, so the two cannot both take the bare name. Decorating unconditionally would leave every design with a name their documentation does not show, so the whole file set decides: one drill file keeps the published name, several are distinguished. """ if not isinstance(function, Drill): # pragma: no cover - kind implies the type return None if function.format is not DrillFormat.XNC: # `.XLN` names an NC drill file. A Gerber-format drill file is a # Gerber file, and calling it `.XLN` would misdescribe it, so defer # rather than mislabel. The relay selects XNC, so this only arises # when someone picks this scheme with a different drill format. return None if _drill_count(file_set) < 2: return stem + XLN_EXT match function.hole: case HoleType.PTH: return f"{stem}-PTH{XLN_EXT}" case HoleType.NPTH: return f"{stem}-NPTH{XLN_EXT}" case _: # Blind and buried spans have no published convention at all. tail = "" if function.plated else "-NP" return f"{stem}-L{function.first}-L{function.last}{tail}{XLN_EXT}" def _drill_count(file_set: Sequence[FileFunction]) -> int: return sum(1 for f in file_set if f.kind == FileKind.DRILL)