exceptions.py

# Copyright Iris contributors
#
# 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.
"""Exceptions specific to the Iris package."""
from functools import lru_cache
import traceback
import warnings


class IrisError(Exception):
    """Base class for errors in the Iris package."""

    pass


class CoordinateCollapseError(IrisError):
    """Raised when a requested coordinate cannot be collapsed."""

    pass


class CoordinateNotFoundError(KeyError):
    """Raised when a search yields no coordinates."""

    pass


class CellMeasureNotFoundError(KeyError):
    """Raised when a search yields no cell measures."""

    pass


class AncillaryVariableNotFoundError(KeyError):
    """Raised when a search yields no ancillary variables."""

    pass


class ConnectivityNotFoundError(KeyError):
    """Raised when a search yields no connectivities."""

    pass


class CoordinateMultiDimError(ValueError):
    """Raised when a routine doesn't support multi-dimensional coordinates."""

    def __init__(self, msg):
        # N.B. deferred import to avoid a circular import dependency.
        import iris.coords

        if isinstance(msg, iris.coords.Coord):
            fmt = "Multi-dimensional coordinate not supported: '%s'"
            msg = fmt % msg.name()
        ValueError.__init__(self, msg)


class CoordinateNotRegularError(ValueError):
    """Raised when a coordinate is unexpectedly irregular."""

    pass


class InvalidCubeError(IrisError):
    """Raised when a Cube validation check fails."""

    pass


class ConstraintMismatchError(IrisError):
    """Raised when a constraint operation has failed to find the correct number of results."""

    pass


class NotYetImplementedError(IrisError):
    """Raised by missing functionality.

    Different meaning to NotImplementedError, which is for abstract methods.

    """

    pass


class TranslationError(IrisError):
    """Raised when Iris is unable to translate format-specific codes."""

    pass


class IgnoreCubeException(IrisError):
    """Raised from a callback function when a cube should be ignored on load."""

    pass


class ConcatenateError(IrisError):
    """Raised when concatenate is expected to produce a single cube, but fails to do so."""

    def __init__(self, differences):
        """Create a ConcatenateError with a list of textual descriptions of differences.

        Create a ConcatenateError with a list of textual descriptions of
        the differences which prevented a concatenate.

        Parameters
        ----------
        differences : list of str
            The list of strings which describe the differences.

        """
        self.differences = differences

    def __str__(self):
        return "\n  ".join(
            ["failed to concatenate into a single cube."] + list(self.differences)
        )


class MergeError(IrisError):
    """Raised when merge is expected to produce a single cube, but fails to do so."""

    def __init__(self, differences):
        """Create a MergeError with a list of textual descriptions of the differences.

        Creates a MergeError with a list of textual descriptions of
        the differences which prevented a merge.

        Parameters
        ----------
        differences : list of str
            The list of strings which describe the differences.

        """
        self.differences = differences

    def __str__(self):
        return "\n  ".join(
            ["failed to merge into a single cube."] + list(self.differences)
        )


class DuplicateDataError(MergeError):
    """Raised when merging two or more cubes that have identical metadata."""

    def __init__(self, msg):
        self.differences = [msg]


class LazyAggregatorError(Exception):
    pass


class UnitConversionError(IrisError):
    """Raised when Iris is unable to convert a unit."""

    pass


class CannotAddError(ValueError):
    """Raised when an object (e.g. coord) cannot be added to a :class:`~iris.cube.Cube`."""

    pass


###############################################################################
# WARNINGS
# Please namespace all warning objects (i.e. prefix with Iris...).


class IrisUserWarning(UserWarning):
    r"""Base class for :class:`UserWarning` generated by Iris."""

    pass


class IrisLoadWarning(IrisUserWarning):
    """Any warning relating to loading."""

    pass


class IrisSaveWarning(IrisUserWarning):
    """Any warning relating to saving."""

    pass


class IrisCfWarning(IrisUserWarning):
    """Any warning relating to :term:`CF Conventions` ."""

    pass


class IrisIgnoringWarning(IrisUserWarning):
    """Any warning that involves an Iris operation not using some information.

    E.g. :class:`~iris.aux_factory.AuxCoordFactory` generation disregarding
    bounds.
    """

    pass


class IrisDefaultingWarning(IrisUserWarning):
    """Any warning that involves Iris changing invalid/missing information.

    E.g. creating a :class:`~iris.coords.AuxCoord` from an invalid
    :class:`~iris.coords.DimCoord` definition.
    """

    pass


class IrisVagueMetadataWarning(IrisUserWarning):
    """Warnings where object metadata may not be fully descriptive."""

    pass


class IrisUnsupportedPlottingWarning(IrisUserWarning):
    """Warnings where support for a plotting module/function is not guaranteed."""

    pass


class IrisImpossibleUpdateWarning(IrisUserWarning):
    """Warnings where it is not possible to update an object.

    Mainly generated during regridding where the necessary information for
    updating an :class:`~iris.aux_factory.AuxCoordFactory` is no longer
    present.
    """

    pass


class IrisGeometryExceedWarning(IrisUserWarning):
    """:mod:`iris.analysis.geometry` warnings about geometry exceeding dimensions."""

    pass


class IrisMaskValueMatchWarning(IrisUserWarning):
    """Warnings where the value representing masked data is actually present in data."""

    pass


########


class IrisCfLoadWarning(IrisCfWarning, IrisLoadWarning):
    """Any warning relating to both loading and :term:`CF Conventions` ."""

    pass


class IrisCfSaveWarning(IrisCfWarning, IrisSaveWarning):
    """Any warning relating to both saving and :term:`CF Conventions` ."""

    pass


class IrisCfInvalidCoordParamWarning(IrisCfLoadWarning):
    """Warnings where incorrect information for CF coord construction is in a file."""

    pass


class IrisCfMissingVarWarning(IrisCfLoadWarning):
    """Warnings where a CF variable references another variable that is not in the file."""

    pass


class IrisCfLabelVarWarning(IrisCfLoadWarning, IrisIgnoringWarning):
    """Warnings where a CF string/label variable is being used inappropriately."""

    pass


class IrisCfNonSpanningVarWarning(IrisCfLoadWarning, IrisIgnoringWarning):
    """Warnings where a CF variable is ignored because it does not span the required dimension."""

    pass


########


class IrisIgnoringBoundsWarning(IrisIgnoringWarning):
    """Warnings where bounds information has not been used by an Iris operation."""

    pass


class IrisCannotAddWarning(IrisIgnoringWarning):
    """Warnings where a member object cannot be added to a :class:`~iris.cube.Cube` ."""

    pass


class IrisGuessBoundsWarning(IrisDefaultingWarning):
    """Warnings where Iris has filled absent bounds information with a best estimate."""

    pass


class IrisPpClimModifiedWarning(IrisSaveWarning, IrisDefaultingWarning):
    """Warnings where a climatology has been modified while saving :term:`Post Processing (PP) Format` ."""

    pass


class IrisFactoryCoordNotFoundWarning(IrisLoadWarning):
    """Warnings where a referenced factory coord can not be found when loading a variable in :term:`NetCDF Format`."""

    pass


class IrisNimrodTranslationWarning(IrisLoadWarning):
    """For unsupported vertical coord types in :mod:`iris.file_formats.nimrod_load_rules`.

    (Pre-dates the full categorisation of Iris UserWarnings).
    """

    pass


class IrisUnknownCellMethodWarning(IrisCfLoadWarning):
    """If a loaded :class:`~iris.coords.CellMethod` is not one the method names known to Iris.

    (Pre-dates the full categorisation of Iris UserWarnings).
    """

    pass


class IrisSaverFillValueWarning(IrisMaskValueMatchWarning, IrisSaveWarning):
    """For fill value complications during Iris file saving :term:`NetCDF Format`.

    (Pre-dates the full categorisation of Iris UserWarnings).
    """

    pass


@lru_cache(None)
def warn_once(msg, type, stacklevel, frame, **kwargs):
    """Raise a warning only if a similar one has not been raised before."""
    warnings.warn(msg, type, stacklevel=stacklevel, **kwargs)


def warn_once_at_level(msg, type=None, stacklevel=0, **kwargs):
    """
    Raise a warning only if a similar one hasn't been raised from the same line
    for a given stack level.
    """
    stacklevel += 1
    frame = traceback.format_stack()[-stacklevel]
    warn_once(msg, type, stacklevel + 1, frame, **kwargs)