stratified_packager.processing.strata

Strata resolution: snapshot, strict naming, gpkg/zip path evaluation, bundling (SPEC §6).

Runs on the algorithm thread during Phase A. Every fatal condition raises QgsProcessingException (the Processing framework’s sanctioned failure path); names and paths are validated, never silently rewritten.

Module Attributes

FULL_PACKAGE_KEY

Pseudo-stratum key of the full package (SPEC §2/§11); sanitization strips </>, so no real stratum can collide with it.

Functions

`bundle_strata`(strata)	Group strata into zip bundles and enforce the §6.6 uniqueness rules.
`evaluate_layer_display_name`(layer, project, ...)	Evaluate a packaged layer's display-name expression for one stratum (SPEC §4/§13).
`resolve_strata`(layer, *, project[, ...])	Resolve the run's strata from the stratification layer (SPEC §6).

Classes

`StrataResolution`(strata, bundles, features)	The outcome of strata resolution.
`StratumSpec`(feature_id, raw_name, name, ...)	One resolved stratum (plain data; safe to hand across threads).

class stratified_packager.processing.strata.StrataResolution(strata, bundles, features)[source]

The outcome of strata resolution.

Parameters:

strata (tuple[StratumSpec, ...])
bundles (Mapping[str, tuple[StratumSpec, ...]])
features (tuple[QgsFeature, ...])

__init__(strata, bundles, features)

Parameters:

strata (tuple[StratumSpec, ...])
bundles (Mapping[str, tuple[StratumSpec, ...]])
features (tuple[QgsFeature, ...])

bundles: Mapping[str, tuple[StratumSpec, ...]]: Members per zip path (zip_rel); multi-member values are bundled zips (§6.6).

features: tuple[qgis.core.QgsFeature, ...]: The stratum features, aligned with strata. Phase-A (algorithm thread) material only — unlike the specs, these are live QGIS objects.

strata: tuple[StratumSpec, ...]: All strata, ordered by stratum feature id.

class stratified_packager.processing.strata.StratumSpec(feature_id, raw_name, name, gpkg_rel, zip_rel)[source]

One resolved stratum (plain data; safe to hand across threads).

Parameters:

feature_id (int)
raw_name (str)
name (str)
gpkg_rel (str)
zip_rel (str)

__init__(feature_id, raw_name, name, gpkg_rel, zip_rel)

Parameters:

feature_id (int)
raw_name (str)
name (str)
gpkg_rel (str)
zip_rel (str)

feature_id: int: Feature id of the stratum feature in the stratification layer.

property gpkg_name: str

The gpkg basename (no extension, no directories).

Returns:: The last component of gpkg_rel.

gpkg_rel: str: Zip-internal gpkg path, slash-separated, without the .gpkg extension.

name: str: The sanitized stratum name — filename-grade, also the warm-cache key (SPEC §11).

raw_name: str: The evaluated (unsanitized) stratum name.

zip_rel: str: Output-directory-relative zip path, slash-separated, without the .zip extension.

class stratified_packager.processing.strata._PathKind(*values)[source]

Which §6 path is being evaluated (only affects error wording).

GPKG = 'GeoPackage'

ZIP = 'zip'

stratified_packager.processing.strata._base_context(layer, project)[source]

Build the full project + layer expression context (SPEC §6.2).

Parameters:

layer (QgsMapLayer) – The layer supplying the layer scope (any map layer).
project (QgsProject) – The project.

Return type:

QgsExpressionContext

Returns:

A fresh expression context.

stratified_packager.processing.strata._evaluate_names(layer, project, expression_text, features)[source]

Evaluate the stratum name per feature under the strict regime (SPEC §6.2).

Parameters:

layer (QgsVectorLayer) – The stratification layer.
project (QgsProject) – The project.
expression_text (str) – The name expression; empty means the feature id.
features (Sequence[QgsFeature]) – The snapshot.

Return type:

list[str]

Returns:

One raw name per feature, in order.

Raises:

QgsProcessingException – On a parse error, an evaluation error or a NULL name.

stratified_packager.processing.strata._evaluate_path(layer, project, expression_text, feature, *, default, kind, stratum_vars)[source]

Evaluate and validate one gpkg/zip path for one stratum (SPEC §6.4/§6.5).

Parameters:

layer (QgsVectorLayer) – The stratification layer.
project (QgsProject) – The project.
expression_text (str) – The path expression; empty selects default.
feature (QgsFeature) – The stratum feature.
default (str) – The default path when the expression is empty.
kind (_PathKind) – Which path is being evaluated (error wording).
stratum_vars (Mapping[str, str]) – The §6.4 naming variables injected into the context.

Return type:

str

Returns:

The validated, slash-joined relative path (no extension).

Raises:

QgsProcessingException – On parse/evaluation errors, NULL results or §6.5 path-rule violations.

stratified_packager.processing.strata._reject_duplicate_raw_names(raw_names)[source]

Abort on duplicate raw stratum names (SPEC §6.2).

Parameters:: raw_names (Sequence[str]) – The evaluated names.
Raises:: QgsProcessingException – Listing every duplicated name.
Return type:: None

stratified_packager.processing.strata._reject_sanitization_collisions(raw_names, sanitized)[source]

Abort on case-insensitive post-sanitization collisions (SPEC §6.2, Windows rule).

Parameters:

raw_names (Sequence[str]) – The raw names (for the error message).
sanitized (Sequence[str]) – The sanitized names, aligned with raw_names.

Raises:

QgsProcessingException – Listing the colliding raw-name groups.

Return type:

None

stratified_packager.processing.strata._snapshot(layer, *, strata_from_selection)[source]

Materialize the stratum features once, ordered by feature id (SPEC §6.1).

Parameters:

layer (QgsVectorLayer) – The stratification layer (its subsetString applies implicitly).
strata_from_selection (bool) – Whether only the selected features become strata.

Return type:

list[QgsFeature]

Returns:

The ordered features.

Raises:

QgsProcessingException – If strata_from_selection is set but nothing is selected — fail-fast, never a silent full run (SPEC §6.1/§15).

stratified_packager.processing.strata.bundle_strata(strata)[source]

Group strata into zip bundles and enforce the §6.6 uniqueness rules.

Also called by the algorithm to re-bundle after appending the <full> pseudo-stratum, so the full package passes the same zip- and gpkg-collision checks as any stratum.

Parameters:: strata (Sequence[StratumSpec]) – The resolved strata.
Return type:: dict[str, tuple[StratumSpec, ...]]
Returns:: Members per exact zip path, in stratum order.
Raises:: QgsProcessingException – On case-variant zip paths or on case-insensitive gpkg path collisions inside one bundle.

stratified_packager.processing.strata.evaluate_layer_display_name(layer, project, expression_text, *, stratum_name, stratum_name_sanitized)[source]

Evaluate a packaged layer’s display-name expression for one stratum (SPEC §4/§13).

The expression sees the full project + layer context plus @stratum_name and @stratum_name_sanitized. Unlike the §6 path expressions it is feature-less — it names a whole layer, not a stratum feature — and its layer scope is the packaged layer being renamed, so @layer_name resolves to that layer’s original name.

Parameters:

layer (QgsMapLayer) – The packaged layer being renamed.
project (QgsProject) – The project supplying the global/project/layer scopes.
expression_text (str) – The non-empty stratified_packager_layer_name expression.
stratum_name (str) – The raw stratum name (@stratum_name).
stratum_name_sanitized (str) – The sanitized stratum name (@stratum_name_sanitized).

Return type:

str

Returns:

The evaluated display name.

Raises:

QgsProcessingException – On a parse error, an evaluation error or a NULL result.

stratified_packager.processing.strata.resolve_strata(layer, *, project, name_expression='', gpkg_path_expression='', zip_path_expression='', strata_from_selection=False)[source]

Resolve the run’s strata from the stratification layer (SPEC §6).

The snapshot honors the layer’s subsetString; when strata_from_selection is set, only the selected features become strata (an empty selection aborts — fail-fast, never a silent full run). Names follow the strict regime: NULL or evaluation errors, duplicate raw names and case-insensitive post-sanitization collisions all abort. Evaluated gpkg/zip paths are validated against the §6.5 path rules, and the §6.6 bundling rules are enforced.

Parameters:

layer (QgsVectorLayer) – The stratification layer.
project (QgsProject) – The project supplying the expression context scopes.
name_expression (str) – STRATUM_NAME_EXPRESSION; empty means the feature id.
gpkg_path_expression (str) – GPKG_PATH_EXPRESSION; empty means the sanitized name.
zip_path_expression (str) – ZIP_PATH_EXPRESSION; empty means the gpkg basename.
strata_from_selection (bool) – Whether an existing selection restricts the strata.

Return type:

StrataResolution

Returns:

The resolved strata and their zip bundles (both empty for an empty layer).

Raises:

QgsProcessingException – On any violation of the strict §6 rules.

stratified_packager.processing.strata.FULL_PACKAGE_KEY: Final = '<full>': Pseudo-stratum key of the full package (SPEC §2/§11); sanitization strips </>, so no real stratum can collide with it.