Deprecation Tools/Utils

ray.rllib.utils.deprecation.deprecation_warning(old: str, new: Optional[str] = None, *, help: Optional[str] = None, error: Optional[Union[bool, Exception]] = None) None[source]

Warns (via the logger object) or throws a deprecation warning/error.

Parameters
  • 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.

ray.rllib.utils.deprecation.Deprecated(old=None, *, new=None, help=None, error)[source]

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):
...     ...