Merge branch 'geo-bridge' of github.com:HGWright/iris into geo-bridge

* 'geo-bridge' of github.com:HGWright/iris: (41 commits)
  Updated lock files.
  [pre-commit.ci] auto fixes from pre-commit.com hooks
  Advertise structured_um_loading performance regression.
  [pre-commit.ci] pre-commit autoupdate
  Updated environment lockfiles
  [pre-commit.ci] auto fixes from pre-commit.com hooks
  [pre-commit.ci] pre-commit autoupdate
  Make the bugfix panel OPEN.
  What's New patch.
  What's New patch.
  Bump scitools/workflows from 2024.03.1 to 2024.03.3
  Bump scitools/workflows from 2024.03.0 to 2024.03.1
  Bump scitools/workflows from 2024.02.2 to 2024.03.0
  Fix usage of map_blocks in AreaWeighted and elsewhere (SciTools#5767)
  Lazy rolling_window (SciTools#5775)
  whatsnew update for 3.8.0 (SciTools#5793)
  Bump scitools/workflows from 2024.02.1 to 2024.02.2 (SciTools#5792)
  DOCS: Add whatsnew for recent PRs (SciTools#5789)
  ASV custom build command and file-based benchmark triggers (SciTools#5776)
  DOCS: Enable numpydoc validation pre-commit hook (SciTools#5762)
  ...

Author: HGWright

.github/labeler.yml

@@ -0,0 +1,9 @@
+# benchmark_this automatically triggers the benchmark workflow when added by
+#  a user. No triggering happens when GitHub Actions adds the label (this
+#  avoids security vulnerabilities), so alternative triggers for the below
+#  files are therefore included in workflows/benchmarks_run.yml. Automatic
+#  labelling is still included here to make it easier to search pull requests,
+#  and to reinforce the culture of using this label.
+benchmark_this:
+- changed-files:
+  - any-glob-to-any-file: ['requirements/locks/*.lock', "setup.py"]

.github/pull_request_template.md

@@ -7,3 +7,8 @@
 
 ---
 [Consult Iris pull request check list]( https://scitools-iris.readthedocs.io/en/latest/developers_guide/contributing_pull_request_checklist.html)
+
+---
+Add any of the below labels to trigger actions on this PR:
+
+- https://github.com/SciTools/iris/labels/benchmark_this

.github/workflows/benchmarks_run.yml

@@ -16,15 +16,46 @@ on:
         required: false
         type: string
   pull_request:
-    types: [labeled]
+    # Add the `labeled` type to the default list.
+    types: [labeled, opened, synchronize, reopened]
 
 jobs:
+  pre-checks:
+    runs-on: ubuntu-latest
+    if: github.repository == 'SciTools/iris'
+    outputs:
+      overnight: ${{ steps.overnight.outputs.check }}
+      branch: ${{ steps.branch.outputs.check }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+      - id: files-changed
+        uses: marceloprado/has-changed-path@df1b7a3161b8fb9fd8c90403c66a9e66dfde50cb
+        with:
+          # SEE ALSO .github/labeler.yml .
+          paths: requirements/locks/*.lock setup.py
+      - id: overnight
+        if: github.event_name != 'pull_request'
+        run: echo "check=true" >> "$GITHUB_OUTPUT"
+      - id: branch
+        if: >
+          github.event_name == 'pull_request'
+          &&
+          (
+            steps.files-changed.outputs.changed == 'true'
+            ||
+            github.event.label.name == 'benchmark_this'
+          )
+        run: echo "check=true" >> "$GITHUB_OUTPUT"
+
+
   benchmark:
-    if: >
-      github.repository == 'SciTools/iris' && 
-      (github.event_name != 'pull_request' || 
-      github.event.label.name == 'benchmark_this')
     runs-on: ubuntu-latest
+    needs: pre-checks
+    if: >
+      needs.pre-checks.outputs.overnight == 'true' ||
+      needs.pre-checks.outputs.branch == 'true'
 
     env:
       IRIS_TEST_DATA_LOC_PATH: benchmarks
@@ -76,7 +107,7 @@ jobs:
           echo "OVERRIDE_TEST_DATA_REPOSITORY=${GITHUB_WORKSPACE}/${IRIS_TEST_DATA_PATH}/test_data" >> $GITHUB_ENV
 
       - name: Benchmark this pull request
-        if: ${{ github.event.label.name == 'benchmark_this' }}
+        if: needs.pre-checks.outputs.branch == 'true'
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PR_NUMBER: ${{ github.event.number }}
@@ -85,7 +116,7 @@ jobs:
 
       - name: Run overnight benchmarks
         id: overnight
-        if: ${{ github.event_name != 'pull_request' }}
+        if: needs.pre-checks.outputs.overnight == 'true'
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |

.github/workflows/ci-manifest.yml

@@ -23,4 +23,4 @@ concurrency:
 jobs:
   manifest:
     name: "check-manifest"
-    uses: scitools/workflows/.github/workflows/ci-manifest.yml@2024.02.0
+    uses: scitools/workflows/.github/workflows/ci-manifest.yml@2024.03.3

.github/workflows/labeler.yml

@@ -0,0 +1,15 @@
+# Reference
+#   - https://github.com/actions/labeler
+
+name: "Pull Request Labeler"
+on:
+- pull_request_target
+
+jobs:
+  labeler:
+    permissions:
+      contents: read
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/labeler@v5

.github/workflows/refresh-lockfiles.yml

@@ -14,5 +14,5 @@ on:
 
 jobs:
   refresh_lockfiles:
-    uses: scitools/workflows/.github/workflows/refresh-lockfiles.yml@2024.02.0
+    uses: scitools/workflows/.github/workflows/refresh-lockfiles.yml@2024.03.3
     secrets: inherit

.pre-commit-config.yaml

@@ -29,7 +29,7 @@ repos:
     -   id: no-commit-to-branch
 
 -   repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.2.1"
+    rev: "v0.3.4"
     hooks:
     -   id: ruff
         types: [file, python]
@@ -61,3 +61,10 @@ repos:
     hooks:
     -   id: sort-all
         types: [file, python]
+
+-   repo: https://github.com/numpy/numpydoc
+    rev: v1.7.0rc0
+    hooks:
+      - id: numpydoc-validation
+        exclude: "^lib/iris/tests/|docs/gallery_code/"
+        types: [file, python]

benchmarks/asv.conf.json

@@ -6,6 +6,10 @@
     "environment_type": "conda-delegated",
     "show_commit_url": "https://github.com/scitools/iris/commit/",
     "branches": ["upstream/main"],
+    "build_command": [
+        "python setup.py build",
+        "python -mpip wheel --no-deps -w {build_cache_dir} {build_dir}"
+    ],
 
     "benchmark_dir": "./benchmarks",
     "env_dir": ".asv/env",

benchmarks/asv_delegated_conda.py

@@ -47,17 +47,15 @@ def __init__(
 
         Parameters
         ----------
-        conf : Config instance
-
+        conf : Config
+            Config instance.
         python : str
             Version of Python.  Must be of the form "MAJOR.MINOR".
-
         requirements : dict
             Dictionary mapping a PyPI package name to a version
             identifier string.
-
         tagged_env_vars : dict
-            Environment variables, tagged for build vs. non-build
+            Environment variables, tagged for build vs. non-build.
 
         """
         ignored = ["`python`"]

benchmarks/benchmarks/__init__.py

@@ -3,18 +3,20 @@
 # This file is part of Iris and is released under the BSD license.
 # See LICENSE in the root of the repository for full licensing details.
 """Common code for benchmarks."""
+
 from os import environ
 import resource
 
 ARTIFICIAL_DIM_SIZE = int(10e3)  # For all artificial cubes, coords etc.
 
 
 def disable_repeat_between_setup(benchmark_object):
-    """Benchmarks where object persistence would be inappropriate (decorator).
+    """Benchmark where object persistence would be inappropriate (decorator).
 
     E.g:
-        * Benchmarking data realisation
-        * Benchmarking Cube coord addition
+
+    * Benchmarking data realisation
+    * Benchmarking Cube coord addition
 
     Can be applied to benchmark classes/methods/functions.
 
@@ -107,14 +109,15 @@ def _wrapper(*args, **kwargs):
 
 
 def on_demand_benchmark(benchmark_object):
-    """Disables these benchmark(s) unless ON_DEMAND_BENCHARKS env var is set.
+    """Disable these benchmark(s) unless ON_DEMAND_BENCHARKS env var is set.
 
     This is a decorator.
 
     For benchmarks that, for whatever reason, should not be run by default.
     E.g:
-        * Require a local file
-        * Used for scalability analysis instead of commit monitoring.
+
+    * Require a local file
+    * Used for scalability analysis instead of commit monitoring.
 
     Can be applied to benchmark classes/methods/functions.
 

benchmarks/benchmarks/cperf/__init__.py

@@ -9,6 +9,7 @@
 Files available from the UK Met Office:
   moo ls moose:/adhoc/projects/avd/asv/data_for_nightly_tests/
 """
+
 import numpy as np
 
 from iris import load_cube

benchmarks/benchmarks/cperf/equality.py

@@ -3,6 +3,7 @@
 # This file is part of Iris and is released under the BSD license.
 # See LICENSE in the root of the repository for full licensing details.
 """Equality benchmarks for the CPerf scheme of the UK Met Office's NG-VAT project."""
+
 from .. import on_demand_benchmark
 from . import SingleDiagnosticMixin
 

benchmarks/benchmarks/cperf/load.py

@@ -3,6 +3,7 @@
 # This file is part of Iris and is released under the BSD license.
 # See LICENSE in the root of the repository for full licensing details.
 """File loading benchmarks for the CPerf scheme of the UK Met Office's NG-VAT project."""
+
 from .. import on_demand_benchmark
 from . import SingleDiagnosticMixin
 

benchmarks/benchmarks/experimental/ugrid/regions_combine.py

@@ -16,6 +16,7 @@
   run-time that scale with data size.
 
 """
+
 import os
 
 import dask.array as da
@@ -92,7 +93,7 @@ def setup_cache(self):
             )
 
     def setup(self, n_cubesphere, imaginary_data=True, create_result_cube=True):
-        """Combine-tests "standard" setup operation.
+        """Combine tests "standard" setup operation.
 
         Load the source cubes (full-mesh + region) from disk.
         These are specific to the cubesize parameter.

benchmarks/benchmarks/generate_data/__init__.py

@@ -14,6 +14,7 @@
 benchmark sequence runs over two different Python versions.
 
 """
+
 from contextlib import contextmanager
 from inspect import getsource
 from os import environ

benchmarks/benchmarks/generate_data/ugrid.py

@@ -3,6 +3,7 @@
 # This file is part of Iris and is released under the BSD license.
 # See LICENSE in the root of the repository for full licensing details.
 """Scripts for generating supporting data for UGRID-related benchmarking."""
+
 from iris import load_cube as iris_loadcube
 from iris.experimental.ugrid import PARSE_UGRID_ON_LOAD
 

benchmarks/benchmarks/import_iris.py

@@ -3,7 +3,7 @@
 # This file is part of Iris and is released under the BSD license.
 # See LICENSE in the root of the repository for full licensing details.
 
-"""import iris benchmarking."""
+"""Import iris benchmarking."""
 
 from importlib import import_module, reload
 

benchmarks/benchmarks/iterate.py

@@ -3,6 +3,7 @@
 # This file is part of Iris and is released under the BSD license.
 # See LICENSE in the root of the repository for full licensing details.
 """Iterate benchmark tests."""
+
 import numpy as np
 
 from iris import coords, cube, iterate

benchmarks/benchmarks/load/__init__.py

@@ -112,7 +112,7 @@ class ManyVars:
 
     @staticmethod
     def _create_file(save_path: str) -> None:
-        """Is run externally - everything must be self-contained."""
+        """Run externally - everything must be self-contained."""
         import numpy as np
 
         from iris import save

benchmarks/benchmarks/metadata_manager_factory.py

@@ -2,7 +2,7 @@
 #
 # This file is part of Iris and is released under the BSD license.
 # See LICENSE in the root of the repository for full licensing details.
-"""metadata_manager_factory benchmark tests."""
+"""Metadata manager factory benchmark tests."""
 
 from iris.common import (
     AncillaryVariableMetadata,

benchmarks/benchmarks/plot.py

@@ -3,6 +3,7 @@
 # This file is part of Iris and is released under the BSD license.
 # See LICENSE in the root of the repository for full licensing details.
 """Plot benchmark tests."""
+
 import matplotlib as mpl
 import numpy as np
 

benchmarks/benchmarks/save.py

@@ -11,6 +11,7 @@
            run-time that scale with data size.
 
 """
+
 from iris import save
 from iris.experimental.ugrid import save_mesh
 

benchmarks/benchmarks/sperf/__init__.py

@@ -7,6 +7,7 @@
 SPerf = assessing performance against a series of increasingly large LFRic
 datasets.
 """
+
 from iris import load_cube
 
 # TODO: remove uses of PARSE_UGRID_ON_LOAD once UGRID parsing is core behaviour.

benchmarks/benchmarks/sperf/combine_regions.py

@@ -3,6 +3,7 @@
 # This file is part of Iris and is released under the BSD license.
 # See LICENSE in the root of the repository for full licensing details.
 """Region combine benchmarks for the SPerf scheme of the UK Met Office's NG-VAT project."""
+
 import os.path
 
 from dask import array as da
@@ -83,7 +84,7 @@ def setup_cache(self):
             )
 
     def setup(self, n_cubesphere, imaginary_data=True, create_result_cube=True):
-        """Combine-tests "standard" setup operation.
+        """Combine tests "standard" setup operation.
 
         Load the source cubes (full-mesh + region) from disk.
         These are specific to the cubesize parameter.

benchmarks/benchmarks/sperf/equality.py

@@ -3,6 +3,7 @@
 # This file is part of Iris and is released under the BSD license.
 # See LICENSE in the root of the repository for full licensing details.
 """Equality benchmarks for the SPerf scheme of the UK Met Office's NG-VAT project."""
+
 from .. import on_demand_benchmark
 from . import FileMixin
 

benchmarks/benchmarks/sperf/load.py

@@ -3,6 +3,7 @@
 # This file is part of Iris and is released under the BSD license.
 # See LICENSE in the root of the repository for full licensing details.
 """File loading benchmarks for the SPerf scheme of the UK Met Office's NG-VAT project."""
+
 from .. import on_demand_benchmark
 from . import FileMixin
 

benchmarks/benchmarks/sperf/save.py

@@ -3,6 +3,7 @@
 # This file is part of Iris and is released under the BSD license.
 # See LICENSE in the root of the repository for full licensing details.
 """File saving benchmarks for the SPerf scheme of the UK Met Office's NG-VAT project."""
+
 import os.path
 
 from iris import save

benchmarks/bm_runner.py

@@ -66,7 +66,7 @@ def _check_requirements(package: str) -> None:
 
 
 def _prep_data_gen_env() -> None:
-    """Create/access a separate, unchanging environment for generating test data."""
+    """Create or access a separate, unchanging environment for generating test data."""
     python_version = "3.11"
     data_gen_var = "DATA_GEN_PYTHON"
     if data_gen_var in environ:
@@ -171,7 +171,7 @@ def _gh_create_reports(commit_sha: str, results_full: str, results_shifts: str)
     performance_report = dedent(
         (
             """
-            ### Performance Benchmark Report: {commit_sha}
+            # :stopwatch: Performance Benchmark Report: {commit_sha}
 
             <details>
             <summary>Performance shifts</summary>