ding.utils.deprecation

ding.utils.deprecation

deprecated(since, removed_in, up_to=None)

Overview

Decorate a function to signify its deprecation.

Arguments: - since (:obj:str): the version when the function was first deprecated. - removed_in (:obj:str): the version when the function will be removed. - up_to (:obj:Optional[str]): the new API users should use. Returns: - decorator (:obj:Callable): decorated function. Examples: >>> from ding.utils.deprecation import deprecated >>> @deprecated('0.4.1', '0.5.1') >>> def hello(): >>> print('hello')

Full Source Code

../ding/utils/deprecation.py

1import functools 2import textwrap 3import warnings 4from typing import Optional 5 6 7def deprecated(since: str, removed_in: str, up_to: Optional[str] = None): 8 """ 9 Overview: 10 Decorate a function to signify its deprecation. 11 Arguments: 12 - since (:obj:`str`): the version when the function was first deprecated. 13 - removed_in (:obj:`str`): the version when the function will be removed. 14 - up_to (:obj:`Optional[str]`): the new API users should use. 15 Returns: 16 - decorator (:obj:`Callable`): decorated function. 17 Examples: 18 >>> from ding.utils.deprecation import deprecated 19 >>> @deprecated('0.4.1', '0.5.1') 20 >>> def hello(): 21 >>> print('hello') 22 """ 23 24 def decorator(func): 25 existing_docstring = func.__doc__ or "" 26 27 deprecated_doc = f'.. deprecated:: {since}\n Deprecated and will be removed in version {removed_in}' 28 29 if up_to is not None: 30 deprecated_doc += f', please use `{up_to}` instead.' 31 else: 32 deprecated_doc += '.' 33 34 func.__doc__ = deprecated_doc + "\n\n" + textwrap.dedent(existing_docstring) 35 36 @functools.wraps(func) 37 def wrapper(*args, **kwargs): 38 warning_msg = ( 39 f'API `{func.__module__}.{func.__name__}` is deprecated since version {since} ' 40 f'and will be removed in version {removed_in}' 41 ) 42 if up_to is not None: 43 warning_msg += f", please use `{up_to}` instead." 44 else: 45 warning_msg += "." 46 47 warnings.warn(warning_msg, category=FutureWarning, stacklevel=2) 48 return func(*args, **kwargs) 49 50 return wrapper 51 52 return decorator