A Complete PyQGIS Map Pipeline: Settings, Functions and a Log File

part-c/
  bengaluru_layout_start.qgz     the project
  data/                          the input data
  templates/                     the template (.qpt)
  scripts/                       the scripts
  output/                        everything the script writes
    pipeline/                    the PDFs
    pipeline/logs/               the log file

# Lesson 7: put it together as a pipeline: settings in one place, a log file, small functions, and a summary.
import logging
import re
from pathlib import Path
from qgis.core import (
    Qgis,
    QgsProject,
    QgsPrintLayout,
    QgsReadWriteContext,
    QgsLayoutItemMap,
    QgsLayoutItemLabel,
    QgsLayoutExporter,
    QgsExpressionContextUtils,
)
from qgis.PyQt.QtXml import QDomDocument

# Step 1: all the settings that might change, in one dictionary. The rest of the script only reads them.
config = {
    "regions_layer": "Parks and lakes, share of area (%)",
    "name_field": "short",
    "title_field": "title",
    "template": "templates/parks_and_lakes_template.qpt",
    "padding": 1.15,
    "output_folder": "output/pipeline",
}
REQUIRED_ITEMS = {"main_map": QgsLayoutItemMap, "map_title": QgsLayoutItemLabel}

project = QgsProject.instance()
folder = Path(project.homePath())
output_folder = folder / config["output_folder"]
(output_folder / "logs").mkdir(parents=True, exist_ok=True)

# Step 2: a log file. A dedicated logger is used, and old handlers are removed, so that running the
# script twice does not write every line twice.
logger = logging.getLogger("map_series")
logger.setLevel(logging.INFO)
for handler in list(logger.handlers):
    handler.close()
    logger.removeHandler(handler)
file_handler = logging.FileHandler(output_folder / "logs" / "map_generation.log", mode="w", encoding="utf-8")
file_handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(message)s"))
logger.addHandler(file_handler)

# Step 3: small functions, each doing one job
def validate_inputs():
    """Return the regions layer and the template document, or raise an error that says what is wrong."""
    matches = project.mapLayersByName(config["regions_layer"])
    if not matches:
        raise ValueError(f"Layer not found: {config['regions_layer']}")
    layer = matches[0]
    if not layer.isValid():
        raise ValueError(f"Layer is not valid: {config['regions_layer']}")
    for field in (config["name_field"], config["title_field"]):
        if layer.fields().indexFromName(field) == -1:
            raise ValueError(f"Field not found: {field}")
    template_path = folder / config["template"]
    if not template_path.exists():
        raise FileNotFoundError(f"Template not found: {template_path}")
    document = QDomDocument()
    ok, message, line, column = document.setContent(template_path.read_text(encoding="utf-8"))
    if not ok:
        raise ValueError(f"Template is not valid XML (line {line}): {message}")
    return layer, document


def make_layout(document):
    layout = QgsPrintLayout(project)
    layout.loadFromTemplate(document, QgsReadWriteContext(), True)
    for item_id, item_class in REQUIRED_ITEMS.items():
        if not isinstance(layout.itemById(item_id), item_class):
            raise ValueError(f"The template has no usable item with the ID {item_id!r}")
    return layout


def safe_filename(value):
    return re.sub(r'[<>:"/\\|?*]', "_", str(value).strip()) or "unnamed"


def export_layout(layout, path):
    result = QgsLayoutExporter(layout).exportToPdf(str(path), QgsLayoutExporter.PdfExportSettings())
    if result != QgsLayoutExporter.Success:
        raise RuntimeError(f"Export failed ({result}): {path.name}")
    if not path.exists() or path.stat().st_size == 0:
        raise RuntimeError(f"File is missing or empty: {path.name}")
    return path

# Step 4: the pipeline. Anything unexpected is written to the log, and the script carries on with the next map.
results = []
logger.info("Map generation started. QGIS %s", Qgis.version())
try:
    regions, document = validate_inputs()
    logger.info("Inputs are valid: %s features", regions.featureCount())

    seen = set()
    for feature in sorted(regions.getFeatures(), key=lambda f: f[config["name_field"]]):
        name = feature[config["name_field"]]
        filename = safe_filename(name) + ".pdf"
        try:
            if filename in seen:
                raise ValueError(f"Duplicate file name: {filename}")
            seen.add(filename)
            layout = make_layout(document)
            layout.itemById("map_title").setText(feature[config["title_field"]])
            QgsExpressionContextUtils.setProjectVariable(project, "focus_name", name)
            extent = feature.geometry().boundingBox()
            extent.scale(config["padding"])
            layout.itemById("main_map").zoomToExtent(extent)
            export_layout(layout, output_folder / filename)
            logger.info("Exported %s", filename)
            results.append((name, "ok"))
        except Exception as error:
            logger.exception("Map %s failed", name)
            results.append((name, f"failed: {error}"))
except Exception:
    logger.exception("Map generation stopped because of an error")
    raise
finally:
    logger.info("Map generation finished.")

# Step 5: a summary for the person running the script
failed = [r for r in results if r[1] != "ok"]
print(f"{len(results) - len(failed)} of {len(results)} maps exported to {output_folder}")
for name, status in results:
    print(f"  {name}: {status}")
print("Log file:", output_folder / "logs" / "map_generation.log")

5 of 5 maps exported to ...\part-c\output\pipeline
  Central: ok
  East: ok
  North: ok
  South: ok
  West: ok
Log file: ...\part-c\output\pipeline\logs\map_generation.log

INFO Map generation started. QGIS 3.44.13-Solothurn
INFO Inputs are valid: 5 features
INFO Exported Central.pdf
INFO Exported East.pdf
INFO Exported North.pdf
INFO Exported South.pdf
INFO Exported West.pdf
INFO Map generation finished.