job module#

Assemble a complete Gerber data set from a captured design and write it.

The order here is fixed by §6.10 rather than by convenience: naming runs first, then the job file, then the writer. The job file’s Path values are the final resolved filenames, so if it re-derived a name instead of being handed the resolved map, “nothing outside naming.py builds a filename” would be false on the first day.

Within a copper file the emission order is fixed too: every filled surface, containment-ordered, then the traces and flashes. A clear region erases what was drawn before it, and nothing else can erase anything, so objects that come after every region are safe by construction.

JOB_FORMAT: dict[DrillFormat, str] = {DrillFormat.GERBER: 'Gerber', DrillFormat.XNC: 'XNC'}#

The gbrjob FileFormat value each drill format declares.

The job spec enumerates (Gerber|XNC|NC|SM|IPC356|Other); this maps the formats this exporter can write onto it.

DRILL_EMITTERS: dict[DrillFormat, Callable[[DrillFile, FileMeta], str]] = {DrillFormat.GERBER: <function emit_drill_gerber>, DrillFormat.XNC: <function emit_xnc>}#

How each drill format is serialized.

One format per data set, never both. Adding a format is a row here, a row in JOB_FORMAT, and a row in naming.DRILL_EXT - nothing about the CLI, the naming hook or the writer changes, which is the point of carrying the format on the file function rather than threading it through every call.

class GerberResult(root, archive, files)[source]#

Bases: object

What an export wrote.

Parameters:
  • root (Path) – the output path, whichever form it took - the directory the files were written into, or the archive itself.

  • archive (Path | None) – the zip, when the output was one, and root again.

  • files (Sequence[tuple[Copper | Soldermask | Legend | Paste | Profile | Drill | Component | Job, Path]]) – every file written, with what it is, so a caller assembling a manufacturing packet does not have to re-derive the set. For a directory these are paths on disk; for an archive they are the names the files carry inside it, and nothing is on disk but the archive.

root: Path#
archive: Path | None#
files: Sequence[tuple[Copper | Soldermask | Legend | Paste | Profile | Drill | Component | Job, Path]]#
class DataSet(gerbers, drills, job, meta)[source]#

Bases: object

The file set before it has names or a destination.

Parameters:
gerbers: list[GerberFile]#
drills: list[DrillFile]#
job: JobFile#
meta: FileMeta#
property functions: list[Copper | Soldermask | Legend | Paste | Profile | Drill | Component | Job]#
build(design, *, creation_date=None, drill_format=DrillFormat.GERBER, compat=Compat(bake_macro_rotation=False))[source]#

Build the complete file set for a captured design.

No file is written and no name is resolved here, which is what makes the whole pipeline testable without a directory.

Parameters:
  • drill_format (DrillFormat) – which format the drill files are written in. Exactly one, never both: a job file offering a CAM system the same span in two formats is a job file that invites drilling it twice.

  • compat (Compat) – output adjustments for readers that deviate from the spec.

  • design (RuntimeDesign)

  • creation_date (str | None)

Return type:

DataSet

export(design, *, output, naming_scheme='descriptive', overwrite=False, creation_date=None, drill_format=DrillFormat.GERBER, compat=Compat(bake_macro_rotation=False))[source]#

Build and write the complete data set for a captured design.

Return type:

GerberResult

Parameters:
write(data, design_name, *, output, naming_scheme='descriptive', overwrite=False)[source]#

Name, serialize and write a built data set.

Split from build so the whole write path - naming, the job file and the overwrite guard - is exercisable without a runtime, and so a caller that has already built a set can write it twice under two schemes.

Parameters:
  • output (Path) – a directory to write the files into, or a path ending in .zip, which writes exactly that archive and nothing beside it. A directory is the user’s directory, not one this package created, so nothing here ever removes a directory.

  • naming_scheme (str | FileNaming) – a registered scheme name or a strategy object. An object is accepted so a caller can pass a configured instance without a registry round trip.

  • data (DataSet)

  • design_name (str)

  • overwrite (bool)

Raises:

OutputError – a name collides, or a target exists that this export may not replace.

Return type:

GerberResult

surface_of(island)[source]#

One resolved island as a dark region with its holes as clear ones.

The holes inherit the island’s object attributes deliberately: the dictionary is still set when they are emitted, and the cleared area does belong to that net’s surface.

Return type:

Surface | None

Parameters:

island (Island)