Merge remote-tracking branch 'upstream/main' into api_toc_expand

* upstream/main: (26 commits)
  Bump scitools/workflows from 2023.12.1 to 2024.01.0 (SciTools#5710)
  Faster trivial equality checks for coordinates and arrays (SciTools#5691)
  Make the Coord.cell method lazy (SciTools#5693)
  Re-write `pearsonr` to use `Resolve` (SciTools#5638)
  ruff compliance for D401. (SciTools#5687)
  Bump actions/cache from 3 to 4 (SciTools#5703)
  update rtd ubuntu and mambaforge (SciTools#5702)
  [pre-commit.ci] pre-commit autoupdate (SciTools#5699)
  ruff compliance for D205. (SciTools#5681)
  Added whatsnew to warnings PR (SciTools#5696)
  Removed use of catch_warnings (SciTools#5685)
  Better documentation for Cube names in curl (SciTools#5680)
  fix typo (SciTools#5689)
  Make further topics obviously different (SciTools#5684)
  [pre-commit.ci] pre-commit autoupdate (SciTools#5682)
  ruff complliance for D100. (SciTools#5678)
  move tests.pp to tests.__init__ (SciTools#5679)
  ruff compliance for D417, D106 (SciTools#5677)
  ruff compliance for D200. (SciTools#5675)
  ruff compliance for D106. (SciTools#5676)
  ...

Author: tkknight

Diff for: .github/workflows/benchmarks_run.yml

@@ -46,7 +46,7 @@ jobs:
 
       - name: Cache environment directories
         id: cache-env-dir
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: |
             .nox
@@ -56,7 +56,7 @@ jobs:
 
       - name: Cache test data directory
         id: cache-test-data
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: |
             ${{ env.IRIS_TEST_DATA_PATH }}

Diff for: .github/workflows/ci-manifest.yml

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

Diff for: .github/workflows/refresh-lockfiles.yml

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

Diff for: .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.1.9"
+    rev: "v0.1.13"
     hooks:
     -   id: ruff
         types: [file, python]
@@ -45,7 +45,7 @@ repos:
         additional_dependencies: [tomli]
 
 -   repo: https://github.com/PyCQA/flake8
-    rev: 6.1.0
+    rev: 7.0.0
     hooks:
     -   id: flake8
         types: [file, python]

Diff for: .readthedocs.yml

@@ -1,9 +1,9 @@
 version: 2
 
 build:
-  os: ubuntu-20.04
+  os: "ubuntu-22.04"
   tools:
-    python: mambaforge-4.10
+    python: "mambaforge-22.9"
   jobs:
     post_checkout:
       # The SciTools/iris repository is shallow i.e., has a .git/shallow,

Diff for: .ruff.toml

@@ -11,7 +11,6 @@ lint.ignore = [
     # pycodestyle (E, W)
     # https://docs.astral.sh/ruff/rules/#pycodestyle-e-w
     "E",
-    "W",
 
     # mccabe (C90)
     # https://docs.astral.sh/ruff/rules/#mccabe-c90
@@ -26,22 +25,10 @@ lint.ignore = [
     # (D-1) Permanent
     "D105",  # Missing docstring in magic method
     # (D-2) Temporary, to be removed when we are more compliant. Rare cases mmove  to (1).
-    "D417",  # Missing argument descriptions in the docstring
     "D101",  # Missing docstring in public class
     "D102",  # Missing docstring in public method
-    "D104",  # Missing docstring in public package
-    "D106",  # Missing docstring in public nested class
-    # (D-3) Temporary, before an initial review, either fix ocurrenvces or move to (2).
-    "D100",  # Missing docstring in public module
+    # (D-3) Temporary, before an initial review, either fix ocurrences or move to (2).
     "D103",  # Missing docstring in public function
-    "D200",  # One-line docstring should fit on one line
-    "D202",  # No blank lines allowed after function docstring
-    "D205",  # 1 blank line required between summary line and description
-    "D401",  # First line of docstring should be in imperative mood: ...
-    "D404",  # First word of the docstring should not be "This"
-    "D405",  # Section name should be properly capitalized
-    "D406",  # Section name should end with a newline
-    "D407",  # Missing dashed underline after section
 
     # pyupgrade (UP)
     # https://docs.astral.sh/ruff/rules/#pyupgrade-up
@@ -71,10 +58,6 @@ lint.ignore = [
     # https://docs.astral.sh/ruff/rules/#flake8-builtins-a
     "A",
 
-    # flake8-copyright (CPY)
-    # https://docs.astral.sh/ruff/rules/#flake8-copyright-cpy
-    "CPY",
-
     # flake8-comprehensions (C4)
     # https://docs.astral.sh/ruff/rules/#flake8-comprehensions-c4
     "C4",
@@ -91,10 +74,6 @@ lint.ignore = [
     # https://docs.astral.sh/ruff/rules/#flake8-future-annotations-fa
     "FA",
 
-    # flake8-implicit-str-concat (ISC)
-    # https://docs.astral.sh/ruff/rules/#flake8-implicit-str-concat-isc
-    "ISC",
-
     # flake8-logging-format (G)
     # https://docs.astral.sh/ruff/rules/#flake8-logging-format-g
     "G",
@@ -187,10 +166,6 @@ lint.ignore = [
     # https://docs.astral.sh/ruff/rules/#flynt-fly
     "FLY",
 
-    # Airflow (AIR)
-    # https://docs.astral.sh/ruff/rules/#airflow-air
-    "AIR",
-
     # Perflint (PERF)
     # https://docs.astral.sh/ruff/rules/#perflint-perf
     "PERF",

Diff for: benchmarks/asv_delegated_conda.py

@@ -2,8 +2,9 @@
 #
 # 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.
-"""ASV plug-in providing an alternative :class:`asv.plugins.conda.Conda`
-subclass that manages the Conda environment via custom user scripts.
+"""ASV plug-in providing an alternative :class:`asv.plugins.conda.Conda` subclass.
+
+Manages the Conda environment via custom user scripts.
 
 """
 
@@ -42,7 +43,9 @@ def __init__(
         requirements: dict,
         tagged_env_vars: dict,
     ) -> None:
-        """Parameters
+        """__init__.
+
+        Parameters
         ----------
         conf : Config instance
 

Diff for: benchmarks/benchmarks/__init__.py

@@ -10,7 +10,7 @@
 
 
 def disable_repeat_between_setup(benchmark_object):
-    """Decorator for benchmarks where object persistence would be inappropriate.
+    """Benchmarks where object persistence would be inappropriate (decorator).
 
     E.g:
         * Benchmarking data realisation
@@ -36,7 +36,9 @@ def disable_repeat_between_setup(benchmark_object):
 
 
 class TrackAddedMemoryAllocation:
-    """Context manager which measures by how much process resident memory grew,
+    """Measures by how much process resident memory grew, during execution.
+
+    Context manager which measures by how much process resident memory grew,
     during execution of its enclosed code block.
 
     Obviously limited as to what it actually measures : Relies on the current
@@ -84,7 +86,7 @@ def addedmem_mb(self):
 
     @staticmethod
     def decorator(decorated_func):
-        """Decorates this benchmark to track growth in resident memory during execution.
+        """Benchmark to track growth in resident memory during execution.
 
         Intended for use on ASV ``track_`` benchmarks. Applies the
         :class:`TrackAddedMemoryAllocation` context manager to the benchmark
@@ -105,7 +107,9 @@ def _wrapper(*args, **kwargs):
 
 
 def on_demand_benchmark(benchmark_object):
-    """Decorator. Disables these benchmark(s) unless ON_DEMAND_BENCHARKS env var is set.
+    """Disables 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:

Diff for: benchmarks/benchmarks/aux_factory.py

@@ -2,9 +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.
-"""AuxFactory benchmark tests.
-
-"""
+"""AuxFactory benchmark tests."""
 
 import numpy as np
 
@@ -18,7 +16,9 @@ class FactoryCommon:
     #       * make class an ABC
     #       * remove NotImplementedError
     #       * combine setup_common into setup
-    """A base class running a generalised suite of benchmarks for any factory.
+    """Run a generalised suite of benchmarks for any factory.
+
+    A base class running a generalised suite of benchmarks for any factory.
     Factory to be specified in a subclass.
 
     ASV will run the benchmarks within this class for any subclasses.

Diff for: benchmarks/benchmarks/coords.py

@@ -2,9 +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.
-"""Coord benchmark tests.
-
-"""
+"""Coord benchmark tests."""
 
 import numpy as np
 
@@ -25,7 +23,9 @@ class CoordCommon:
     #       * make class an ABC
     #       * remove NotImplementedError
     #       * combine setup_common into setup
-    """A base class running a generalised suite of benchmarks for any coord.
+    """Run a generalised suite of benchmarks for any coord.
+
+    A base class running a generalised suite of benchmarks for any coord.
     Coord to be specified in a subclass.
 
     ASV will run the benchmarks within this class for any subclasses.

Diff for: benchmarks/benchmarks/cperf/equality.py

@@ -2,15 +2,17 @@
 #
 # 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.
-"""
+"""Equality benchmarks for the CPerf scheme of the UK Met Office's NG-VAT project."""
 from .. import on_demand_benchmark
 from . import SingleDiagnosticMixin
 
 
 class EqualityMixin(SingleDiagnosticMixin):
-    r"""Uses :class:`SingleDiagnosticMixin` as the realistic case will be comparing
+    r"""Use :class:`SingleDiagnosticMixin` as the realistic case.
+
+    Uses :class:`SingleDiagnosticMixin` as the realistic case will be comparing
     :class:`~iris.cube.Cube`\\ s that have been loaded from file.
+
     """
 
     # Cut down the parent parameters.
@@ -24,9 +26,7 @@ def setup(self, file_type, three_d=False, three_times=False):
 
 @on_demand_benchmark
 class CubeEquality(EqualityMixin):
-    r"""Benchmark time and memory costs of comparing LFRic and UM
-    :class:`~iris.cube.Cube`\\ s.
-    """
+    r"""Benchmark time & memory costs of comparing LFRic & UM :class:`~iris.cube.Cube`\\ s."""
 
     def _comparison(self):
         _ = self.cube == self.other_cube

Diff for: benchmarks/benchmarks/cperf/load.py

@@ -2,16 +2,16 @@
 #
 # 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.
-"""
+"""File loading benchmarks for the CPerf scheme of the UK Met Office's NG-VAT project."""
 from .. import on_demand_benchmark
 from . import SingleDiagnosticMixin
 
 
 @on_demand_benchmark
 class SingleDiagnosticLoad(SingleDiagnosticMixin):
     def time_load(self, _, __, ___):
-        """The 'real world comparison'
+        """Perform a 'real world comparison'.
+
         * UM coords are always realised (DimCoords).
         * LFRic coords are not realised by default (MeshCoords).
 
@@ -26,7 +26,7 @@ def time_load(self, _, __, ___):
             assert coord.has_lazy_bounds() == expecting_lazy_coords
 
     def time_load_w_realised_coords(self, _, __, ___):
-        """A valuable extra comparison where both UM and LFRic coords are realised."""
+        """Valuable extra comparison where both UM and LFRic coords are realised."""
         cube = self.load()
         for coord_name in "longitude", "latitude":
             coord = cube.coord(coord_name)

Diff for: benchmarks/benchmarks/cperf/save.py

@@ -2,8 +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.
-"""File saving benchmarks for the CPerf scheme of the UK Met Office's NG-VAT project.
-"""
+"""File saving benchmarks for the CPerf scheme of the UK Met Office's NG-VAT project."""
 
 from iris import save
 
@@ -15,6 +14,7 @@
 @on_demand_benchmark
 class NetcdfSave:
     """Benchmark time and memory costs of saving ~large-ish data cubes to netcdf.
+
     Parametrised by file type.
 
     """

Diff for: benchmarks/benchmarks/cube.py

@@ -2,9 +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.
-"""Cube benchmark tests.
-
-"""
+"""Cube benchmark tests."""
 
 import numpy as np
 
@@ -30,7 +28,9 @@ class ComponentCommon:
     #       * make class an ABC
     #       * remove NotImplementedError
     #       * combine setup_common into setup
-    """A base class running a generalised suite of benchmarks for cubes that
+    """Run a generalised suite of benchmarks for cubes.
+
+    A base class running a generalised suite of benchmarks for cubes that
     include a specified component (e.g. Coord, CellMeasure etc.). Component to
     be specified in a subclass.
 
@@ -45,7 +45,7 @@ def setup(self):
         raise NotImplementedError
 
     def create(self):
-        """Generic cube creation.
+        """Create a cube (generic).
 
         cube_kwargs allow dynamic inclusion of different components;
         specified in subclasses.

Diff for: benchmarks/benchmarks/experimental/__init__.py

@@ -2,6 +2,4 @@
 #
 # 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.
-"""Benchmark tests for the experimental module.
-
-"""
+"""Benchmark tests for the experimental module."""

Diff for: benchmarks/benchmarks/experimental/ugrid/__init__.py

@@ -2,9 +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.
-"""Benchmark tests for the experimental.ugrid module.
-
-"""
+"""Benchmark tests for the experimental.ugrid module."""
 
 from copy import deepcopy
 
@@ -17,7 +15,9 @@
 
 
 class UGridCommon:
-    """A base class running a generalised suite of benchmarks for any ugrid object.
+    """Run a generalised suite of benchmarks for any ugrid object.
+
+    A base class running a generalised suite of benchmarks for any ugrid object.
     Object to be specified in a subclass.
 
     ASV will run the benchmarks within this class for any subclasses.