stratified_packager.processing.material

Phase-A → Phase-B/C hand-off records and their shared helpers (SPEC §8).

The plain dataclasses the algorithm fills during Phase A and consumes while building and zipping (_Inputs, _LayerPrep, _PayloadPrep, _Material, _BuildState), plus the small helpers that several phase modules share (_field_indexes(), _warm_file_name(), _is_warm_marked()). Kept here so the extracted phase modules (dedup, reporting) and the orchestrator all depend on one lower-layer module rather than on each other.

class stratified_packager.processing.material._BuildState(total_units, done_units=0, succeeded=<factory>, failed=<factory>, published=<factory>, failed_zips=<factory>, layer_results=<factory>, zip_futures=<factory>, cold_fallbacks=<factory>, matched_union=<factory>, failed_warm=<factory>)[source]

Mutable bookkeeping of the sequential build and the background zip pool.

Parameters:
__init__(total_units, done_units=0, succeeded=<factory>, failed=<factory>, published=<factory>, failed_zips=<factory>, layer_results=<factory>, zip_futures=<factory>, cold_fallbacks=<factory>, matched_union=<factory>, failed_warm=<factory>)
Parameters:
cold_fallbacks: dict[str, str]
done_units: int = 0
failed: dict[str, str]
failed_warm: dict[str, str]

Stratum name -> error of its failed §11 warm-cache write (the deliverable still builds — cold — but a requested-yet-unwritten cache fails the run at the end).

failed_zips: dict[str, str]
layer_results: dict[tuple[str, str], LayerWriteResult]

(stratum name, layer id) -> the layer’s write outcome (the dedup primary’s id).

matched_union: dict[str, set[int]]

Dedup-primary layer id -> union of matched fids across strata (§9.1 orphans).

published: list[str]
succeeded: set[str]
total_units: int

Progress units: one per (stratum, layer) write plus one per bundle zip.

zip_futures: list[Future[ZipOutcome]]
class stratified_packager.processing.material._Inputs(layers, payload_layers, embedded_layers, strat_layer, name_expression, gpkg_expression, zip_expression, output_dir, compression_level, overwrite_mode, project_inclusion, use_temp_folder, strata_from_selection, include_styles, style_categories, include_metadata, keep_empty_layers, deduplicate, stage_providers, export_full, generate_report, write_checksums, extra_dir, warm_dir, use_warm, update_warm, full_package_path, dry_run)[source]

Every input of SPEC §3, resolved through the §5 chain to typed values.

Parameters:

  • layers (list[QgsVectorLayer])

  • payload_layers (list[QgsMapLayer])

  • embedded_layers (list[QgsMapLayer])

  • strat_layer (QgsVectorLayer | None)

  • name_expression (str)

  • gpkg_expression (str)

  • zip_expression (str)

  • output_dir (Path)

  • compression_level (int)

  • overwrite_mode (params.OverwriteMode)

  • project_inclusion (params.ProjectInclusion)

  • use_temp_folder (bool)

  • strata_from_selection (bool)

  • include_styles (bool)

  • style_categories (QgsMapLayer.StyleCategory)

  • include_metadata (bool)

  • keep_empty_layers (bool)

  • deduplicate (bool)

  • stage_providers (frozenset[str])

  • export_full (bool)

  • generate_report (bool)

  • write_checksums (bool)

  • extra_dir (Path | None)

  • warm_dir (Path | None)

  • use_warm (bool)

  • update_warm (bool)

  • full_package_path (str)

  • dry_run (bool)

__init__(layers, payload_layers, embedded_layers, strat_layer, name_expression, gpkg_expression, zip_expression, output_dir, compression_level, overwrite_mode, project_inclusion, use_temp_folder, strata_from_selection, include_styles, style_categories, include_metadata, keep_empty_layers, deduplicate, stage_providers, export_full, generate_report, write_checksums, extra_dir, warm_dir, use_warm, update_warm, full_package_path, dry_run)
Parameters:

  • layers (list[QgsVectorLayer])

  • payload_layers (list[QgsMapLayer])

  • embedded_layers (list[QgsMapLayer])

  • strat_layer (QgsVectorLayer | None)

  • name_expression (str)

  • gpkg_expression (str)

  • zip_expression (str)

  • output_dir (Path)

  • compression_level (int)

  • overwrite_mode (params.OverwriteMode)

  • project_inclusion (params.ProjectInclusion)

  • use_temp_folder (bool)

  • strata_from_selection (bool)

  • include_styles (bool)

  • style_categories (QgsMapLayer.StyleCategory)

  • include_metadata (bool)

  • keep_empty_layers (bool)

  • deduplicate (bool)

  • stage_providers (frozenset[str])

  • export_full (bool)

  • generate_report (bool)

  • write_checksums (bool)

  • extra_dir (Path | None)

  • warm_dir (Path | None)

  • use_warm (bool)

  • update_warm (bool)

  • full_package_path (str)

  • dry_run (bool)

compression_level: int
deduplicate: bool
dry_run: bool
embedded_layers: list[QgsMapLayer]
export_full: bool
extra_dir: Path | None
full_package_path: str
generate_report: bool
gpkg_expression: str
include_metadata: bool
include_styles: bool
keep_empty_layers: bool
layers: list[QgsVectorLayer]
name_expression: str
output_dir: Path
overwrite_mode: params.OverwriteMode
payload_layers: list[QgsMapLayer]
project_inclusion: params.ProjectInclusion
stage_providers: frozenset[str]
strat_layer: QgsVectorLayer | None
strata_from_selection: bool
style_categories: QgsMapLayer.StyleCategory
update_warm: bool
use_temp_folder: bool
use_warm: bool
warm_dir: Path | None
write_checksums: bool
zip_expression: str
class stratified_packager.processing.material._LayerPrep(layer, table, plan, read_layer, kept_fields, kept_field_indexes, excluded_fields, subset_sql='', qml='', sld='', metadata_xml='', staged=False, group_primary_id=None)[source]

Phase-A material of one packaged vector layer.

Parameters:
__init__(layer, table, plan, read_layer, kept_fields, kept_field_indexes, excluded_fields, subset_sql='', qml='', sld='', metadata_xml='', staged=False, group_primary_id=None)
Parameters:
excluded_fields: tuple[str, ...]
group_primary_id: str | None = None

Dedup groups (§12): the primary member’s layer id when this prep rides a shared table (the primary points at itself); None outside any group.

kept_field_indexes: tuple[int, ...]

kept_fields resolved to indexes into read_layer.fields() (the writer drops the rest); empty exports every field.

kept_fields: tuple[str, ...]

Exported field names after exclusions (and the §12 dedup union on a primary).

layer: qgis.core.QgsVectorLayer

The user’s layer (styles, names, the embedded-project source); never read for data.

metadata_xml: str = ''
plan: LayerMatchPlan
qml: str = ''
read_layer: qgis.core.QgsVectorLayer

The standalone layer the per-stratum write reads and selects from — a clone of layer, or a layer over the staging/full-package gpkg. Never a project layer, so its selection is mutated freely.

sld: str = ''
staged: bool = False

Whether read_layer is a staging copy (§8.2) — set on the group primary (or an ungrouped layer); non-primary members read through their primary’s staged table.

subset_sql: str = ''

The original subsetString, re-applied in the embedded project (§12); no longer a data filter — per-stratum filtering is the read layer’s selection.

table: str
class stratified_packager.processing.material._Material(project, inputs, preps=<factory>, payloads=<factory>, assets=<factory>, bundles=<factory>, zip_roots=<factory>, gpkg_paths=<factory>, zip_of_stratum=<factory>, warm_marked_ids=<factory>, warm_prefetch=<factory>, layer_name_expressions=<factory>, template_path=None)[source]

Everything Phase A hands to Phases B/C (one object instead of long params).

Parameters:
__init__(project, inputs, preps=<factory>, payloads=<factory>, assets=<factory>, bundles=<factory>, zip_roots=<factory>, gpkg_paths=<factory>, zip_of_stratum=<factory>, warm_marked_ids=<factory>, warm_prefetch=<factory>, layer_name_expressions=<factory>, template_path=None)
Parameters:
assets: dict[str, str]

Style-asset path -> resources/... arcname (SPEC §14).

bundles: dict[str, tuple[StratumSpec, ...]]
gpkg_paths: dict[str, Path]

Stratum name -> its gpkg build path (inside its zip root).

inputs: _Inputs
layer_name_expressions: dict[str, str]

Layer id -> non-empty stratified_packager_layer_name expression text (SPEC §4), snapshotted and parse-validated in Phase A; empty unless an embedded project is built.

payloads: list[_PayloadPrep]
preps: list[_LayerPrep]
project: qgis.core.QgsProject
template_path: Path | None = None

The §8.1.5 template gpkg (non-warm-marked whole-export layers), if built.

warm_marked_ids: set[str]

Layer ids carrying warm_marked = true (§11).

warm_prefetch: dict[str, Future[bool]]

Stratum name -> its §11 warm-cache prefetch future (WARM_START_MODE=use runs only): True = the cache already sits at the stratum’s build path and the build seeds in place; False/absent = seed-time copy from the original cache file.

zip_of_stratum: dict[str, str]

Stratum name -> its zip path.

zip_roots: dict[str, Path]

Zip path -> its zip-mirror build root.

class stratified_packager.processing.material._PayloadPrep(layer, table, members, layer_type, project_source='')[source]

Phase-A material of one whole-export raster/mesh/point-cloud layer (SPEC §14).

Parameters:
__init__(layer, table, members, layer_type, project_source='')
Parameters:
layer: qgis.core.QgsMapLayer
layer_type: str

§9.2 token: raster | mesh | point-cloud.

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

(source file, arcname) pairs under data/<table>/.

project_source: str = ''

Arcname the embedded project re-points this layer at (§13) and the §9.2 path_in_zip: the main file, or the copied directory for directory-based sources.

table: str
stratified_packager.processing.material._field_indexes(layer, names)[source]

Resolve field names to their indexes in layer, in field order.

Parameters:
Return type:

tuple[int, ...]

Returns:

The matching indexes in field order (an empty tuple keeps every field).

stratified_packager.processing.material._is_warm_marked(layer)[source]

Report whether a layer carries stratified_packager_warm_marked = true (§11).

Coerced with the same strict coerce_bool() every other boolean layer variable uses (§4/§6 strict regime).

Parameters:

layer (QgsMapLayer) – The packaged layer.

Return type:

bool

Returns:

Whether the layer belongs to the warm cache.

Raises:

QgsProcessingException – If the variable holds an uncoercible value.

stratified_packager.processing.material._warm_file_name(stratum_name)[source]

Map a stratum key to its warm-cache file basename (§11).

Parameters:

stratum_name (str) – The sanitized stratum name, or <full>.

Return type:

str

Returns:

The basename without extension (__full__ for the full package, whose key contains characters that are not legal in filenames).