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)