Source code for jitxlib.gerber.format.pack

"""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.
"""

from __future__ import annotations

import json
import logging
import zipfile
from dataclasses import dataclass
from pathlib import Path
from typing import Sequence

from .model import FileFunction, FileKind, GenerationSoftware
from .naming import ARCHIVE_EXT

log = logging.getLogger(__name__)

ZIP_TIMESTAMP = (1980, 1, 1, 0, 0, 0)
"""Archive entries get a fixed timestamp so the zip is byte-stable."""


[docs] class OutputError(Exception): """The output set cannot be written safely."""
[docs] @dataclass(frozen=True) class OutputFile: """One resolved file: its final name, what it is, and its text. Args: name: a plain filename, already resolved by the naming layer. function: what the file is, which is what the overwrite guard keys on. """ name: str function: FileFunction content: str
[docs] def is_archive(output: Path) -> bool: """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 output.suffix.lower() == ARCHIVE_EXT
[docs] def write_set( files: Sequence[OutputFile], output: Path, software: GenerationSoftware, *, overwrite: bool = False, ) -> list[Path]: """Write the file set to `output` and return the paths written. Args: output: 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: the identity the guard looks for when deciding whether an existing file is a previous export of ours. 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. """ names = [f.name for f in files] _check_names(names) if is_archive(output): return [_write_archive(files, output, software, overwrite=overwrite)] targets = {name: output / name for name in names} kinds = {f.name: f.function.kind for f in files} _guard(targets, kinds, software, overwrite=overwrite) _warn_foreign(output, set(names), software) output.mkdir(parents=True, exist_ok=True) written: list[Path] = [] for file in files: path = targets[file.name] path.write_text(file.content, encoding="ascii", newline="\n") written.append(path) return written
def _write_archive( files: Sequence[OutputFile], output: Path, software: GenerationSoftware, *, overwrite: bool, ) -> Path: """Write the set as one zip and nothing else. The archive's contents are not inspected before it is replaced, unlike a file in a directory output. The reason the directory guard sniffs at all is that the names there are *generated*: the user names a directory and the exporter decides what lands in it, so a collision with a stranger's file is something neither of them chose. An archive path is the opposite - the user named this exact file as the destination - so `--overwrite` on it is permission to replace that file, and there is nothing left to infer. Only the parent directory is created, and the files inside the archive never touch the filesystem, so a refusal leaves nothing behind. """ if output.is_symlink(): raise OutputError( f"{output} is a symlink; refusing to write through it. Remove it " f"or choose another output path." ) if output.is_dir(): raise OutputError(f"{output} is a directory, not an archive to replace") if output.exists() and not overwrite: raise OutputError( f"{output} already exists; pass overwrite to replace a previous export" ) output.parent.mkdir(parents=True, exist_ok=True) return _write_zip(output, files) def _check_names(names: Sequence[str]) -> None: """Names must be plain filenames and must not collide. The comparison is case-insensitive: two names differing only in case are one file on Windows and macOS, and inside a zip extracted on either. Collision is a bug in a naming scheme, and the right time to see it is here rather than as a file silently missing from a customer's upload. """ for name in names: if not name or name in (".", "..") or "/" in name or "\\" in name: raise OutputError(f"not a plain filename: {name!r}") seen: dict[str, str] = {} for name in names: key = name.lower() if key in seen: raise OutputError( f"two files resolve to the same name: {seen[key]!r} and {name!r}" ) seen[key] = name def _guard( targets: dict[str, Path], kinds: dict[str, FileKind], software: GenerationSoftware, *, overwrite: bool, ) -> None: for name, path in targets.items(): if path.is_symlink(): raise OutputError( f"{path} is a symlink; refusing to write through it. Remove it " f"or choose another output directory." ) if not path.exists(): continue if path.is_dir(): raise OutputError(f"{path} is a directory, not a file this export writes") if not overwrite: raise OutputError( f"{path} already exists; pass overwrite to replace a previous export" ) if not recognize(path, kinds[name], software): raise OutputError( f"{path} exists and does not look like output of " f"{software.application}; refusing to overwrite it" )
[docs] def recognize(path: Path, kind: FileKind, software: GenerationSoftware) -> bool: """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. Args: kind: the file function's kind. """ try: text = path.read_text(encoding="utf-8", errors="strict") except (OSError, UnicodeDecodeError): return False match kind: case FileKind.JOB: return _is_our_gbrjob(text, software) case FileKind.DRILL: # a drill file is XNC or Gerber depending on the format it was # written in, and the format is not in the kind. Sniffing both is # not a widening that matters: each marker still names our own # GenerationSoftware, so the thing the guard exists to prevent - # overwriting a stranger's export - is unaffected. return _is_our_xnc(text, software) or _is_our_gerber(text, software) case _: return _is_our_gerber(text, software)
def _is_our_gerber(text: str, software: GenerationSoftware) -> bool: marker = f"%TF.GenerationSoftware,{software.vendor},{software.application}," return marker in text and text.rstrip("\r\n").endswith("M02*") def _is_our_xnc(text: str, software: GenerationSoftware) -> bool: # not "starts with M48": comments are allowed before it and our own # writer may lead with one marker = f"; #@! TF.GenerationSoftware,{software.vendor},{software.application}," return marker in text and text.rstrip("\r\n").endswith("M30") def _is_our_gbrjob(text: str, software: GenerationSoftware) -> bool: try: content = json.loads(text) except (json.JSONDecodeError, ValueError): return False if not isinstance(content, dict): return False generator = content.get("Header", {}) generator = ( generator.get("GenerationSoftware", {}) if isinstance(generator, dict) else {} ) if not isinstance(generator, dict): return False return ( generator.get("Vendor") == software.vendor and generator.get("Application") == software.application ) def _is_our_zip(path: Path, software: GenerationSoftware) -> bool: """A zip is ours when every entry in it is.""" try: with zipfile.ZipFile(path) as archive: entries = archive.namelist() if not entries: return False for entry in entries: text = archive.read(entry).decode("utf-8", errors="strict") if not _any_kind(text, software): return False except (OSError, zipfile.BadZipFile, UnicodeDecodeError): return False return True def _any_kind(text: str, software: GenerationSoftware) -> bool: return ( _is_our_gerber(text, software) or _is_our_xnc(text, software) or _is_our_gbrjob(text, software) ) def _warn_foreign( directory: Path, names: set[str], software: GenerationSoftware ) -> None: """Warn about a previous export under a different naming scheme. Files we cannot prove we wrote are never deleted, which is the whole point of the guard - but it does mean a directory can end up holding two overlapping data sets, which is its own way to ship the wrong files to a fab. The decision is the user's. """ if not directory.is_dir(): return stale = sorted( entry.name for entry in directory.iterdir() if entry.is_file() and not entry.is_symlink() and entry.name not in names and looks_like_ours(entry, software) ) if stale: log.warning( "%s holds output from an earlier export that this run does not " "replace: %s. Two overlapping data sets in one directory is a way " "to send a fab the wrong files.", directory, ", ".join(stale), )
[docs] def looks_like_ours(path: Path, software: GenerationSoftware) -> bool: """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. """ try: text = path.read_text(encoding="utf-8", errors="strict") except (OSError, UnicodeDecodeError): return _is_our_zip(path, software) return _any_kind(text, software)
def _write_zip(path: Path, files: Sequence[OutputFile]) -> Path: with zipfile.ZipFile(path, "w", zipfile.ZIP_DEFLATED) as archive: for file in files: info = zipfile.ZipInfo(file.name, date_time=ZIP_TIMESTAMP) info.compress_type = zipfile.ZIP_DEFLATED info.external_attr = 0o644 << 16 archive.writestr(info, file.content) return path