refactor(provider): drop matplotlib.use("Agg") for the Figure API

Use matplotlib's object-oriented Figure class directly instead of
pyplot. Figure.savefig works without an interactive backend, so the
module-level matplotlib.use("Agg") call -- and the E402 noqa it forced
on every following import -- are no longer needed. Library code now
touches no matplotlib global state.

test: move matplotlib backend selection into conftest.py

The Agg backend is now selected once in tests/conftest.py, before any
test module is imported, instead of via a module-level matplotlib.use
call in test_ref_tutorials.py. The test file's imports go back to a
clean sorted block with no E402 noqa.

Author: lewisjared

src/ref_tutorials/provider.py

@@ -18,29 +18,28 @@
 
 import importlib.metadata
 from pathlib import Path
-from typing import Any
 
-import matplotlib
-
-matplotlib.use("Agg")  # Diagnostics run headless; no display is available.
-
-import matplotlib.pyplot as plt  # noqa: E402
-import xarray as xr  # noqa: E402
-from climate_ref_core.constraints import (  # noqa: E402
+import xarray as xr
+from climate_ref_core.constraints import (
     AddSupplementaryDataset,
     RequireContiguousTimerange,
 )
-from climate_ref_core.datasets import FacetFilter, SourceDatasetType  # noqa: E402
-from climate_ref_core.diagnostics import (  # noqa: E402
+from climate_ref_core.datasets import FacetFilter, SourceDatasetType
+from climate_ref_core.diagnostics import (
     DataRequirement,
     Diagnostic,
     ExecutionDefinition,
     ExecutionResult,
 )
-from climate_ref_core.metric_values.typing import SeriesMetricValue  # noqa: E402
-from climate_ref_core.providers import DiagnosticProvider  # noqa: E402
-from climate_ref_core.pycmec.metric import CMECMetric  # noqa: E402
-from climate_ref_core.pycmec.output import CMECOutput, OutputCV  # noqa: E402
+from climate_ref_core.metric_values.typing import SeriesMetricValue
+from climate_ref_core.providers import DiagnosticProvider
+from climate_ref_core.pycmec.metric import CMECMetric
+from climate_ref_core.pycmec.output import CMECOutput, OutputCV
+
+# The object-oriented matplotlib API. Using Figure directly -- rather than
+# pyplot -- means this library module touches no global state and needs no
+# interactive backend, so there is no matplotlib.use("Agg") call.
+from matplotlib.figure import Figure
 
 #: Name of the NetCDF file the diagnostic writes into its output directory.
 _OUTPUT_FILENAME = "annual_mean_global_mean_tas.nc"
@@ -115,18 +114,19 @@ def make_figures(ds: xr.Dataset, output_directory: Path) -> dict[str, Path]:
     tas = ds["tas"].values
 
     timeseries_path = output_directory / _TIMESERIES_PLOT
-    fig, ax = plt.subplots(figsize=(7, 4))
+    fig = Figure(figsize=(7, 4))
+    ax = fig.subplots()
     ax.plot(years, tas, marker="o", color="#1f77b4")
     ax.set_xlabel("Year")
     ax.set_ylabel("Global-mean tas (K)")
     ax.set_title("Annual-mean global-mean near-surface air temperature")
     fig.tight_layout()
     fig.savefig(timeseries_path, dpi=150)
-    plt.close(fig)
 
     anomaly_path = output_directory / _ANOMALY_PLOT
     anomaly = tas - tas.mean()
-    fig, ax = plt.subplots(figsize=(7, 4))
+    fig = Figure(figsize=(7, 4))
+    ax = fig.subplots()
     colors = ["#d62728" if a >= 0 else "#1f77b4" for a in anomaly]
     ax.bar(years, anomaly, color=colors)
     ax.axhline(0, color="#444444", linewidth=0.8)
@@ -135,7 +135,6 @@ def make_figures(ds: xr.Dataset, output_directory: Path) -> dict[str, Path]:
     ax.set_title("Annual-mean tas anomaly relative to the period mean")
     fig.tight_layout()
     fig.savefig(anomaly_path, dpi=150)
-    plt.close(fig)
 
     return {
         "Annual-mean global-mean tas timeseries": timeseries_path,
@@ -186,13 +185,11 @@ def _series_values(
 class AnnualMeanGlobalMeanTas(Diagnostic):
     """Annual-mean, global-mean near-surface air temperature.
 
-    A minimal custom diagnostic for the tutorials. It requires CMIP6 ``tas``
-    data, and pulls in the matching ``areacella`` cell-area field as a
+    A minimal custom diagnostic for the tutorials.
+    It requires CMIP6 ``tas`` data, and pulls in the matching ``areacella`` cell-area field as a
     supplementary dataset so the global mean can be area-weighted.
 
-    Its execution registers scalar metric values, a series metric value, and
-    two figures -- a representative cross-section of what a real diagnostic
-    produces.
+    Its execution registers scalar metric values, a series metric value, and two figures.
     """
 
     name = "Annual Mean Global Mean Temperature"
@@ -202,10 +199,13 @@ class AnnualMeanGlobalMeanTas(Diagnostic):
         (
             DataRequirement(
                 source_type=SourceDatasetType.CMIP6,
+                # We only look at each
                 filters=(FacetFilter(facets={"variable_id": ("tas",)}),),
                 group_by=("source_id", "experiment_id", "variant_label"),
                 constraints=(
+                    # Ensure that we have a contiguous time range to compute the annual mean from
                     RequireContiguousTimerange(group_by=("instance_id",)),
+                    # Add the matching areacella dataset as a supplementary dataset
                     AddSupplementaryDataset.from_defaults(
                         "areacella", SourceDatasetType.CMIP6
                     ),
@@ -225,6 +225,7 @@ class AnnualMeanGlobalMeanTas(Diagnostic):
     def execute(self, definition: ExecutionDefinition) -> None:
         """Compute the diagnostic: write the output NetCDF and the figures."""
         input_datasets = definition.datasets[SourceDatasetType.CMIP6]
+
         result = calculate_annual_mean_global_mean(input_datasets.path.to_list())
         if "time_bnds" in result:
             result = result.drop_vars("time_bnds")
@@ -235,21 +236,17 @@ def execute(self, definition: ExecutionDefinition) -> None:
     def build_execution_result(self, definition: ExecutionDefinition) -> ExecutionResult:
         """Package the output into an :class:`ExecutionResult`.
 
-        ``execute`` has already written the NetCDF file and the figures. Here we
-        register the scalar metric values, the series metric value, and the
-        figures so the REF records them.
+        ``execute`` has already written the NetCDF file and the figures.
+
+        Here we register the scalar metric values, the series metric value,
+        and the figures so the REF records them.
         """
         time_coder = xr.coders.CFDatetimeCoder(use_cftime=True)
         ds = xr.open_dataset(
             definition.output_directory / _OUTPUT_FILENAME, decode_times=time_coder
         )
 
         selectors = definition.datasets[SourceDatasetType.CMIP6].selector_dict()
-        input_selectors: dict[str, Any] = {
-            "source_id": selectors["source_id"],
-            "experiment_id": selectors["experiment_id"],
-            "variant_label": selectors["variant_label"],
-        }
 
         # Register the figures written by execute().
         output_bundle = CMECOutput.create_template()
@@ -265,14 +262,14 @@ def build_execution_result(self, definition: ExecutionDefinition) -> ExecutionRe
                 OutputCV.FILENAME.value: relative_path,
                 OutputCV.LONG_NAME.value: caption,
                 OutputCV.DESCRIPTION.value: caption,
-                OutputCV.DIMENSIONS.value: input_selectors,
+                OutputCV.DIMENSIONS.value: selectors,
             }
 
         return ExecutionResult.build_from_output_bundle(
             definition,
             cmec_output_bundle=output_bundle,
-            cmec_metric_bundle=_scalar_metric_bundle(ds, input_selectors),
-            series=_series_values(ds, input_selectors),
+            cmec_metric_bundle=_scalar_metric_bundle(ds, selectors),
+            series=_series_values(ds, selectors),
         )
 
 

tests/conftest.py

@@ -0,0 +1,6 @@
+"""Shared fixtures"""
+import matplotlib
+
+# The plotting helpers use pyplot.
+# Force a non-interactive backend so the figure-producing tests run headless
+matplotlib.use("Agg")

tests/test_ref_tutorials.py

@@ -1,30 +1,22 @@
-"""Unit tests for the ``ref_tutorials`` helper package.
-
-These tests cover the *observable contract* of the helper functions, not their
-internals. They do not require network access or the generated API client.
-"""
+"""Unit tests for the ``ref_tutorials`` helper package. """
 
 from __future__ import annotations
 
 from dataclasses import dataclass, field
 
 import matplotlib
+import pandas as pd
+import pytest
 
-matplotlib.use("Agg")  # Headless backend for CI.
-
-import pandas as pd  # noqa: E402
-import pytest  # noqa: E402
-
-from ref_tutorials import (  # noqa: E402
+from ref_tutorials import (
     metric_values_to_dataframe,
     model_comparison_figure,
     save_figure,
     set_publication_style,
 )
-from ref_tutorials.plotting import PUBLICATION_RCPARAMS  # noqa: E402
+from ref_tutorials.plotting import PUBLICATION_RCPARAMS
 
-# --- Test doubles -----------------------------------------------------------
-# Minimal stand-ins for the metric value objects returned by climate_ref_client.
+# The Agg backend is selected in conftest.py before this module is imported.
 
 
 @dataclass
@@ -42,8 +34,6 @@ def make(cls, value: float, **dims: object) -> _MetricValue:
         return cls(value=value, dimensions=_Dimensions(additional_properties=dict(dims)))
 
 
-# --- metric_values_to_dataframe ---------------------------------------------
-
 
 def test_metric_values_to_dataframe_flattens_dimensions():
     values = [
@@ -79,8 +69,6 @@ def test_metric_values_to_dataframe_empty_input():
     assert df.empty
 
 
-# --- set_publication_style --------------------------------------------------
-
 
 def test_set_publication_style_applies_rcparams():
     matplotlib.rcParams["font.size"] = 99  # Pollute first.
@@ -90,8 +78,6 @@ def test_set_publication_style_applies_rcparams():
     assert matplotlib.rcParams["font.size"] == PUBLICATION_RCPARAMS["font.size"]
 
 
-# --- model_comparison_figure ------------------------------------------------
-
 
 def test_model_comparison_figure_returns_fig_and_axes():
     df = pd.DataFrame(
@@ -122,8 +108,6 @@ def test_model_comparison_figure_aggregates_ensemble_members():
     assert len(ax.patches) == 2
 
 
-# --- save_figure ------------------------------------------------------------
-
 
 def test_save_figure_writes_png_and_pdf(tmp_path):
     df = pd.DataFrame({"source_id": ["ModelA"], "value": [1.0]})