pack module#

Write a resolved file set to a directory, optionally also as a zip.

The output directory is the user’s directory, not one this package created, so nothing here ever removes a directory. –overwrite is permission to replace a previous export, not permission to delete arbitrary files that happen to collide with a generated name, so every file removed has to say we wrote it. Recognition is keyed by the file function about to be written there rather than by extension, because a naming scheme may produce .GTL, .TXT or no extension at all.

Because naming is deterministic, the exact set of paths a run will write is known before anything is written, and that set is the only thing the guard ever touches. A path that fails its check aborts the whole export before a single file is written: a partially overwritten fabrication data set that still looks complete is worse than no export at all.

ZIP_TIMESTAMP = (1980, 1, 1, 0, 0, 0)#

Archive entries get a fixed timestamp so the zip is byte-stable.

exception OutputError[source]#

Bases: Exception

The output set cannot be written safely.

class OutputFile(name, function, content)[source]#

Bases: object

One resolved file: its final name, what it is, and its text.

Parameters:
  • name (str) – a plain filename, already resolved by the naming layer.

  • function (Copper | Soldermask | Legend | Paste | Profile | Drill | Component | Job) – what the file is, which is what the overwrite guard keys on.

  • content (str)

name: str#
function: Copper | Soldermask | Legend | Paste | Profile | Drill | Component | Job#
content: str#
is_archive(output)[source]#

Whether an output path asks for a zip rather than a directory.

The suffix is the whole switch. An output path is a destination the user named, so board.zip says what they want as plainly as a flag would and cannot disagree with one.

Return type:

bool

Parameters:

output (Path)

write_set(files, output, software, *, overwrite=False)[source]#

Write the file set to output and return the paths written.

Parameters:
  • output (Path) – a directory to write the files into, or a path ending in .zip, which writes exactly that archive with the files at its root - the layout fab upload forms expect - and nothing beside it. The archive is built from the content in memory, so it never contains itself.

  • software (GenerationSoftware) – the identity the guard looks for when deciding whether an existing file is a previous export of ours.

  • files (Sequence[OutputFile])

  • overwrite (bool)

Return type:

list[Path]

Returns:

One path per file for a directory, or the single archive path.

Raises:

OutputError – a name is not a plain filename, two files resolve to one name, a target exists without overwrite, or a target exists that does not look like our own output.

recognize(path, kind, software)[source]#

Whether an existing file looks like output this package wrote.

A cheap structural sniff, keyed by what the file is rather than by its extension. The GenerationSoftware test is the point rather than decoration: a sniff for “any valid X2 Gerber” passes a mature exporter’s output sitting in the same directory, so overwriting would delete someone else’s export believing it was replacing ours.

This is for the generated names of a directory output only. An archive output is a file the user named outright and is replaced without a sniff.

Parameters:
Return type:

bool

looks_like_ours(path, software)[source]#

Whether a file we were not about to write is a previous export.

Unlike recognize this has no file function to key on - the file is not in the set - so it tries every kind. It drives a warning, never a removal.

Return type:

bool

Parameters: