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

* upstream/main:
  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)

.ruff.toml

@@ -29,7 +29,6 @@ lint.ignore = [
     "D102",  # Missing docstring in public method
     # (D-3) Temporary, before an initial review, either fix ocurrences or move to (2).
     "D103",  # Missing docstring in public function
-    "D205",  # 1 blank line required between summary line and description
     "D401",  # First line of docstring should be in imperative mood: ...
 
     # pyupgrade (UP)

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
 

benchmarks/benchmarks/__init__.py

@@ -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

benchmarks/benchmarks/aux_factory.py

@@ -16,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.

benchmarks/benchmarks/coords.py

@@ -23,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.

benchmarks/benchmarks/cperf/equality.py

@@ -8,8 +8,11 @@
 
 
 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.
@@ -23,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

benchmarks/benchmarks/cperf/load.py

@@ -10,7 +10,8 @@
 @on_demand_benchmark
 class SingleDiagnosticLoad(SingleDiagnosticMixin):
     def time_load(self, _, __, ___):
-        """The 'real world comparison'
+        """The 'real world comparison'.
+
         * UM coords are always realised (DimCoords).
         * LFRic coords are not realised by default (MeshCoords).
 

benchmarks/benchmarks/cperf/save.py

@@ -14,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.
 
     """

benchmarks/benchmarks/cube.py

@@ -28,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.
 

benchmarks/benchmarks/experimental/ugrid/__init__.py

@@ -15,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.

benchmarks/benchmarks/experimental/ugrid/regions_combine.py

@@ -2,14 +2,18 @@
 #
 # 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.
-"""Benchmarks stages of operation of the function
+"""Benchmarks stages of operation.
+
+Benchmarks stages of operation of the function
 :func:`iris.experimental.ugrid.utils.recombine_submeshes`.
 
 Where possible benchmarks should be parameterised for two sizes of input data:
-  * minimal: enables detection of regressions in parts of the run-time that do
-             NOT scale with data size.
-  * large: large enough to exclusively detect regressions in parts of the
-           run-time that scale with data size.
+
+* minimal: enables detection of regressions in parts of the run-time that do
+  NOT scale with data size.
+
+* large: large enough to exclusively detect regressions in parts of the
+  run-time that scale with data size.
 
 """
 import os
@@ -193,10 +197,13 @@ def track_addedmem_compute_data(self, n_cubesphere):
 
 
 class CombineRegionsSaveData(MixinCombineRegions):
-    """Test saving *only*, having replaced the input cube data with 'imaginary'
+    """Test saving *only*.
+
+    Test saving *only*, having replaced the input cube data with 'imaginary'
     array data, so that input data is not loaded from disk during the save
     operation.
 
+
     """
 
     def time_save(self, n_cubesphere):
@@ -219,6 +226,7 @@ def track_filesize_saved(self, n_cubesphere):
 
 class CombineRegionsFileStreamedCalc(MixinCombineRegions):
     """Test the whole cost of file-to-file streaming.
+
     Uses the combined cube which is based on lazy data loading from the region
     cubes on disk.
     """

benchmarks/benchmarks/generate_data/ugrid.py

@@ -14,7 +14,9 @@
 
 
 def generate_cube_like_2d_cubesphere(n_cube: int, with_mesh: bool, output_path: str):
-    """Construct and save to file an LFRIc cubesphere-like cube for a given
+    """Construct and save to file an LFRIc cubesphere-like cube.
+
+    Construct and save to file an LFRIc cubesphere-like cube for a given
     cubesphere size, *or* a simpler structured (UM-like) cube of equivalent
     size.
 
@@ -54,7 +56,9 @@ def generate_cube_like_2d_cubesphere(n_cube: int, with_mesh: bool, output_path:
 
 
 def make_cube_like_2d_cubesphere(n_cube: int, with_mesh: bool):
-    """Generate an LFRIc cubesphere-like cube for a given cubesphere size,
+    """Generate an LFRIc cubesphere-like cube.
+
+    Generate an LFRIc cubesphere-like cube for a given cubesphere size,
     *or* a simpler structured (UM-like) cube of equivalent size.
 
     All the cube data, coords and mesh content are LAZY, and produced without
@@ -155,7 +159,9 @@ def _external(xy_dims_, save_path_):
 
 
 def make_cubesphere_testfile(c_size, n_levels=0, n_times=1):
-    """Build a C<c_size> cubesphere testfile in a given directory, with a standard naming.
+    """Build a C<c_size> cubesphere testfile in a given directory.
+
+    Build a C<c_size> cubesphere testfile in a given directory, with a standard naming.
     If n_levels > 0 specified: 3d file with the specified number of levels.
     Return the file path.
 

benchmarks/benchmarks/import_iris.py

@@ -31,8 +31,7 @@
 class Iris:
     @staticmethod
     def _import(module_name, reset_colormaps=False):
-        """Have experimented with adding sleep() commands into the imported
-        modules.
+        """Have experimented with adding sleep() commands into the imported modules.
 
         The results reveal:
 

benchmarks/benchmarks/sperf/combine_regions.py

@@ -195,7 +195,9 @@ def track_addedmem_compute_data(self, n_cubesphere):
 
 @on_demand_benchmark
 class SaveData(Mixin):
-    """Test saving *only*, having replaced the input cube data with 'imaginary'
+    """Test saving *only*.
+
+    Test saving *only*, having replaced the input cube data with 'imaginary'
     array data, so that input data is not loaded from disk during the save
     operation.
 
@@ -217,8 +219,10 @@ def track_filesize_saved(self, n_cubesphere):
 @on_demand_benchmark
 class FileStreamedCalc(Mixin):
     """Test the whole cost of file-to-file streaming.
+
     Uses the combined cube which is based on lazy data loading from the region
     cubes on disk.
+
     """
 
     def setup(self, n_cubesphere, imaginary_data=False, create_result_cube=True):

benchmarks/benchmarks/sperf/equality.py

@@ -9,8 +9,10 @@
 
 @on_demand_benchmark
 class CubeEquality(FileMixin):
-    r"""Benchmark time and memory costs of comparing :class:`~iris.cube.Cube`\\ s
-     with attached :class:`~iris.experimental.ugrid.mesh.Mesh`\\ es.
+    r"""Benchmark time and memory costs.
+
+    Benchmark time and memory costs of comparing :class:`~iris.cube.Cube`\\ s
+    with attached :class:`~iris.experimental.ugrid.mesh.Mesh`\\ es.
 
     Uses :class:`FileMixin` as the realistic case will be comparing
     :class:`~iris.cube.Cube`\\ s that have been loaded from file.

docs/gallery_code/general/plot_SOI_filtering.py

@@ -1,4 +1,5 @@
-"""Applying a Filter to a Time-Series
+"""
+Applying a Filter to a Time-Series
 ==================================
 
 This example demonstrates low pass filtering a time-series by applying a
@@ -17,7 +18,7 @@
     Trenberth K. E. (1984) Signal Versus Noise in the Southern Oscillation.
     Monthly Weather Review, Vol 112, pp 326-332
 
-"""  # noqa: D400
+"""  # noqa: D205, D212, D400
 
 import matplotlib.pyplot as plt
 import numpy as np

docs/gallery_code/general/plot_anomaly_log_colouring.py

@@ -1,4 +1,5 @@
-"""Colouring Anomaly Data With Logarithmic Scaling
+"""
+Colouring Anomaly Data With Logarithmic Scaling
 ===============================================
 
 In this example, we need to plot anomaly data where the values have a
@@ -22,7 +23,7 @@
 and :obj:`matplotlib.pyplot.pcolormesh`).
 See also: https://en.wikipedia.org/wiki/False_color#Pseudocolor.
 
-"""  # noqa: D400
+"""  # noqa: D205, D212, D400
 
 import cartopy.crs as ccrs
 import matplotlib.colors as mcols

docs/gallery_code/general/plot_coriolis.py

@@ -1,11 +1,12 @@
-"""Deriving the Coriolis Frequency Over the Globe
+"""
+Deriving the Coriolis Frequency Over the Globe
 ==============================================
 
 This code computes the Coriolis frequency and stores it in a cube with
 associated metadata. It then plots the Coriolis frequency on an orthographic
 projection.
 
-"""  # noqa: D400
+"""  # noqa: D205, D212, D400
 
 import cartopy.crs as ccrs
 import matplotlib.pyplot as plt

docs/gallery_code/general/plot_cross_section.py

@@ -1,10 +1,11 @@
-"""Cross Section Plots
+"""
+Cross Section Plots
 ===================
 
 This example demonstrates contour plots of a cross-sectioned multi-dimensional
 cube which features a hybrid height vertical coordinate system.
 
-"""  # noqa: D400
+"""  # noqa: D205, D212, D400
 
 import matplotlib.pyplot as plt
 

docs/gallery_code/general/plot_custom_aggregation.py

@@ -1,4 +1,5 @@
-"""Calculating a Custom Statistic
+"""
+Calculating a Custom Statistic
 ==============================
 
 This example shows how to define and use a custom
@@ -11,7 +12,7 @@
 over North America, and we want to calculate in how many years these exceed a
 certain temperature over a spell of 5 years or more.
 
-"""  # noqa: D400
+"""  # noqa: D205, D212, D400
 
 import matplotlib.pyplot as plt
 import numpy as np
@@ -27,25 +28,24 @@
 # Note: in order to meet the requirements of iris.analysis.Aggregator, it must
 # do the calculation over an arbitrary (given) data axis.
 def count_spells(data, threshold, axis, spell_length):
-    """Function to calculate the number of points in a sequence where the value
+    """Calculate the number of points in a sequence.
+
+    Function to calculate the number of points in a sequence where the value
     has exceeded a threshold value for at least a certain number of timepoints.
 
     Generalised to operate on multiple time sequences arranged on a specific
     axis of a multidimensional array.
 
-    Args:
-
-    * data (array):
+    Parameters
+    ----------
+    data : array
         raw data to be compared with value threshold.
-
-    * threshold (float):
+    threshold : float
         threshold point for 'significant' datapoints.
-
-    * axis (int):
+    axis : int
         number of the array dimension mapping the time sequences.
         (Can also be negative, e.g. '-1' means last dimension)
-
-    * spell_length (int):
+    spell_length : int
         number of consecutive times at which value > threshold to "count".
 
     """