stratified_packager.processing.project_builder

Embedded per-stratum project construction (SPEC §13).

Runs on the algorithm thread during Phase C — never against instance(). The fresh project re-points included layers at the stratum GeoPackage tables and the data/ payload copies, restores the layer-tree structure (groups, order, visibility) restricted to included layers, applies the full (rewritten) styles, remaps relations among included layers, and carries the project CRS, transform context and title. Paths are stored relative: the caller builds the stratum inside a directory tree that mirrors the zip layout, so Qt’s relative-path storage produces portable ./… sources (SPEC §13).

Functions

build_stratum_project(source, plan, feedback)

Build and write one stratum's embedded project (SPEC §13).

Classes

StratumProjectPlan(title, mode, gpkg_path[, ...])

Everything needed to build one stratum's embedded project.
class stratified_packager.processing.project_builder.StratumProjectPlan(title, mode, gpkg_path, qgz_path=None, vector_tables=<factory>, data_sources=<factory>, embedded_only=(), styles_qml=<factory>, subsets=<factory>, display_names=<factory>)[source]

Everything needed to build one stratum’s embedded project.

Parameters:
__init__(title, mode, gpkg_path, qgz_path=None, vector_tables=<factory>, data_sources=<factory>, embedded_only=(), styles_qml=<factory>, subsets=<factory>, display_names=<factory>)
Parameters:
data_sources: dict[str, Path]

Included payload layers: source layer id -> absolute path of the data/ copy inside the zip-mirror tree.

display_names: dict[str, str]

Source layer id -> custom display name for this stratum (SPEC §4 layer_name, already evaluated). Absent ids keep the original layer name.

embedded_only: tuple[str, ...] = ()

Source layer ids riding only in the project (remote sources, annotations).

gpkg_path: Path

The stratum GeoPackage (absolute, already built, inside the zip-mirror tree).

mode: ProjectInclusion

gpkg (project storage inside the GeoPackage) or qgz (file beside it).

qgz_path: Path | None = None

The .qgz destination for qgz mode (beside the gpkg, same basename).

styles_qml: dict[str, str]

Source layer id -> rewritten QML document (SPEC §14 asset paths).

subsets: dict[str, str]

Source layer id -> subset string to re-apply (SPEC §12/§13).

title: str

Project title (the stratum name).

vector_tables: dict[str, str]

Included vector layers: source layer id -> table present in the stratum gpkg.

stratified_packager.processing.project_builder._append_unplaced(fresh, fresh_root, replacements, placed)[source]

Append included layers that had no source tree node (legend-less additions).

Parameters:
Return type:

None

stratified_packager.processing.project_builder._apply_styles_and_subsets(plan, replacements, feedback)[source]

Apply the rewritten QML styles and re-apply subset strings.

Parameters:
Return type:

None

stratified_packager.processing.project_builder._build_layers(source, plan, feedback)[source]

Create the fresh project’s layers, keyed by their source layer id.

Broken layers are never included (SPEC §13 bad-layer policy) — a re-pointed layer that fails to open is dropped with a warning.

Parameters:
Return type:

dict[str, QgsMapLayer]

Returns:

Source layer id -> replacement layer.

stratified_packager.processing.project_builder._capture_log()[source]

Collect QgsMessageLog entries emitted on the current thread.

Surfaces why write() failed: it returns only a bool while the cause is logged. The write runs synchronously on the algorithm thread, so its emissions invoke the handler before the block exits. The handler is a plain callable with no receiver thread affinity, so an unrelated emission from another thread during this window would run it on that thread — a tolerated, GIL-safe append of a stray line.

Yield:

The list each entry ([tag] message) is appended to.

stratified_packager.processing.project_builder._embedded_replacement(original, source, plan, feedback)[source]

Build the embedded-only replacement for one layer.

Live virtual layers are re-pointed at the stratum gpkg (_rebuild_virtual_layer()); remote and annotation layers are cloned with their original sources.

Parameters:

  • original (QgsMapLayer) – The source project’s embedded-only layer.

  • source (QgsProject) – The open project being packaged.

  • plan (StratumProjectPlan) – The stratum’s project plan.

  • feedback (QgsProcessingFeedback) – Execution feedback channel.

Return type:

QgsMapLayer | None

Returns:

The replacement layer, or None to drop it.

stratified_packager.processing.project_builder._fast_open()[source]

Build the layer options of a re-pointed embedded-project layer.

loadDefaultStyle=False: the style is applied explicitly afterwards from the exported QML (the very payload the gpkg layer_styles rows carry — _finalize_layer writes both from the same source), so the per-layer default-style lookup is a redundant read. skipCrsValidation=True: the CRS comes from the just-written gpkg (or the virtual query); there is nothing to interactively validate on a worker thread.

Return type:

LayerOptions

Returns:

The options for QgsVectorLayer construction.

stratified_packager.processing.project_builder._rebuild_virtual_layer(original, source, plan, feedback)[source]

Re-point a live virtual layer’s sources at this stratum’s gpkg tables.

Each source the virtual layer queries is rewritten to the GeoPackage table that holds that layer in this stratum; the query, uid and geometry definition are preserved. The layer is dropped (returning None) when any source has no table in this stratum (e.g. an empty layer omitted under KEEP_EMPTY_LAYERS=False). Style and attribute-form config ride along by cloning the original and only swapping its data source.

Parameters:

  • original (QgsMapLayer) – The source project’s virtual layer.

  • source (QgsProject) – The open project being packaged (resolves source references).

  • plan (StratumProjectPlan) – The stratum’s project plan.

  • feedback (QgsProcessingFeedback) – Execution feedback channel.

Return type:

QgsMapLayer | None

Returns:

The re-pointed virtual layer, or None to drop it.

stratified_packager.processing.project_builder._remap_relations(source, fresh, replacements, feedback)[source]

Recreate the relations whose both ends are included.

Relations touching excluded layers are dropped.

Parameters:
Return type:

None

stratified_packager.processing.project_builder._replicate_tree(source, fresh, replacements, feedback)[source]

Replicate the layer tree (groups, order, visibility) for included layers.

Parameters:
Return type:

None

stratified_packager.processing.project_builder._resolve_virtual_source_table(src, source, plan)[source]

Find the stratum gpkg table backing one virtual-layer source.

References by layer id resolve directly; embedded sources match the first packaged layer with the same provider and source string.

Parameters:
Return type:

str | None

Returns:

The table name, or None when the source is not packaged here.

stratified_packager.processing.project_builder._write_failure_detail(plan, messages)[source]

Describe why write() failed, for the raised exception.

Prefers the captured log; falls back to filesystem facts about the destination when the log stayed silent.

Parameters:
Return type:

str

Returns:

A single-line detail string.

stratified_packager.processing.project_builder.build_stratum_project(source, plan, feedback)[source]

Build and write one stratum’s embedded project (SPEC §13).

Parameters:
Raises:

QgsProcessingException – If writing the project fails.

Return type:

None