Spatial Reporting Automated Docs & Maps

Managing Global vs Local Variables in Complex Jinja2 Templates

Managing global vs local variables in complex Jinja2 templates requires explicit namespace isolation, controlled context passing, and strict adherence to Jinja2’s block-scoping rules. This technique fits directly inside the Variable Scoping in Nested Jinja Templates workflow: once you understand how context layers inherit from one another, this page shows you exactly how to keep global project metadata immutable while safely accumulating loop-scoped state such as cumulative area totals, feature counts, and per-page bounding boxes. Getting this wrong produces silent data corruption — totals that never update, CRS strings that get overwritten mid-loop, or scale bar values that bleed from one map inset into the next.

Prerequisites

  • Python 3.10+ with jinja2 installed (pip install jinja2)
  • Familiarity with Jinja2 template inheritance ({% extends %}) and block definitions
  • Understanding of how Variable Scoping in Nested Jinja Templates resolves context across include/extend boundaries
  • Spatial data in a structured format: GeoJSON feature collections, GeoPandas GeoDataFrames, or PostGIS query results serialised to Python dicts

Scope Architecture: What Goes Where

Before writing a single line of template code, decide which variables belong at each level. Mixing these is the root cause of most scoping bugs in spatial reporting pipelines.

Global vs Local Variable Tiers in Jinja2 Diagram showing three horizontal tiers: Python context at top (read-only globals: CRS, project title, author metadata), namespace() object in the middle (mutable loop state: running area total, feature counter, bbox union), and per-iteration block scope at the bottom (single-feature local values: one feature id, name, geometry type). Tier 1 — Python render() context (read-only globals) project_crs · project_title · metadata.author · base_map_url Injected once via template.render(**context); never reassigned inside the template Tier 2 — namespace() object (mutable loop state) ns.total_area · ns.feature_count · ns.bbox_union Declared above the loop; attributes survive iteration boundaries Tier 3 — per-iteration block scope (ephemeral) feature.id · feature.name · feature.area_km2 · loop.index Exists only within one {% for %} iteration; cannot assign back to Tier 1 or Tier 2 directly

Step 1 — Freeze Global State in Python

Pass only the data the template needs, structured as plain Python primitives. Keep Python-internal objects (ORM instances, GeoPandas GeoDataFrames, Shapely geometry objects) out of the Jinja2 context entirely — serialise them first.

Python
# report_engine.py
from jinja2 import Environment, FileSystemLoader, select_autoescape

env = Environment(
    loader=FileSystemLoader("./templates"),
    autoescape=select_autoescape(["html", "xml"]),
)

# Spatial data pre-serialised from a GeoDataFrame or PostGIS query.
# Precompute any geometry-derived values here, not in the template.
spatial_data: list[dict] = [
    {
        "id": "A1",
        "name": "Watershed Alpha",
        "area_km2": 142.5,
        "geometry_type": "Polygon",
        "centroid_wkt": "POINT(12.34 56.78)",
    },
    {
        "id": "B2",
        "name": "Watershed Beta",
        "area_km2": 89.3,
        "geometry_type": "Polygon",
        "centroid_wkt": "POINT(13.01 57.22)",
    },
    {
        "id": "C3",
        "name": "Watershed Gamma",
        "area_km2": 210.7,
        "geometry_type": "Polygon",
        "centroid_wkt": "POINT(11.90 55.95)",
    },
]

# Immutable project-level metadata — these are global constants inside the template.
context: dict = {
    "features": spatial_data,
    "project_crs": "EPSG:4326",
    "project_title": "Regional Hydrology Assessment",
    "metadata": {"author": "GIS Automation Team", "version": "2.1"},
}

template = env.get_template("spatial_report.html")
output: str = template.render(**context)

project_crs, project_title, and metadata are injected once and remain read-only for the entire render. Never pass mutable Python objects (lists you intend to mutate, counters, accumulators) at this level.

Step 2 — Declare Mutable State with namespace()

Jinja2’s block-scoping rule means that {% set total = total + x %} inside a {% for %} loop silently creates a new block-local variable. The outer total is never changed. The only supported escape hatch is namespace().

Jinja
{# templates/spatial_report.html #}
{% extends "base_layout.html" %}

{% block content %}
  {#
    namespace() creates an object whose attributes can be updated
    across {% for %} loop iterations. A plain {% set %} inside a loop
    is block-local and does NOT persist.
  #}
  {% set ns = namespace(total_area=0.0, feature_count=0) %}

  <table class="attribute-table">
    <thead>
      <tr>
        <th>ID</th>
        <th>Name</th>
        <th>Area (km²)</th>
        <th>Geometry</th>
      </tr>
    </thead>
    <tbody>
    {% for feature in features %}
      <tr>
        <td>{{ feature.id }}</td>
        <td>{{ feature.name }}</td>
        <td>{{ feature.area_km2 }}</td>
        <td>{{ feature.geometry_type }}</td>
      </tr>
      {# Update namespace attributes — this persists across iterations #}
      {% set ns.total_area    = ns.total_area    + feature.area_km2 %}
      {% set ns.feature_count = ns.feature_count + 1 %}
    {% endfor %}
    </tbody>
  </table>

  <div class="summary-footer">
    <p>Total Features: {{ ns.feature_count }}</p>
    <p>Aggregated Area: {{ "%.1f" | format(ns.total_area) }} km²</p>
  </div>
{% endblock %}

The contrast between the working and broken patterns is worth making explicit:

Jinja
{# BROKEN — set inside a for loop is block-scoped; outer total is never mutated #}
{% set total = 0 %}
{% for feature in features %}
  {% set total = total + feature.area_km2 %}
{% endfor %}
{{ total }}  {# always 0 #}

{# CORRECT — namespace() attributes survive loop scope boundaries #}
{% set ns = namespace(total=0) %}
{% for feature in features %}
  {% set ns.total = ns.total + feature.area_km2 %}
{% endfor %}
{{ ns.total }}  {# correct cumulative value #}

Step 3 — Pass Context Explicitly to Partial Templates

When a spatial report decomposes into {% include %} partials (map insets, legend blocks, metadata footers), each partial inherits the full parent context by default. This causes two failure modes: a partial can accidentally read a ns object it was not designed for, and adding a {% set %} inside the partial shadows a parent variable without warning.

Fix this by isolating each partial’s inputs:

Jinja
{# Option A: {% with %} block — pass only what the partial needs #}
{% for feature in features %}
  {% with inset_feature=feature, inset_crs=project_crs %}
    {% include "map_inset.html" %}
  {% endwith %}
{% endfor %}

{# Option B: macro — fully explicit parameters, isolated scope #}
{% macro render_inset(feature, crs, legend_title) %}
  <div class="map-inset" data-crs="{{ crs }}">
    <h3>{{ feature.name }}</h3>
    <p class="legend-title">{{ legend_title }}</p>
    {# Any {% set %} here is local to this macro invocation #}
  </div>
{% endmacro %}

{% for feature in features %}
  {{ render_inset(feature, project_crs, "Watershed Boundary") }}
{% endfor %}

Macros execute in their own scope. Any {% set %} inside a macro never pollutes the parent template context, making them the safest option for reusable spatial components such as scale bars, north arrows, and attribute summary panels. This pattern is covered in depth in the loop-mapping for dynamic attribute tables workflow for feature iteration patterns.

Step 4 — Precompute Geometry in Python, Not in the Template

Jinja2 is a text-rendering engine. Spatial calculations — bounding box unions, coordinate reprojections, scale bar pixel lengths, centroid lookups — belong in Python where you have full access to shapely, pyproj, and geopandas.

Python
# Precompute all geometry-derived values before building the context.
import geopandas as gpd
from shapely.ops import unary_union

gdf = gpd.read_file("watersheds.gpkg")
gdf = gdf.to_crs("EPSG:4326")

# Total bounding box — pass as a plain tuple, not a Shapely object.
total_bbox: tuple[float, float, float, float] = tuple(
    unary_union(gdf.geometry).bounds
)

# Per-feature centroid as WKT string — no Shapely in the template.
features = [
    {
        "id": row["id"],
        "name": row["name"],
        "area_km2": round(row.geometry.area / 1e6, 2),
        "centroid_wkt": row.geometry.centroid.wkt,
    }
    for _, row in gdf.iterrows()
]

context = {
    "features": features,
    "total_bbox": total_bbox,   # (minx, miny, maxx, maxy)
    "project_crs": "EPSG:4326",
    "project_title": "Regional Hydrology Assessment",
}

Passing geometry objects into the Jinja2 context and calling .area or .centroid inside the template is an anti-pattern: it forces spatial logic into the rendering layer, breaks template portability, and makes testing much harder.

Step 5 — Validate Context Boundaries During Development

Use the {% debug %} extension (from jinja2.ext.debug) or a custom filter to dump the active context at any point in the template. This quickly reveals where variables are being shadowed or inherited unexpectedly.

Python
from jinja2 import Environment, FileSystemLoader

env = Environment(
    loader=FileSystemLoader("./templates"),
    extensions=["jinja2.ext.debug"],  # enables {% debug %} tag
)
Jinja
{# Place {% debug %} anywhere inside the template to dump current context #}
{% for feature in features %}
  {% debug %}   {# dumps the full context dict at this iteration point #}
  {{ feature.name }}
{% endfor %}

Remove {% debug %} tags before production. For CI validation, write an assertion against the rendered output instead:

Python
import re

output: str = template.render(**context)

# Verify the cumulative total rendered correctly.
match = re.search(r"Aggregated Area:\s*([\d.]+)\s*km", output)
assert match, "Summary footer not found in rendered output"
rendered_total = float(match.group(1))
expected_total = sum(f["area_km2"] for f in context["features"])
assert abs(rendered_total - expected_total) < 0.1, (
    f"Area total mismatch: got {rendered_total}, expected {expected_total}"
)

Key Parameters / Configuration Reference

Parameter Type Default Effect
namespace(**kwargs) Jinja2 built-in — Creates a mutable object; attributes can be updated inside loops with {% set ns.attr = value %}
{% include "x.html" without context %} Jinja2 directive inherits context Renders the partial with an empty context; pass variables explicitly via {% with %}
{% with key=value %}...{% endwith %} Jinja2 block — Creates a temporary local scope; variables defined inside do not leak out
extensions=["jinja2.ext.debug"] Environment kwarg [] Enables {% debug %} tag to dump active context during development
autoescape=select_autoescape(["html"]) Environment kwarg False Auto-escapes HTML special characters in variable output; always enable for HTML/XML reports

Common Pitfalls

  • Silently reset accumulators. Using {% set total = total + x %} inside {% for %} looks correct but always resets. Replace with {% set ns = namespace(total=0) %} above the loop and {% set ns.total = ns.total + x %} inside it. There is no warning when this happens — the output simply shows the wrong value.

  • Global variable shadowing in includes. A partial that does {% set project_crs = "EPSG:3857" %} appears to change the CRS for that section, but actually creates a local variable. Other parts of the template that read project_crs still see the original. Use an unambiguous local name ({% set inset_crs = "EPSG:3857" %}) to make the intention explicit.

  • Passing Shapely or GeoDataFrame objects into the context. These objects are not JSON-serialisable and carry spatial methods that do not belong in a templating context. Serialise to dicts or plain numeric primitives in Python before calling template.render().

  • Shared mutable Python objects across multiple render calls. If your pipeline renders several report variants in a loop, pass a fresh context dict to each render() call. Jinja2 caches compiled templates but does not deep-copy mutable Python objects you pass in. A list mutated during one render will carry those mutations into the next.

Verification

After rendering, run this assertion block to confirm the summary footer values match a Python-computed reference:

Python
import re
from jinja2 import Environment, FileSystemLoader

env = Environment(loader=FileSystemLoader("./templates"))
template = env.get_template("spatial_report.html")
output: str = template.render(**context)

expected_count: int = len(context["features"])
expected_area: float = sum(f["area_km2"] for f in context["features"])

count_match = re.search(r"Total Features:\s*(\d+)", output)
area_match  = re.search(r"Aggregated Area:\s*([\d.]+)", output)

assert count_match, "Feature count not found in output"
assert area_match,  "Area total not found in output"
assert int(count_match.group(1)) == expected_count
assert abs(float(area_match.group(1)) - expected_area) < 0.1
print("Render assertions passed.")

For CI pipelines, add this as a pytest test in your template test suite so that any refactor to the template or context-building code immediately surfaces a regression.