stratified_packager.processing.workers

Background zip publishing: the only work that leaves the algorithm thread (SPEC §8.4/§10).

This module MUST NOT import ``qgis`` — zip jobs run on plain ThreadPoolExecutor threads and touch only zipfile and the standard library. An AST test enforces this. GeoPackage writing now happens on the algorithm thread (see building); the algorithm hands each finished bundle here so the next bundle’s GeoPackages can be built while this one is compressed and published.

A job returns its outcome (the algorithm collects it from the future); cancellation propagates via a threading.Event the algorithm sets when the feedback is canceled. Jobs never raise — failures and cancellations are returned as outcomes and the partial archive is removed (best-effort policy, SPEC §17).

Functions

run_prefetch(source, destination, cancel)	Copy one §11 warm-cache file to its build location on a background thread; never raises.
run_zip(job, cancel)	Assemble and publish one zip on a background thread (SPEC §10); never raises.

Classes

ZipJob(zip_rel, members, build_path, final_path)	One zip assembly + publish task (SPEC §10); plain data built on the algorithm thread.
ZipOutcome(zip_rel, ok[, final_path, error])	The result of one run_zip() call.

class stratified_packager.processing.workers.ZipJob(zip_rel, members, build_path, final_path, compression_level=6, write_checksum=False)

One zip assembly + publish task (SPEC §10); plain data built on the algorithm thread.

Parameters:

• zip_rel (str)

• members (tuple[tuple[Path, str], ...])

• build_path (Path)

• final_path (Path)

• compression_level (int)

• write_checksum (bool)

__init__(zip_rel, members, build_path, final_path, compression_level=6, write_checksum=False)

Parameters:

• zip_rel (str)

• members (tuple[tuple[Path, str], ...])

• build_path (Path)

• final_path (Path)

• compression_level (int)

• write_checksum (bool)

build_path: Path

Where the zip is assembled (run-scoped temp or the output directory).

compression_level: int = 6

Deflate level; 0 stores uncompressed.

final_path: Path

The published destination (.part + atomic rename).

members: tuple[tuple[Path, str], ...]

(source file, arcname) zip members.

write_checksum: bool = False

Whether to write a .sha256 sidecar next to the published zip.

zip_rel: str

The zip’s output-relative path without the .zip extension (the outcome key).

class stratified_packager.processing.workers.ZipOutcome(zip_rel, ok, final_path='', error='')

The result of one run_zip() call.

Parameters:

• zip_rel (str)

• ok (bool)

• final_path (str)

• error (str)

__init__(zip_rel, ok, final_path='', error='')

Parameters:

• zip_rel (str)

• ok (bool)

• final_path (str)

• error (str)

error: str = ''

Failure detail (canceled when aborted by cancellation).

final_path: str = ''

The published path (empty on failure).

ok: bool

Whether the zip was published.

zip_rel: str

The zip’s output-relative path (matches ZipJob.zip_rel).

stratified_packager.processing.workers._check_cancel(cancel, token)

Raise when the run was canceled.

Parameters:

• cancel (Event) – The run’s cancellation event.

• token (str) – Identifier carried in the exception.

Raises:

OperationAbortedError – If cancellation was requested.

Return type:

None

stratified_packager.processing.workers.run_prefetch(source, destination, cancel)

Copy one §11 warm-cache file to its build location on a background thread; never raises.

Submitted before Phase A on WARM_START_MODE=use runs, so a (possibly remote) cache file is already sitting at the stratum’s build path when its seeded build starts — the build then seeds in place instead of copying on the critical path. Copied chunked via publish_atomic() (.part + rename, cancel polled between chunks), so a half-copied file is never mistaken for a seed and a canceled run does not wait out a large remote copy. Best-effort: False sends the caller back to the seed-time copy from the original cache file.

Parameters:

• source (Path) – The warm-cache gpkg.

• destination (Path) – The stratum’s build gpkg path.

• cancel (Event) – The run’s cancellation event (set by the algorithm thread).

Return type:

bool

Returns:

Whether the copy completed.

stratified_packager.processing.workers.run_zip(job, cancel)

Assemble and publish one zip on a background thread (SPEC §10); never raises.

Build at ZipJob.build_path, publish to ZipJob.final_path via .part + atomic rename, then write the optional checksum sidecar. The build copy is removed whatever the outcome — after publishing on success (the build dir shrinks as bundles publish instead of holding every archive until run end), best-effort on failure or cancellation.

Parameters:

• job (ZipJob) – The zip job.

• cancel (Event) – The run’s cancellation event (set by the algorithm thread).

Return type:

ZipOutcome

Returns:

The publish outcome.