Merge remote-tracking branch 'upstream/main' into numpydoc-pre-commit

* upstream/main:
  Refactor warnings from `iris.exceptions` into `iris.warnings` (SciTools#5760)

docs/src/further_topics/filtering_warnings.rst

@@ -16,7 +16,7 @@ you to ``ignore`` Warnings which you do not find helpful.
 
     import iris
     import iris.coord_systems
-    import iris.exceptions
+    import iris.warnings
 
     # Hack to ensure doctests actually see Warnings that are raised, and that
     #  they have a relative path (so a test pass is not machine-dependent).
@@ -47,9 +47,9 @@ Warnings:
 
     >>> my_operation()
     ...
-    iris/coord_systems.py:444: IrisUserWarning: Setting inverse_flattening does not affect other properties of the GeogCS object. To change other properties set them explicitly or create a new GeogCS instance.
-      warnings.warn(wmsg, category=iris.exceptions.IrisUserWarning)
-    iris/coord_systems.py:770: IrisDefaultingWarning: Discarding false_easting and false_northing that are not used by Cartopy.
+    iris/coord_systems.py:442: IrisUserWarning: Setting inverse_flattening does not affect other properties of the GeogCS object. To change other properties set them explicitly or create a new GeogCS instance.
+      warnings.warn(wmsg, category=iris.warnings.IrisUserWarning)
+    iris/coord_systems.py:768: IrisDefaultingWarning: Discarding false_easting and false_northing that are not used by Cartopy.
       warnings.warn(
 
 Warnings can be suppressed using the Python warnings filter with the ``ignore``
@@ -110,8 +110,8 @@ You can target specific Warning messages, e.g.
     ...     warnings.filterwarnings("ignore", message="Discarding false_easting")
     ...     my_operation()
     ...
-    iris/coord_systems.py:444: IrisUserWarning: Setting inverse_flattening does not affect other properties of the GeogCS object. To change other properties set them explicitly or create a new GeogCS instance.
-      warnings.warn(wmsg, category=iris.exceptions.IrisUserWarning)
+    iris/coord_systems.py:442: IrisUserWarning: Setting inverse_flattening does not affect other properties of the GeogCS object. To change other properties set them explicitly or create a new GeogCS instance.
+      warnings.warn(wmsg, category=iris.warnings.IrisUserWarning)
 
 ::
 
@@ -178,33 +178,33 @@ Warnings of a Common Type
 code you are calling.**
 
 The below example will ``ignore`` any
-:class:`~iris.exceptions.IrisDefaultingWarning` that gets raised by *any*
+:class:`~iris.warnings.IrisDefaultingWarning` that gets raised by *any*
 module during execution:
 
 .. doctest:: filtering_warnings
 
     >>> with warnings.catch_warnings():
     ...     warnings.filterwarnings(
     ...         "ignore",
-    ...         category=iris.exceptions.IrisDefaultingWarning
+    ...         category=iris.warnings.IrisDefaultingWarning
     ...     )
     ...     my_operation()
     ...
-    iris/coord_systems.py:444: IrisUserWarning: Setting inverse_flattening does not affect other properties of the GeogCS object. To change other properties set them explicitly or create a new GeogCS instance.
-      warnings.warn(wmsg, category=iris.exceptions.IrisUserWarning)
+    iris/coord_systems.py:442: IrisUserWarning: Setting inverse_flattening does not affect other properties of the GeogCS object. To change other properties set them explicitly or create a new GeogCS instance.
+      warnings.warn(wmsg, category=iris.warnings.IrisUserWarning)
 
 ----
 
-Using :class:`~iris.exceptions.IrisUserWarning` in the filter will ``ignore``
-both Warnings, since :class:`~iris.exceptions.IrisDefaultingWarning` subclasses
-:class:`~iris.exceptions.IrisUserWarning` :
+Using :class:`~iris.warnings.IrisUserWarning` in the filter will ``ignore``
+both Warnings, since :class:`~iris.warnings.IrisDefaultingWarning` subclasses
+:class:`~iris.warnings.IrisUserWarning` :
 
 .. doctest:: filtering_warnings
 
     >>> with warnings.catch_warnings():
     ...     warnings.filterwarnings(
     ...         "ignore",
-    ...         category=iris.exceptions.IrisUserWarning
+    ...         category=iris.warnings.IrisUserWarning
     ...     )
     ...     my_operation()
 
@@ -222,10 +222,10 @@ There are several built-in Python warning categories that can be used here
 (:class:`DeprecationWarning` being a popular example, see
 :external+python:mod:`warnings` for more). Since Iris has
 so many different warnings that might be raised, Iris subclasses
-:class:`UserWarning` to :class:`~iris.exceptions.IrisUserWarning`, which itself
+:class:`UserWarning` to :class:`~iris.warnings.IrisUserWarning`, which itself
 has **many** specialised subclasses. These subclasses exist to give you more
 granularity in your warning filtering; you can see the full list by
-searching the :mod:`iris.exceptions` page for ``warning`` .
+viewing the :mod:`iris.warnings` module.
 
 .. attention::
 

docs/src/whatsnew/latest.rst

@@ -46,7 +46,8 @@ This document explains the changes made to Iris for this release
 
 #. `@trexfeathers`_ and `@HGWright`_ (reviewer) sub-categorised all Iris'
    :class:`UserWarning`\s for richer filtering. The full index of
-   sub-categories can be seen here: :mod:`iris.exceptions` . (:pull:`5498`)
+   sub-categories can be seen here: :mod:`iris.warnings` . (:pull:`5498`,
+   :pull:`5760`)
 
 #. `@trexfeathers`_ added the :class:`~iris.coord_systems.ObliqueMercator`
    and :class:`~iris.coord_systems.RotatedMercator` coordinate systems,

lib/iris/_concatenate.py

@@ -14,6 +14,7 @@
 import iris.cube
 import iris.exceptions
 from iris.util import array_equal, guess_coord_axis
+import iris.warnings
 
 #
 # TODO:
@@ -910,7 +911,7 @@ def register(
                 raise iris.exceptions.ConcatenateError([msg])
             elif not match:
                 msg = f"Found cubes with overlap on concatenate axis {candidate_axis}, skipping concatenation for these cubes"
-                warnings.warn(msg, category=iris.exceptions.IrisUserWarning)
+                warnings.warn(msg, category=iris.warnings.IrisUserWarning)
 
         # Check for compatible AuxCoords.
         if match:

lib/iris/_shapefiles.py

@@ -17,7 +17,7 @@
 import shapely.geometry as sgeom
 import shapely.ops
 
-from iris.exceptions import IrisDefaultingWarning, IrisUserWarning
+from iris.warnings import IrisDefaultingWarning, IrisUserWarning
 
 
 def create_shapefile_mask(

lib/iris/analysis/_regrid.py

@@ -19,8 +19,8 @@
     snapshot_grid,
 )
 from iris.analysis._scipy_interpolate import _RegularGridInterpolator
-from iris.exceptions import IrisImpossibleUpdateWarning
 from iris.util import _meshgrid, guess_coord_axis
+from iris.warnings import IrisImpossibleUpdateWarning
 
 
 def _transform_xy_arrays(crs_from, x, y, crs_to):

lib/iris/analysis/calculus.py

@@ -22,8 +22,8 @@
 import iris.analysis.maths
 import iris.coord_systems
 import iris.coords
-from iris.exceptions import IrisUserWarning
 from iris.util import delta
+from iris.warnings import IrisUserWarning
 
 __all__ = ["DIRECTIONAL_NAMES", "cube_delta", "curl", "differentiate"]
 

lib/iris/analysis/cartography.py

@@ -19,6 +19,7 @@
 import iris.coords
 import iris.exceptions
 from iris.util import _meshgrid
+import iris.warnings
 
 from ._grid_angles import gridcell_angles, rotate_grid_vectors
 
@@ -412,7 +413,7 @@ def area_weights(cube, normalize=False):
         if cs.inverse_flattening != 0.0:
             warnings.warn(
                 "Assuming spherical earth from ellipsoid.",
-                category=iris.exceptions.IrisDefaultingWarning,
+                category=iris.warnings.IrisDefaultingWarning,
             )
         radius_of_earth = cs.semi_major_axis
     elif isinstance(cs, iris.coord_systems.RotatedGeogCS) and (
@@ -421,13 +422,13 @@ def area_weights(cube, normalize=False):
         if cs.ellipsoid.inverse_flattening != 0.0:
             warnings.warn(
                 "Assuming spherical earth from ellipsoid.",
-                category=iris.exceptions.IrisDefaultingWarning,
+                category=iris.warnings.IrisDefaultingWarning,
             )
         radius_of_earth = cs.ellipsoid.semi_major_axis
     else:
         warnings.warn(
             "Using DEFAULT_SPHERICAL_EARTH_RADIUS.",
-            category=iris.exceptions.IrisDefaultingWarning,
+            category=iris.warnings.IrisDefaultingWarning,
         )
         radius_of_earth = DEFAULT_SPHERICAL_EARTH_RADIUS
 
@@ -569,7 +570,7 @@ def cosine_latitude_weights(cube):
     ):
         warnings.warn(
             "Out of range latitude values will be clipped to the valid range.",
-            category=iris.exceptions.IrisDefaultingWarning,
+            category=iris.warnings.IrisDefaultingWarning,
         )
     points = lat.points
     l_weights = np.cos(points).clip(0.0, 1.0)
@@ -686,7 +687,7 @@ def project(cube, target_proj, nx=None, ny=None):
         warnings.warn(
             "Coordinate system of latitude and longitude "
             "coordinates is not specified. Assuming WGS84 Geodetic.",
-            category=iris.exceptions.IrisDefaultingWarning,
+            category=iris.warnings.IrisDefaultingWarning,
         )
         orig_cs = iris.coord_systems.GeogCS(
             semi_major_axis=6378137.0, inverse_flattening=298.257223563
@@ -877,7 +878,7 @@ def project(cube, target_proj, nx=None, ny=None):
                 lon_coord.name(),
                 [coord.name() for coord in discarded_coords],
             ),
-            category=iris.exceptions.IrisIgnoringWarning,
+            category=iris.warnings.IrisIgnoringWarning,
         )
 
     # TODO handle derived coords/aux_factories

lib/iris/analysis/geometry.py

@@ -15,6 +15,7 @@
 from shapely.geometry import Polygon
 
 import iris.exceptions
+import iris.warnings
 
 
 def _extract_relevant_cube_slice(cube, geometry):
@@ -71,7 +72,7 @@ def _extract_relevant_cube_slice(cube, geometry):
     except ValueError:
         warnings.warn(
             "The geometry exceeds the cube's x dimension at the lower end.",
-            category=iris.exceptions.IrisGeometryExceedWarning,
+            category=iris.warnings.IrisGeometryExceedWarning,
         )
         x_min_ix = 0 if x_ascending else x_coord.points.size - 1
 
@@ -81,7 +82,7 @@ def _extract_relevant_cube_slice(cube, geometry):
     except ValueError:
         warnings.warn(
             "The geometry exceeds the cube's x dimension at the upper end.",
-            category=iris.exceptions.IrisGeometryExceedWarning,
+            category=iris.warnings.IrisGeometryExceedWarning,
         )
         x_max_ix = x_coord.points.size - 1 if x_ascending else 0
 
@@ -91,7 +92,7 @@ def _extract_relevant_cube_slice(cube, geometry):
     except ValueError:
         warnings.warn(
             "The geometry exceeds the cube's y dimension at the lower end.",
-            category=iris.exceptions.IrisGeometryExceedWarning,
+            category=iris.warnings.IrisGeometryExceedWarning,
         )
         y_min_ix = 0 if y_ascending else y_coord.points.size - 1
 
@@ -101,7 +102,7 @@ def _extract_relevant_cube_slice(cube, geometry):
     except ValueError:
         warnings.warn(
             "The geometry exceeds the cube's y dimension at the upper end.",
-            category=iris.exceptions.IrisGeometryExceedWarning,
+            category=iris.warnings.IrisGeometryExceedWarning,
         )
         y_max_ix = y_coord.points.size - 1 if y_ascending else 0
 

lib/iris/analysis/maths.py

@@ -23,6 +23,7 @@
 import iris.coords
 import iris.exceptions
 import iris.util
+import iris.warnings
 
 # Configure the logger.
 logger = get_logger(__name__)
@@ -942,7 +943,7 @@ def _broadcast_cube_coord_data(cube, other, operation_name, dim=None):
         warnings.warn(
             "Using {!r} with a bounded coordinate is not well "
             "defined; ignoring bounds.".format(operation_name),
-            category=iris.exceptions.IrisIgnoringBoundsWarning,
+            category=iris.warnings.IrisIgnoringBoundsWarning,
         )
 
     points = other.points

lib/iris/aux_factory.py

@@ -13,7 +13,7 @@
 
 from iris.common import CFVariableMixin, CoordMetadata, metadata_manager_factory
 import iris.coords
-from iris.exceptions import IrisIgnoringBoundsWarning
+from iris.warnings import IrisIgnoringBoundsWarning
 
 
 class AuxCoordFactory(CFVariableMixin, metaclass=ABCMeta):

lib/iris/config.py

@@ -31,7 +31,7 @@
 import os.path
 import warnings
 
-import iris.exceptions
+import iris.warnings
 
 
 def get_logger(name, datefmt=None, fmt=None, level=None, propagate=None, handler=True):
@@ -139,7 +139,7 @@ def get_dir_option(section, option, default=None):
             )
             warnings.warn(
                 msg.format(section, option, c_path),
-                category=iris.exceptions.IrisIgnoringWarning,
+                category=iris.warnings.IrisIgnoringWarning,
             )
     return path
 
@@ -246,7 +246,7 @@ def __setattr__(self, name, value):
                 )
                 warnings.warn(
                     wmsg.format(value, name, good_value),
-                    category=iris.exceptions.IrisDefaultingWarning,
+                    category=iris.warnings.IrisDefaultingWarning,
                 )
                 value = good_value
         self.__dict__[name] = value

lib/iris/coord_systems.py

@@ -13,7 +13,7 @@
 import numpy as np
 
 from iris._deprecation import warn_deprecated
-import iris.exceptions
+import iris.warnings
 
 
 def _arg_default(value, default, cast_as=float):
@@ -441,7 +441,7 @@ def inverse_flattening(self, value):
             "the GeogCS object. To change other properties set them explicitly"
             " or create a new GeogCS instance."
         )
-        warnings.warn(wmsg, category=iris.exceptions.IrisUserWarning)
+        warnings.warn(wmsg, category=iris.warnings.IrisUserWarning)
         value = float(value)
         self._inverse_flattening = value
 
@@ -770,7 +770,7 @@ def as_cartopy_crs(self):
         warnings.warn(
             "Discarding false_easting and false_northing that are "
             "not used by Cartopy.",
-            category=iris.exceptions.IrisDefaultingWarning,
+            category=iris.warnings.IrisDefaultingWarning,
         )
 
         return ccrs.Orthographic(

lib/iris/coords.py

@@ -32,6 +32,7 @@
 import iris.exceptions
 import iris.time
 import iris.util
+import iris.warnings
 
 #: The default value for ignore_axis which controls guess_coord_axis' behaviour
 DEFAULT_IGNORE_AXIS = False
@@ -1977,7 +1978,7 @@ def contiguous_bounds(self):  # numpydoc ignore=SS05
                 warnings.warn(
                     "Coordinate {!r} is not bounded, guessing "
                     "contiguous bounds.".format(self.name()),
-                    category=iris.exceptions.IrisGuessBoundsWarning,
+                    category=iris.warnings.IrisGuessBoundsWarning,
                 )
                 bounds = self._guess_bounds()
             elif self.ndim == 2:
@@ -2138,7 +2139,7 @@ def serialize(x):
                 )
                 warnings.warn(
                     msg.format(self.name()),
-                    category=iris.exceptions.IrisVagueMetadataWarning,
+                    category=iris.warnings.IrisVagueMetadataWarning,
                 )
             else:
                 try:
@@ -2151,7 +2152,7 @@ def serialize(x):
                     )
                     warnings.warn(
                         msg.format(str(exc), self.name()),
-                        category=iris.exceptions.IrisVagueMetadataWarning,
+                        category=iris.warnings.IrisVagueMetadataWarning,
                     )
                     self.bounds = None
                 else:
@@ -2162,7 +2163,7 @@ def serialize(x):
                         )
                         warnings.warn(
                             msg.format(self.name()),
-                            category=iris.exceptions.IrisVagueMetadataWarning,
+                            category=iris.warnings.IrisVagueMetadataWarning,
                         )
 
             if self.has_bounds():

lib/iris/cube.py

@@ -45,6 +45,7 @@
 import iris.coords
 import iris.exceptions
 import iris.util
+import iris.warnings
 
 __all__ = ["Cube", "CubeAttrsDict", "CubeList"]
 
@@ -4054,7 +4055,7 @@ def collapsed(self, coords, aggregator, **kwargs):
                 for coord in lat_match:
                     warnings.warn(
                         msg.format(coord.name()),
-                        category=iris.exceptions.IrisUserWarning,
+                        category=iris.warnings.IrisUserWarning,
                     )
 
         # Determine the dimensions we need to collapse (and those we don't)
@@ -4608,7 +4609,7 @@ def rolling_window(self, coord, aggregator, window, **kwargs):
                 warnings.warn(
                     "The bounds of coordinate %r were ignored in "
                     "the rolling window operation." % coord_.name(),
-                    category=iris.exceptions.IrisIgnoringBoundsWarning,
+                    category=iris.warnings.IrisIgnoringBoundsWarning,
                 )
 
             if coord_.ndim != 1: