Working with QgsProject and Layer Registry

"""Standalone script bootstrap — required before any QgsProject access."""

from __future__ import annotations

import sys
from qgis.core import QgsApplication, QgsProject


def bootstrap_qgis(prefix_path: str = "/usr") -> QgsApplication:
    """
    Initialize the QGIS application context for headless execution.

    Args:
        prefix_path: QGIS installation prefix (e.g. '/usr' on Ubuntu,
                     '/Applications/QGIS.app/Contents/MacOS' on macOS).

    Returns:
        Initialized QgsApplication instance. Caller must keep a reference
        for the duration of the script to prevent premature shutdown.
    """
    QgsApplication.setPrefixPath(prefix_path, True)
    app = QgsApplication(sys.argv, False)  # False = no GUI
    app.initQgis()
    return app


app = bootstrap_qgis()
project = QgsProject.instance()

print(f"Title  : {project.title()!r}")
print(f"File   : {project.fileName()!r}")
print(f"CRS    : {project.crs().authid()!r}")

"""Production layer loading with provider validation."""

from __future__ import annotations

from pathlib import Path
from qgis.core import (
    QgsVectorLayer,
    QgsRasterLayer,
    QgsProject,
)


def load_vector(path: str | Path, name: str) -> QgsVectorLayer:
    """
    Load a vector file via the OGR provider and register it with the project.

    Args:
        path: Absolute path to any GDAL/OGR-supported format (.gpkg, .shp, etc.).
        name: Display name shown in the Layers panel.

    Returns:
        The registered QgsVectorLayer.

    Raises:
        RuntimeError: If the OGR provider cannot open the source.
    """
    layer = QgsVectorLayer(str(path), name, "ogr")
    if not layer.isValid():
        raise RuntimeError(
            f"OGR provider rejected '{path}'. "
            "Check the path, file permissions, and GDAL driver availability."
        )
    # addMapLayer registers the layer AND adds it to the root of QgsLayerTree.
    # Pass addToLegend=False to register without touching the tree (headless use).
    QgsProject.instance().addMapLayer(layer, addToLegend=True)
    return layer


def load_raster(path: str | Path, name: str) -> QgsRasterLayer:
    """
    Load a raster file via the GDAL provider and register it with the project.

    Args:
        path: Absolute path to a GDAL-readable raster (.tif, .img, etc.).
        name: Display name shown in the Layers panel.

    Returns:
        The registered QgsRasterLayer.

    Raises:
        RuntimeError: If the GDAL provider cannot open the source.
    """
    layer = QgsRasterLayer(str(path), name, "gdal")
    if not layer.isValid():
        raise RuntimeError(f"GDAL provider rejected '{path}'.")
    QgsProject.instance().addMapLayer(layer)
    return layer


project = QgsProject.instance()

boundaries = load_vector("/data/admin_boundaries.gpkg", "Administrative Boundaries")
dem = load_raster("/data/dem_30m.tif", "Digital Elevation Model")

print(f"Registered layers: {list(project.mapLayers().keys())}")

"""Registry query patterns and safe removal."""

from __future__ import annotations

from typing import Optional
from qgis.core import QgsProject, QgsVectorLayer, QgsMapLayer


def get_layer_by_name(name: str) -> Optional[QgsMapLayer]:
    """
    Return the first registered layer matching the given display name.

    mapLayersByName() returns a list; names are NOT unique identifiers.
    If duplicates are possible, iterate all results and apply additional checks.

    Args:
        name: Display name to search for.

    Returns:
        The first matching layer, or None if not found.
    """
    results = QgsProject.instance().mapLayersByName(name)
    return results[0] if results else None


def remove_layer_safely(layer_id: str) -> bool:
    """
    Remove a layer from the registry, guarding against double-removal.

    IMPORTANT: Do not call this inside a for-loop over project.mapLayers().
    Collect IDs first, then remove. See the iteration note below.

    Args:
        layer_id: The unique string ID obtained from layer.id().

    Returns:
        True if the layer was present and removed, False otherwise.
    """
    project = QgsProject.instance()
    if project.mapLayer(layer_id) is None:
        return False
    project.removeMapLayer(layer_id)
    return True


# --- Safe batch removal -------------------------------------------------------
project = QgsProject.instance()

# Collect IDs before iterating; mutating mapLayers() during iteration raises
# RuntimeError due to dict size change mid-loop.
ids_to_remove = [
    lid for lid, lyr in project.mapLayers().items()
    if lyr.name().startswith("temp_")
]
for lid in ids_to_remove:
    remove_layer_safely(lid)

# --- Diagnostic summary -------------------------------------------------------
for layer_id, layer in project.mapLayers().items():
    crs_id = layer.crs().authid()
    print(f"{layer.name():<40} id={layer_id[:8]}…  crs={crs_id}")

"""Project persistence with error handling."""

from __future__ import annotations

from pathlib import Path
from qgis.core import QgsProject


def save_project(output_path: str | Path) -> None:
    """
    Persist the current project to disk.

    Args:
        output_path: Target .qgz or .qgs file path.

    Raises:
        IOError: If QgsProject.write() returns False (disk full, permissions, etc.).
    """
    project = QgsProject.instance()
    project.setDirty(True)  # Ensure GUI save indicator reflects the change.

    if not project.write(str(output_path)):
        raise IOError(
            f"QgsProject.write() failed for '{output_path}'. "
            "Check disk space and write permissions."
        )
    print(f"Project saved to {output_path}")


def clear_project() -> None:
    """
    Remove all layers and reset project settings without exiting the application.
    Equivalent to File > New in the GUI.
    """
    QgsProject.instance().clear()


save_project("/output/automation_project.qgz")

"""Batch layer registration — one tree refresh instead of N."""

from __future__ import annotations

from pathlib import Path
from typing import Sequence
from qgis.core import QgsVectorLayer, QgsProject


def batch_load_vectors(
    paths: Sequence[str | Path],
    name_prefix: str = "",
) -> list[QgsVectorLayer]:
    """
    Load multiple vector files and register them in a single batch operation.

    Args:
        paths: Sequence of absolute file paths to GDAL/OGR-readable sources.
        name_prefix: Optional prefix applied to each layer's display name.

    Returns:
        List of successfully registered QgsVectorLayer objects.

    Raises:
        RuntimeError: If any source fails the isValid() check.
    """
    layers: list[QgsVectorLayer] = []
    for path in paths:
        name = f"{name_prefix}{Path(path).stem}" if name_prefix else Path(path).stem
        lyr = QgsVectorLayer(str(path), name, "ogr")
        if not lyr.isValid():
            raise RuntimeError(f"Provider validation failed for '{path}'")
        layers.append(lyr)

    # addMapLayers triggers ONE QgsLayerTree update rather than one per layer.
    # Pass addToLegend=False for pure headless pipelines.
    QgsProject.instance().addMapLayers(layers, addToLegend=True)
    return layers

from qgis.core import QgsVectorLayer, QgsProject

layer = QgsVectorLayer("/data/parcels.gpkg", "Parcels", "ogr")
# Register with the ID hash table but bypass the GUI layer tree entirely.
registered = QgsProject.instance().addMapLayer(layer, addToLegend=False)

# If you later need the layer in the tree (e.g., for map rendering):
root = QgsProject.instance().layerTreeRoot()
root.addLayer(registered)

from qgis.core import QgsProject

project = QgsProject.instance()

# Write a custom variable (persisted to .qgz)
project.writeEntry("my_plugin", "last_run_epoch", "1719187200")
project.writeEntry("my_plugin", "output_crs", "EPSG:3857")

# Read it back (returns a tuple: (value, success_bool))
last_run, ok = project.readEntry("my_plugin", "last_run_epoch", "")
if ok:
    print(f"Last run: {last_run}")

# QGIS expression: @my_plugin_last_run_epoch