Source code for ray.rllib.utils.deprecation

import inspect
import logging
from typing import Optional, Union

from ray.util import log_once
from ray.util.annotations import _mark_annotated

logger = logging.getLogger(__name__)

# A constant to use for any configuration that should be deprecated
# (to check, whether this config has actually been assigned a proper value or
# not).
DEPRECATED_VALUE = -1


[docs]def deprecation_warning( old: str, new: Optional[str] = None, *, help: Optional[str] = None, error: Optional[Union[bool, Exception]] = None, ) -> None: """Warns (via the `logger` object) or throws a deprecation warning/error. Args: old: A description of the "thing" that is to be deprecated. new: A description of the new "thing" that replaces it. help: An optional help text to tell the user, what to do instead of using `old`. error: Whether or which exception to raise. If True, raise ValueError. If False, just warn. If `error` is-a subclass of Exception, raise that Exception. Raises: ValueError: If `error=True`. Exception: Of type `error`, iff `error` is a sub-class of `Exception`. """ msg = "`{}` has been deprecated.{}".format( old, (" Use `{}` instead.".format(new) if new else f" {help}" if help else "") ) if error is True: raise DeprecationWarning(msg) elif error and issubclass(error, Exception): raise error(msg) else: logger.warning( "DeprecationWarning: " + msg + " This will raise an error in the future!" )
[docs]def Deprecated(old=None, *, new=None, help=None, error): """Decorator for documenting a deprecated class, method, or function. Automatically adds a `deprecation.deprecation_warning(old=..., error=False)` to not break existing code at this point to the decorated class' constructor, method, or function. In a next major release, this warning should then be made an error (by setting error=True), which means at this point that the class/method/function is no longer supported, but will still inform the user about the deprecation event. In a further major release, the class, method, function should be erased entirely from the codebase. Examples: >>> from ray.rllib.utils.deprecation import Deprecated >>> # Deprecated class: Patches the constructor to warn if the class is ... # used. ... @Deprecated(new="NewAndMuchCoolerClass", error=False) ... class OldAndUncoolClass: ... ... >>> # Deprecated class method: Patches the method to warn if called. ... class StillCoolClass: ... ... ... @Deprecated(new="StillCoolClass.new_and_much_cooler_method()", ... error=False) ... def old_and_uncool_method(self, uncool_arg): ... ... >>> # Deprecated function: Patches the function to warn if called. ... @Deprecated(new="new_and_much_cooler_function", error=False) ... def old_and_uncool_function(*uncool_args): ... ... """ def _inner(obj): # A deprecated class. if inspect.isclass(obj): # Patch the class' init method to raise the warning/error. obj_init = obj.__init__ def patched_init(*args, **kwargs): if log_once(old or obj.__name__): deprecation_warning( old=old or obj.__name__, new=new, help=help, error=error, ) return obj_init(*args, **kwargs) obj.__init__ = patched_init _mark_annotated(obj) # Return the patched class (with the warning/error when # instantiated). return obj # A deprecated class method or function. # Patch with the warning/error at the beginning. def _ctor(*args, **kwargs): if log_once(old or obj.__name__): deprecation_warning( old=old or obj.__name__, new=new, help=help, error=error, ) # Call the deprecated method/function. return obj(*args, **kwargs) # Return the patched class method/function. return _ctor # Return the prepared decorator. return _inner