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