stratified_packager.processing.virtual

Virtual-layer routing: materialize into the stratum gpkg vs. keep live (SPEC §4/§13).

A virtual provider layer is either materialized into its own packaged table (behaving like any packaged vector) or kept live in the embedded project — re-pointed at this stratum’s gpkg tables — when every source it queries is already packaged. Runs on the algorithm thread during Phase A layer classification.

Functions

load_lazy_virtual(layer, feedback)	Run a lazy virtual layer's query so it reads its rows rather than nothing (§4/§13).
route_virtual_layers(virtuals, vectors, ...)	Route virtual layers to packaged vectors (materialize) or embedded-only (live) (§4/§13).

stratified_packager.processing.virtual._virtual_should_materialize(layer, packaged_ids, packaged_keys, feedback)

Decide whether a virtual layer is materialized vs. kept live (SPEC §4/§13).

The materialize_virtual_layer variable forces materialization when true. Otherwise the layer is kept live only when every source it queries is already packaged into the stratum gpkg (referenced by id to a packaged layer, or an embedded source normalizing to a packaged layer’s source); any uncovered source would require adding new data, so the layer is materialized and an info message is pushed.

Parameters:

• layer (QgsVectorLayer) – The virtual provider layer.

• packaged_ids (frozenset[str]) – Layer ids of the packaged (vector + payload) layers.

• packaged_keys (frozenset[tuple[str, frozenset[tuple[str, str]]]]) – Dedup source keys of the packaged vector layers.

• feedback (QgsProcessingFeedback) – Execution feedback channel.

Return type:

bool

Returns:

True to materialize (route to packaged vectors), False to keep the layer live (route to embedded-only).

Raises:

qgis.core.QgsProcessingException – If the materialize_virtual_layer value cannot be coerced to bool (the §6 strict regime).

stratified_packager.processing.virtual._warn_remote_sources(layer, project, feedback)

Warn when a materialized virtual layer queries sources off the local machine (§4/§8.2).

A materialized virtual layer is packaged like any vector, so its SQLite query is re-executed for every stratum — once to select the stratum’s features and once more while the writer reads them. When a source is a database or service provider, each execution is a round-trip generator: SQLite cannot push a correlated subquery down, so it pulls the source through QGIS row by row, and concurrent scans can exhaust the provider’s connection pool and wedge the run. Pushing the join into the source (a subset filter, view, or materialized view) turns the whole thing into one set-based query.

Detection only — the layer is materialized exactly as it would have been.

Parameters:

• layer (QgsVectorLayer) – The virtual layer being materialized.

• project (QgsProject) – The run’s project (resolves referenced sources to their provider).

• feedback (QgsProcessingFeedback) – Execution feedback channel.

Return type:

None

stratified_packager.processing.virtual.load_lazy_virtual(layer, feedback)

Run a lazy virtual layer’s query so it reads its rows rather than nothing (§4/§13).

A lazy definition tells the virtual provider to skip the query at construction: the layer opens valid — its CRS and geometry type come from the definition itself — but with no fields and no features until something reloads it. The flag is an authoring convenience that must not reach a package, and it survives clone() because the clone is rebuilt from the provider’s uri. Left alone, a materialized lazy layer would be written as an empty table into every stratum. The live route sheds the flag by rebuilding the definition eagerly instead (§13).

No-op for any other layer, so callers need not know what they hold.

Parameters:

• layer (QgsVectorLayer) – The layer to load — typically a freshly cloned read source, never the user’s.

• feedback (QgsProcessingFeedback) – Execution feedback channel.

Return type:

None

stratified_packager.processing.virtual.route_virtual_layers(virtuals, vectors, payloads, embedded, project, feedback)

Route virtual layers to packaged vectors (materialize) or embedded-only (live) (§4/§13).

Mutates vectors / embedded in place; the coverage set is the already-classified packaged layers. A layer routed to materialize is additionally checked for remote sources, which cost a warning but never change the routing.

Parameters:

• virtuals (list[QgsVectorLayer]) – The collected virtual provider layers.

• vectors (list[QgsVectorLayer]) – Packaged vector layers (materialized virtuals are appended).

• payloads (list[QgsMapLayer]) – Packaged payload layers (part of the coverage set).

• embedded (list[QgsMapLayer]) – Embedded-only layers (live virtuals are appended).

• project (QgsProject) – The run’s project (resolves referenced sources to their provider).

• feedback (QgsProcessingFeedback) – Execution feedback channel.

Return type:

None

stratified_packager.processing.virtual._LOCAL_PROVIDERS: Final[frozenset[str]] = frozenset({'delimitedtext', 'gdal', 'gpkg', 'gpx', 'mdal', 'memory', 'ogr', 'spatialite'})

Provider keys a virtual layer can query without leaving the machine.

Anything else — a database provider, a web service, or a nested virtual layer that may itself reach one — makes the virtual query a remote round-trip generator when materialized.