Refactor warnings from iris.exceptions into iris.warnings

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).
@@ -48,7 +48,7 @@ Warnings:
  >>> my_operation()
  ...
  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.exceptions.IrisUserWarning)
+ 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(
 
@@ -111,7 +111,7 @@ You can target specific Warning messages, e.g.
  ... my_operation()
  ...
  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.exceptions.IrisUserWarning)
+ warnings.warn(wmsg, category=iris.warnings.IrisUserWarning)
 
 ::
 
@@ -176,33 +176,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: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.exceptions.IrisUserWarning)
+ 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()
 
@@ -220,10 +220,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:
@@ -911,7 +912,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__)
@@ -941,7 +942,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):
@@ -439,7 +439,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
 
@@ -768,7 +768,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):
  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"]
 
@@ -4051,7 +4052,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)
@@ -4605,7 +4606,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: