stratified_packager.processing.algorithm

The Stratified Packager Processing algorithm: orchestration of Phases A/B/C (SPEC §8).

All user-facing messaging inside algorithm execution goes through the qgis.core.QgsProcessingFeedback instance supplied by the Processing framework — never the plugin logger (whose records do not reach the algorithm’s log panel or qgis_process output). Fatal failures raise qgis.core.QgsProcessingException, the framework’s sanctioned failure path; per-stratum failures are contained (best-effort policy, SPEC §17) and surface in one final exception listing the failed strata. Helpers invoked during execution take the feedback as an explicit parameter.

Build layout: every zip gets its own build root mirroring the zip’s internal layout (gpkgs at their gpkg_rel paths, data/ and resources/ beside them), so Qt’s relative-path storage produces portable ./… sources in embedded projects (SPEC §13) and zip assembly is a plain tree walk. The Phase-A→B/C records and the per-phase helpers live in the sibling material, dedup, virtual and reporting modules; this module orchestrates them.

Classes

StratifiedPackagerAlgorithm(*args, **kwargs)

stratified_packager:package — one zipped GeoPackage per stratum (SPEC §1).
class stratified_packager.processing.algorithm.StratifiedPackagerAlgorithm(*args, **kwargs)[source]

stratified_packager:package — one zipped GeoPackage per stratum (SPEC §1).

Parameters:
classmethod tr(sourceText, disambiguation=None, n=-1)[source]

Get the translation for a string using Qt translation API.

Parameters:
Return type:

str

Returns:

Translated version of the source text.

_apply_overwrite_mode(inputs, resolution, report_rows, feedback)[source]

Apply OVERWRITE_MODE to the bundle map (§10, §15).

Parameters:
Return type:

dict[str, tuple[StratumSpec, ...]]

Returns:

The surviving bundles.

Raises:

QgsProcessingException – In error mode when any target exists.

_build_and_zip(material, builds, warm_builds, workdir, pool, cancel, feedback)[source]

Build every stratum gpkg on this thread, zipping finished bundles in the background.

On WARM_START_MODE=update runs the §11 warm pass runs first: every stratum’s warm cache is written and atomically published before any deliverable is built, so an interrupted run still leaves a complete, reusable cache. The deliverables then seed from the fresh cache; a stratum whose cache write failed builds cold. On WARM_START_MODE=use runs a member whose §11 prefetch landed seeds in place — its cache already sits at the build path.

Bundles run in order and their strata in sequence (SPEC §8.4); a bundle’s zip is submitted once its members are written, so the next bundle builds while this one compresses. Cancellation propagates into the in-flight zip jobs.

Parameters:
Return type:

_BuildState

Returns:

The final build state.

_build_template(material, workdir, feedback)[source]

Write the §8.1.5 template gpkg once (non-warm-marked whole-export primaries).

Each covered stratum is then seeded by a plain copy of the template; only its partitioned layers (and the per-stratum styles) are written afterwards. The template also becomes the covered layers’ read source (§8.2): a warm-seeded stratum (§11) cannot take the template seed, so it writes these layers per stratum — from the local template copy, not the original source again.

Parameters:
Raises:

QgsProcessingException – If the template writer fails or a written template table cannot be opened back as the read source.

Return type:

None

_chain_hop_fields(material)[source]

Collect the fields every relation chain queries on each intermediate hop layer (§7.1).

The last hop of a chain is never queried — its far-side keys are the membership condition — so only the layers a chain passes through are collected. Each hop reads its own to_fields (matched against the incoming keys) and the next hop’s from_fields (collected as the outgoing keys).

Parameters:

material (_Material) – The run material (its preps carry the resolved plans).

Return type:

dict[str, tuple[set[str], set[tuple[str, ...]]]]

Returns:

Hop layer id -> (queried field names, distinct match field sets).

_clone(layer, feedback)[source]

Clone layer into a standalone read layer (its subset string rides along, §8.2).

A lazy virtual clone is loaded before the validity check (load_lazy_virtual()), both so its features can be read at all and so a query that fails surfaces here rather than as an empty table. A read source exposing no fields is the signature of a provider that never loaded its data, which no packaged layer does on purpose — it is warned about rather than silently written out empty.

Parameters:
Return type:

QgsVectorLayer

Returns:

An independent clone whose selection may be freely changed.

Raises:

QgsProcessingException – If the clone is invalid.

_collect_layer_name_expressions(layers)[source]

Snapshot and parse-validate the §4 layer_name expressions at run start.

Consulted only when an embedded project is built. A parse error is the fail-fast; the per-stratum evaluation in _project_plan() surfaces eval/NULL errors later.

Parameters:

layers (Sequence[QgsMapLayer]) – Every layer that may appear in an embedded project.

Return type:

dict[str, str]

Returns:

Layer id -> non-empty expression text.

Raises:

QgsProcessingException – If a layer’s expression fails to parse.

_collect_layers(parameters, context, project, feedback)[source]

Resolve LAYERS and classify the packaged layers by handling (§4 fixed-by-type).

Plugin layers are excluded with a warning — they are reported here, not returned.

Parameters:
Return type:

tuple[list[QgsVectorLayer], list[QgsMapLayer], list[QgsMapLayer]]

Returns:

(vector, payload (local raster/mesh/point-cloud), embedded-only (remote/annotation/live virtual/project-only)) layers.

Raises:

QgsProcessingException – If a layer’s exclude variable cannot be coerced to bool while resolving an empty LAYERS (§5 strict regime).

_discard_workdir(material, workdir, feedback)[source]

Release the run’s workdir-backed layer handles, then remove the build directory (§10).

The preps’ read layers sit over GeoPackages inside the workdir (staging copies, the whole-export template), as do the chain context’s staged hop copies (§8.2); while those layers are alive GDAL holds the files open and Windows refuses to delete them. Dropping the references (plus a GC pass for cycles) releases the handles so the removal can succeed. Residue surviving the retries — e.g. a handle a failed run’s traceback still pins — is reported and left behind (best-effort, §17).

Parameters:

  • material (_Material) – The run material; its layer-holding fields are cleared in place.

  • workdir (Path) – The run’s build directory.

  • feedback (QgsProcessingFeedback) – Execution feedback channel.

Return type:

None

_distinct_layers(layers, feedback)[source]

Drop repeated identities from a resolved LAYERS value, reporting the loss (§5).

A caller that identifies layers by data source rather than by id — a saved model, a script, qgis_process --LAYERS=<source> — cannot distinguish layers sharing one source (§12): mapLayerFromString() answers every such string with the same first match. The siblings are unrecoverable from the value alone, so name what collapsed instead of failing or guessing, and keep one entry per layer so the run does not write the survivor once per lost sibling.

Parameters:
Return type:

list[QgsMapLayer]

Returns:

The layers in input order, first occurrence of each id only.

_emit_run_report(parameters, context, report_rows, feedback)[source]

Write the run-level report (§9.1) into the REPORT feature sink.

The destination is whatever REPORT resolves to: a memory table (loaded into the project by the GUI) when no path is given, or a file otherwise. Always produced — on DRY_RUN too — independent of GENERATE_REPORT, which gates only the per-zip report.csv (§9.2). The sink’s columns are the RunReportRow fields.

Parameters:
Return type:

str

Returns:

The sink destination id (the memory layer id, or the written path).

Raises:

QgsProcessingException – If QGIS cannot create the sink or accept a row.

_excluded_fields(layer)[source]

Read the layer’s excluded_fields variable (§4).

Parameters:

layer (QgsVectorLayer) – The packaged layer.

Return type:

tuple[str, ...]

Returns:

The excluded field names.

Raises:

QgsProcessingException – If the variable is not a JSON list of strings.

_finalize_members(material, members, state, feedback)[source]

Build the embedded project of each successful member (§13, Phase C).

Two failure regimes (SPEC §4 vs §17): assembling the member’s plan evaluates the layer_name expressions — a §4-strict eval error/NULL fails the stratum (the member leaves the succeeded set and its gpkg is discarded). Once the plan exists, an embedded-project write failure is non-fatal degraded delivery (§17): the member’s data gpkg is intact and still ships — without the embedded project — and a warning is pushed. Genuine data failures are contained upstream in the worker pool, not here.

Parameters:
Return type:

None

_finish_dry_run(material, strata, report_rows, parameters, context, feedback)[source]

Conclude a dry run: report only, no packages (§9.1).

Parameters:
Return type:

StratifiedPackagerAlgorithmOutputDict

Returns:

The §3 outputs map (no zips).

_fold_result(state, result, feedback)[source]

Fold one stratum’s write outcome into the build state and the feedback (§9/§11).

Parameters:
Return type:

None

_fold_warm_result(state, result, feedback)[source]

Fold one §11 warm-pass outcome into the build state and the feedback.

Deliverable accounting (succeeded/failed/layer_results) is untouched: the deliverable pass re-reports every layer (warm-seeded ones as warm), and a failed cache write only costs that stratum its warm seed — it still builds and ships cold; the missing cache fails the run at the end. The matched fids do fold in: the warm-seeded deliverable reports none for those layers, so the §9.1 orphan union needs the warm pass’s.

Parameters:
Return type:

None

_fold_zip(state, outcome, feedback)[source]

Fold one bundle’s zip outcome into the build state and the feedback.

Parameters:
Return type:

None

_layer_write(prep, material, *, to_root='')[source]

Build one (primary) prep’s LayerWrite.

A dedup primary carries every group member’s plan — membership is their union — and every member’s style (the primary’s loads by default). to_root sets the per-stratum resources/ prefix used to rewrite the QML asset paths.

Parameters:

  • prep (_LayerPrep) – The (primary) layer prep.

  • material (_Material) – The run material.

  • to_root (str) – The stratum’s relative prefix back to its zip root.

Return type:

LayerWrite

Returns:

The layer write.

_layout_zip_roots(material, workdir)[source]

Create one zip-mirror build root per bundle and map every member’s build path (§10).

Needs only the bundle layout, so it runs before Phase A — the §11 warm prefetch can then copy cache files straight to their final build paths while Phase A works.

Parameters:

  • material (_Material) – The run material (bundles in, roots/paths out).

  • workdir (Path) – The run’s build directory.

Return type:

None

_make_workdir(inputs, feedback)[source]

Create the run-scoped build directory, sweeping stale leftovers first (§10).

Parameters:
Return type:

Path

Returns:

The build directory (under the Processing temp folder, or under the output directory when USE_TEMP_FOLDER is off).

_maybe_submit_zip(pool, state, material, zip_rel, members, workdir, cancel, feedback)[source]

Finalize a finished bundle (Phase C) and submit its zip to the background pool.

Embedded projects for the successful members, then the per-zip report, then the zip job. A bundle whose members all failed is recorded as a failed zip.

Parameters:
Return type:

None

_metadata_payload(layer, inputs)[source]

Serialize the layer’s QMD metadata (§8.1 step 4).

Parameters:
Return type:

str

Returns:

The QMD XML, or an empty string when metadata is excluded.

_open_local(gpkg_path, table, label)[source]

Open a staged GeoPackage table as a standalone read layer (§8.2).

Parameters:

  • gpkg_path (Path) – The staging GeoPackage.

  • table (str) – The table name.

  • label (str) – A human label for error messages.

Return type:

QgsVectorLayer

Returns:

The opened layer.

Raises:

QgsProcessingException – If the table cannot be opened.

_phase_a(material, strata, features_by_name, workdir, feedback)[source]

Analysis & staging: methods, staging copies, conditions, payloads, build roots.

Parameters:
Raises:

QgsProcessingException – Per §4/§7/§8.2 validation rules.

Return type:

None

_phases_b_c(material, strata, *, warm_strata, features_by_name, workdir, report_rows, parameters, context, pool, cancel, feedback)[source]

Build the stratum gpkgs sequentially, embed projects, zip and publish per bundle.

GeoPackage writing stays on this thread (only it may touch QGIS); the background pool zips each finished bundle while the next bundle’s GeoPackages are built (SPEC §8).

Parameters:

  • material (_Material) – The run material.

  • strata (Sequence[StratumSpec]) – The surviving strata (deliverables; OVERWRITE_MODE applied).

  • warm_strata (Sequence[StratumSpec]) – Every resolved stratum — the §11 update pass refreshes all caches, including strata whose deliverable was skip-existing filtered.

  • features_by_name (Mapping[str, QgsFeature]) – Stratum features keyed by sanitized name.

  • workdir (Path) – The run’s build directory.

  • report_rows (list[RunReportRow]) – Mutable run-report rows.

  • parameters (dict[str | None, Any]) – Raw parameter values (carry the REPORT destination).

  • context (QgsProcessingContext) – The processing context.

  • pool (ThreadPoolExecutor) – The run-scoped background pool.

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

  • feedback (QgsProcessingFeedback) – Execution feedback channel.

Return type:

StratifiedPackagerAlgorithmOutputDict

Returns:

The §3 outputs map.

Raises:

QgsProcessingException – On cancellation, or at the end when any stratum, zip, or warm-cache write failed (best-effort policy, §17).

_place_shared_payloads(material)[source]

Place each bundle’s shared data/ and resources/ trees into its zip root (§13/§14).

Hardlinked when the filesystem allows, copied otherwise, so embedded projects written beside the gpkgs resolve everything relatively. Runs at the end of Phase A (payloads and style assets are Phase-A products); the roots themselves are laid out earlier by _layout_zip_roots().

Parameters:

material (_Material) – The run material.

Return type:

None

_prepare_vector_layer(layer, table, plan, inputs, feedback)[source]

Build one vector layer’s Phase-A prep over a plain clone (§8.1).

The read source starts as a clone of layer (its subset string rides along; the user’s layer is never read for data, so its selection and subset stay untouched). Staging happens later, per dedup group, in _stage_preps() — after apply_dedup() has merged shared-source layers — so a group shares one staging copy instead of building one per member. Conditions are not materialized here; the per-stratum write computes them lazily against the read source.

Parameters:
Return type:

_LayerPrep

Returns:

The prep.

Raises:

QgsProcessingException – On a clone failure.

_project_plan(material, member, state)[source]

Assemble one member’s embedded-project plan (§13).

Parameters:
Return type:

StratumProjectPlan

Returns:

The plan.

_resolve_inputs(parameters, context, project, settings, feedback)[source]

Resolve every input through explicit value > variable > setting > builtin.

Parameters:
Return type:

_Inputs

Returns:

The typed inputs.

Raises:

QgsProcessingException – On unusable stored defaults or missing requirements (§3 footnotes).

_resolve_methods(inputs, project, ordered, feedback)[source]

Resolve every packaged layer’s matching method (§4); a full-only run is all whole-export.

Parameters:
Return type:

dict[str, LayerMatchPlan]

Returns:

One plan per layer id.

Raises:

QgsProcessingException – Per the §4 rules, or if the relation manager is absent.

_resolve_strat_layer(parameters, context, project, reader)[source]

Resolve STRATIFICATION_LAYER (explicit, else the project variable’s layer id).

Parameters:

  • parameters (dict[str | None, Any]) – Raw parameter values.

  • context (QgsProcessingContext) – The processing context.

  • project (QgsProject) – The run’s project.

  • reader (params.InputReader) – The input reader.

Return type:

QgsVectorLayer | None

Returns:

The stratification layer, or None.

_resolve_strata_validated(inputs, project, feedback)[source]

Validate the stratification layer and resolve the strata (§6, §15).

Parameters:
Return type:

StrataResolution

Returns:

The strata resolution.

Raises:

QgsProcessingException – Per the §6 strict rules (including the empty-selection fail-fast, raised by resolve_strata()) and §3 footnote ¹.

_scan_extra_dir(inputs, bundles, feedback)[source]

Reject EXTRA_DIR entries colliding with reserved zip content (§10, §15).

Parameters:
Raises:

QgsProcessingException – Listing every conflicting entry.

Return type:

None

_sld_text(layer)[source]

Serialize the layer’s SLD, best-effort (§8.1).

Prefer exportSldStyleV3() (QGIS 3.44+; returns the document); below QGIS 3.44 it is absent, so except AttributeError falls back to the deprecated exportSldStyleV2 (3.30). This guarded fallback is the sole sanctioned qgis.core behavioral fallback (SPEC §1.1); it keeps V3 from raising the support floor.

Unlike the QML (exportNamedStyle()), the SLD is serialized in full — it is intentionally not scoped to STYLE_CATEGORIES, because the SLD export API offers no category option and SLD represents only symbology and labeling. The category-filtered styleQML is the authoritative artifact (SPEC §13).

Parameters:

layer (QgsMapLayer) – The packaged layer.

Return type:

str

Returns:

The SLD XML (possibly empty or invalid; the caller guards validity).

_stage_chain_hop(layer, names, match_sets, staging_dir, index, chain_context, feedback)[source]

Copy one intermediate hop layer locally and register it on the chain context (§8.2).

Parameters:

  • layer (QgsVectorLayer) – The project’s hop layer (cloned, never read for data nor mutated).

  • names (Collection[str]) – The field names the chain queries on this layer.

  • match_sets (Collection[tuple[str, ...]]) – Distinct key field sets to index (the IN filters scan them).

  • staging_dir (Path) – The directory holding the staging GeoPackages.

  • index (int) – A per-run counter making the staging file name unique.

  • chain_context (ChainContext) – The run’s chain context, which receives the staged layer.

  • feedback (QgsProcessingFeedback) – Execution feedback channel.

Raises:

QgsProcessingException – If the copy cannot be written or re-opened.

Return type:

None

_stage_chain_hops(material, staging_dir, feedback)[source]

Stage the intermediate hop layers of a STAGE_PROVIDERS provider (SPEC §7.1/§8.2).

Relation-chain intermediates are read straight from the project, once per IN chunk per member per stratum — the one read path per-layer staging never covered, because staging only replaces a packaged layer’s read source. When such a hop sits on a provider the user declared slow, copy it once into a local GeoPackage holding just the fields the chain queries, index those, and resolve the chain against that copy instead.

The copy holds every feature: a chain propagates keys through the whole intermediate, so the matched-union slice a packaged layer stages would silently drop rows. A layer that is both a packaged layer and a hop is therefore staged twice, once per role, which is redundant but correct.

A failure here is contained: hop staging is a read-amortization optimization, so the run falls back to reading the project layer rather than aborting.

Parameters:

  • material (_Material) – The run material (its chain context receives the staged layers).

  • staging_dir (Path) – The directory holding the staging GeoPackages.

  • feedback (QgsProcessingFeedback) – Execution feedback channel.

Raises:

QgsProcessingException – On cancellation.

Return type:

None

_stage_layer(layer, plan, stage_providers)[source]

Resolve a partitioned layer’s staging decision (§8.2), wrapping the strict failure.

Parameters:
Return type:

bool

Returns:

Whether to stage the layer into a per-layer GeoPackage.

Raises:

QgsProcessingException – If the stage variable is neither boolean nor auto.

_stage_prep(prep, group, material, real_features, staging_dir, feedback)[source]

Build one staging GeoPackage and swap prep’s read source onto it (§8.2).

The staged copy must be a superset of every read taken against it: the union of every group member’s matches across all strata — or all features when EXPORT_FULL_PACKAGE is on, since the <full> stratum reads the whole staged copy.

Parameters:

  • prep (_LayerPrep) – The group primary (or ungrouped) prep; mutated to read the staged copy.

  • group (Sequence[_LayerPrep]) – Every prep sharing the table (just prep when ungrouped).

  • material (_Material) – The run material.

  • real_features (Sequence[QgsFeature]) – The real strata features.

  • staging_dir (Path) – The directory holding per-layer staging GeoPackages.

  • feedback (QgsProcessingFeedback) – Execution feedback channel.

Raises:

QgsProcessingException – On a staging write or transform failure.

Return type:

None

_stage_preps(material, real_features, staging_dir, feedback, *, skip_warm_staged)[source]

Stage the read sources that resolve stage=true — once per dedup group (§8.2).

Runs after apply_dedup(), so a group of shared-source layers stages a single copy through its primary (whose read layer already carries the merged field union and cleared subset); ungrouped layers stage individually. Whole-export preps are skipped — the §8.1.5 template is their staged form. With skip_warm_staged, a group whose every member is warm-marked is not staged either: on a WARM_START_MODE=use run whose caches all passed the §11 pre-scan, nothing ever reads such a group’s staged copy.

Parameters:

  • material (_Material) – The run material (primary preps mutated in place).

  • real_features (Sequence[QgsFeature]) – The real strata features (a staging copy unions across them).

  • staging_dir (Path) – The directory holding per-layer staging GeoPackages.

  • feedback (QgsProcessingFeedback) – Execution feedback channel.

  • skip_warm_staged (bool) – Whether fully-warm groups skip staging.

Raises:

QgsProcessingException – On a bad stage variable, a staging write failure, or cancellation.

Return type:

None

_stratum_band(state, build, feedback)[source]

Return the feedback band covering build’s slice of the 25-95 % B/C range (SPEC §8.4).

The slice spans the build’s per-layer units from the current unit count, so the writer sweeps inside it and the following _fold_* progress report lands exactly on the slice’s upper bound.

Parameters:
Return type:

_BandFeedback

Returns:

The band proxy to hand to write_stratum().

_stratum_build(stratum, material, features_by_name)[source]

Assemble one stratum’s deliverable build plan (§8.3 step-3 ordering).

Layer order: warm-marked first, the whole-export template layers, then the partitioned layers. A dedup group contributes one layer (the primary’s), carrying every member’s plan and style. WARM_START_MODE=update deliverables seed from the warm cache the §11 warm pass just wrote, exactly like a WARM_START_MODE=use run.

Parameters:
Return type:

StratumBuild

Returns:

The build plan.

_style_documents(layer, inputs, feedback)[source]

Serialize the layer’s style: QML for the selected categories, SLD best-effort (§8.1).

Parameters:
Return type:

tuple[str, str]

Returns:

(qml, sld) — both empty when styles are excluded.

_submit_warm_prefetch(material, strata, pool, cancel)[source]

Queue background copies of the §11 warm caches to their build paths (warm runs only).

Submitted before Phase A, so a (possibly remote) cache file arrives while layers are prepared and staged; the deliverable pass then seeds in place instead of copying on the critical path. Best-effort: a failed or unfinished copy falls back to the normal seed-time copy from the original cache file.

Parameters:

  • material (_Material) – The run material (bundle layout already computed).

  • strata (Sequence[StratumSpec]) – The surviving strata (<full> included when it is exported).

  • pool (ThreadPoolExecutor) – The background pool.

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

Return type:

None

_sweep_stale_workdirs(output_dir, feedback)[source]

Best-effort removal of day-old build directories a crashed run left behind (§10).

Only siblings past _STALE_WORKDIR_AGE are touched — a younger .stratified_build_* directory could belong to a run still executing against the same output directory.

Parameters:
Return type:

None

_tree_ordered(project, layers)[source]

Order vector layers by layer-tree order (§12/§15 tie-breaking).

Parameters:
Return type:

list[QgsVectorLayer]

Returns:

The ordered layers (tree order; unlisted ones keep input order).

_tree_ordered_any(project, layers)[source]

Order any layers by layer-tree order.

Parameters:
Return type:

list[QgsMapLayer]

Returns:

The ordered layers (tree order; unlisted ones keep input order).

_validate_warm_inputs(inputs)[source]

Enforce the §11 warm-start requirements at run start.

Parameters:

inputs (_Inputs) – The resolved inputs.

Raises:

QgsProcessingException – On a missing directory, an uncoercible warm_marked value, or an empty warm-marked layer set.

Return type:

None

_warm_cache_build(stratum, material, features_by_name, build_dir, warm_dir)[source]

Assemble one stratum’s §11 warm-pass build plan (WARM_START_MODE=update).

A fresh gpkg holding only the warm-marked primaries, assembled under build_dir and snapshot into the warm cache after its last layer lands. Empty warm tables are always kept — the cache stays complete regardless of KEEP_EMPTY_LAYERS, which the deliverable pass applies when it seeds from the cache.

Parameters:

  • stratum (StratumSpec) – The stratum.

  • material (_Material) – The run material.

  • features_by_name (Mapping[str, QgsFeature]) – Stratum features keyed by sanitized name (<full> absent).

  • build_dir (Path) – The workdir subdirectory holding the warm-pass builds.

  • warm_dir (Path) – The warm-cache directory (snapshot destination).

Return type:

StratumBuild

Returns:

The build plan.

_warm_covers_all_builds(material, strata, feedback)[source]

Pre-scan the §11 warm caches to decide whether warm-covered staging is skippable.

On a WARM_START_MODE=use run a fully-warm dedup group’s staged copy is only ever read by a per-stratum cold fallback, so staging it is pure waste unless some stratum will actually fall back. Run the seed-time completeness check (warm_rejection()) against every build’s cache file up front: all usable → staging of fully-warm groups is skipped (§8.2); any rejection → staging proceeds and the run is warned once.

Parameters:
Return type:

bool

Returns:

Whether every build’s warm cache passes the §11 completeness check.

_with_full_package(inputs, project, resolution)[source]

Append the <full> pseudo-stratum when EXPORT_FULL_PACKAGE is on (§3).

FULL_PACKAGE_PATH is the full package’s (extensionless) zip path, relative to OUTPUT_DIRECTORY or absolute (§3, _full_package_zip_rel()); its in-zip gpkg path follows GPKG_PATH_EXPRESSION (empty ⇒ the zip basename), evaluated feature-less for <full> — never derived from FULL_PACKAGE_PATH itself.

Parameters:

  • inputs (_Inputs) – The resolved inputs.

  • project (QgsProject) – The run’s project (supplies the default basename).

  • resolution (StrataResolution) – The strata resolution.

Return type:

StrataResolution

Returns:

The resolution, possibly extended by the full package.

Raises:

QgsProcessingException – On an invalid full-package path, on a GPKG_PATH_EXPRESSION parse/evaluation/NULL error, or on any §6.5/§6.6 collision the re-bundling detects (case-variant zip paths, gpkg paths colliding inside a bundle the full package joins).

_zip_job(material, zip_rel, workdir)[source]

Assemble one bundle’s zip job from its build root (§10).

Parameters:

  • material (_Material) – The run material.

  • zip_rel (str) – The bundle’s zip path (no extension).

  • workdir (Path) – The run’s build directory.

Return type:

ZipJob

Returns:

The zip job.

checkParameterValues(parameters, context)[source]

Run the static (no data access) §15 checks.

Parameters:
Return type:

tuple[bool, str]

Returns:

(ok, message).

createInstance()[source]

Create a new instance of the algorithm class.

Return type:

StratifiedPackagerAlgorithm

displayName()[source]

Return the translated user-facing algorithm name.

Return type:

str

flags()[source]

Return the algorithm flags; a project is required.

Return type:

ProcessingAlgorithmFlag

initAlgorithm(configuration=None)[source]

Declare the SPEC §3 inputs and outputs, defaults pre-resolved (SPEC §5).

Parameters:

configuration (dict[str | None, Any] | None) – Unused framework configuration map.

Return type:

None

name()[source]

Return the algorithm name, used for identifying the algorithm.

Return type:

str

processAlgorithm(parameters, context, feedback)[source]

Run the algorithm: validation → Phase A → Phase B/C → report + outputs.

Parameters:

  • parameters (dict[str | None, Any]) – Input parameter values, keyed by parameter name.

  • context (QgsProcessingContext) – Context in which the algorithm runs.

  • feedback (QgsProcessingFeedback | None) – The sole channel for user-facing messages, progress reporting, and cancellation during execution.

Return type:

dict[str, Any]

Returns:

Output value map, keyed by output name (SPEC §3 declared outputs).

Raises:

qgis.core.QgsProcessingException – On a fatal error that must abort the run, and at the end of a best-effort run in which any stratum failed (listing the failed strata).

shortDescription()[source]

Return a translated one-line description.

Return type:

str

shortHelpString()[source]

Return a localised HTML help string documenting every parameter (SPEC §20).

Return type:

str

class stratified_packager.processing.algorithm._BandFeedback(parent, start, end)[source]

Proxy feedback whose full 0-100 progress range maps into a band of a parent feedback.

Handed to a sub-operation (a QgsVectorFileWriter write, or a QgsProcessingMultiStepFeedback stepping over several of them), it scales the sub-operation’s raw setProgress sweeps into the [start, end] slice of the run’s overall bar, so the bar always reads overall progress (SPEC §8.4). Messages and progress text forward to the parent unchanged; cancellation propagates from the parent the way QgsProcessingMultiStepFeedback propagates it (a direct-connected canceled signal, so no spinning event loop is needed).

setProgress() is not virtual, so a C++ caller bypasses any Python override — the scaling therefore rides this object’s own progressChanged signal, the same mechanism QgsProcessingMultiStepFeedback uses.

Parameters:
__init__(parent, start, end)[source]

Wire the proxy onto parent.

Parameters:

  • parent (QgsProcessingFeedback) – The feedback receiving the scaled progress and forwarded messages.

  • start (float) – The parent progress this proxy’s 0 maps to.

  • end (float) – The parent progress this proxy’s 100 maps to.

_scale_to_parent(progress)[source]

Relay an own-progress change into the parent band.

Parameters:

progress (float) – This proxy’s progress in [0, 100].

Return type:

None

pushCommandInfo(info=None)[source]

Forward a command message to the parent.

Parameters:

info (str | None) – The message.

Return type:

None

pushConsoleInfo(info=None)[source]

Forward a console-output message to the parent.

Parameters:

info (str | None) – The message.

Return type:

None

pushDebugInfo(info=None)[source]

Forward a debug message to the parent.

Parameters:

info (str | None) – The message.

Return type:

None

pushFormattedMessage(html=None, text=None)[source]

Forward a formatted message to the parent.

Parameters:

  • html (str | None) – The HTML form of the message.

  • text (str | None) – The plain-text form of the message.

Return type:

None

pushInfo(info=None)[source]

Forward an info message to the parent.

Parameters:

info (str | None) – The message.

Return type:

None

pushWarning(warning=None)[source]

Forward a warning message to the parent.

Parameters:

warning (str | None) – The message.

Return type:

None

reportError(error=None, fatalError=False)[source]

Forward an error to the parent.

Parameters:

  • error (str | None) – The error message.

  • fatalError (bool) – Whether the error prevents the algorithm from completing.

Return type:

None

setProgressText(text=None)[source]

Forward the progress text to the parent.

Parameters:

text (str | None) – The progress text.

Return type:

None

_parent

The wrapped feedback (also keeps the Python wrapper alive for C++ callees).

_span

Parent progress distance covered by this proxy’s 0 → 100.

_start

Parent progress at this proxy’s 0.

stratified_packager.processing.algorithm._full_package_zip_rel(base, output_dir)[source]

Resolve FULL_PACKAGE_PATH to the <full> bundle’s zip key (SPEC §3).

A relative path keeps the §6.5 archive-path rules. An absolute one is honored as-is — like EXTRA_DIR / WARM_START_DIR — but one resolving inside output_dir folds back to the relative form so bundling identity and the §6.6 collision checks keep seeing a single namespace. Only the basename of an outside-the-output-directory path is validated: its parent directories are the filesystem’s business and may legitimately already exist under names the strict filename rules reject.

Parameters:

  • base (str) – The raw FULL_PACKAGE_PATH value (never empty; extensionless).

  • output_dir (Path) – The run’s OUTPUT_DIRECTORY.

Return type:

str

Returns:

The zip key: a /-joined relative path, or an absolute posix path.

Raises:

ValueError – On a §6.5 shape violation; the message names the violation.

stratified_packager.processing.algorithm._place(source, destination)[source]

Materialize source at destination (hardlink when possible, copy otherwise).

Parameters:

  • source (Path) – The existing file.

  • destination (Path) – The target inside a zip-mirror build root.

Return type:

None

stratified_packager.processing.algorithm._report_chain_memo(chain_context, feedback)[source]

Report how many §7.1 hop queries the chain memo saved, once per run.

Debug-level: the memo is an optimization whose effect never changes an output, so it belongs with the other diagnostics rather than in the run’s info stream.

Parameters:
Return type:

None

stratified_packager.processing.algorithm._HOP_TABLE: Final = 'hop'

Table name inside a staged relation-chain intermediate’s GeoPackage (SPEC §7.1/§8.2); each hop layer gets its own file, so one fixed name never collides.

stratified_packager.processing.algorithm._PAYLOAD_LAYER_TYPES: Final[frozenset[Qgis.LayerType]] = frozenset({qgis.core.Qgis.LayerType.Mesh, qgis.core.Qgis.LayerType.PointCloud, qgis.core.Qgis.LayerType.Raster})

Layer types packaged as a data/ payload copy when their source is local (SPEC §14).

stratified_packager.processing.algorithm._POOL_WIDTH: Final = 2

Background pool width (SPEC §8.4).

One thread keeps zip packaging ahead of the sequential builds — a bundle’s zip is a single DEFLATE stream that finishes well within the next bundle’s build time, so jobs never queue (measured on the 94-zip field project: the pool never held more than one active zip) — and the second overlaps the §11 warm-cache prefetch with Phase A.

stratified_packager.processing.algorithm._RESERVED_EXTRA_ROOTS: tuple[str, ...] = ('data', 'resources')

Zip-root directory names reserved for the packager’s own payloads (SPEC §10).

stratified_packager.processing.algorithm._SQLITE_SIDECAR_SUFFIXES: tuple[str, ...] = ('-wal', '-shm', '-journal')

SQLite sidecar suffixes excluded from zips (checkpointed away beforehand, SPEC §10).

stratified_packager.processing.algorithm._STALE_WORKDIR_AGE: Final = 86400.0

Minimum age in seconds before a leftover .stratified_build_* directory from an earlier run is swept at run start (§10); younger siblings could belong to a live concurrent run against the same output directory.