Source code for iris._deprecation

# 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.
"""Utilities for producing runtime deprecation messages."""

import warnings

[docs] class IrisDeprecation(UserWarning): """An Iris deprecation warning. Note this subclasses UserWarning for backwards compatibility with Iris' original deprecation warnings. Should subclass DeprecationWarning at the next major release. """ pass
def warn_deprecated(msg, stacklevel=2): """Issue an Iris deprecation warning. Calls :func:`warnings.warn', to emit the message 'msg' as a :class:`warnings.warning`, of the subclass :class:`IrisDeprecationWarning`. The 'stacklevel' keyword is passed through to warnings.warn. However by default this is set to 2, which ensures that the identified code line is in the caller, rather than in this routine. See :mod:`warnings` module documentation. For example:: >>> from iris._deprecation import warn_deprecated >>> def arrgh(): ... warn_deprecated('"arrgh" is deprecated since version 3.5.') ... return 1 ... >>> arrgh() __main__:2: IrisDeprecation: "arrgh" is deprecated since version 3.5. 1 >>> arrgh() 1 >>> """ warnings.warn(msg, category=IrisDeprecation, stacklevel=stacklevel) # A Mixin for a wrapper class that copies the docstring of the wrapped class # into the wrapper. # This is useful in producing wrapper classes that need to mimic the original # but emit deprecation warnings when used. class ClassWrapperSameDocstring(type): def __new__(metacls, classname, bases, class_dict): # Patch the subclass to duplicate the class docstring from the wrapped # class, and give it a special '__new__' that issues a deprecation # warning when creating an instance. parent_class = bases[0] # Copy the original class docstring. class_dict["__doc__"] = parent_class.__doc__ # Return the result. return super().__new__(metacls, classname, bases, class_dict)