Spaces:
Running
Running
File size: 2,097 Bytes
c61ccee |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 |
"""Utility for deprecating functions."""
import functools
import textwrap
import warnings
def deprecated(since: str, removed_in: str, instructions: str):
"""Marks functions as deprecated.
It will result in a warning when the function is called and a note in the
docstring.
Args:
since: The version when the function was first deprecated.
removed_in: The version when the function will be removed.
instructions: The action users should take.
"""
def decorator(function):
@functools.wraps(function)
def wrapper(*args, **kwargs):
warnings.warn(
f"'{function.__module__}.{function.__name__}' "
f"is deprecated in version {since} and will be "
f"removed in {removed_in}. Please {instructions}.",
category=FutureWarning,
stacklevel=2,
)
return function(*args, **kwargs)
# Add a deprecation note to the docstring.
docstring = function.__doc__ or ""
# Add a note to the docstring.
deprecation_note = textwrap.dedent(
f"""\
.. deprecated:: {since}
Deprecated and will be removed in version {removed_in}.
Please {instructions}.
"""
)
# Split docstring at first occurrence of newline
summary_and_body = docstring.split("\n\n", 1)
if len(summary_and_body) > 1:
summary, body = summary_and_body
# Dedent the body. We cannot do this with the presence of the summary because
# the body contains leading whitespaces when the summary does not.
body = textwrap.dedent(body)
new_docstring_parts = [deprecation_note, "\n\n", summary, body]
else:
summary = summary_and_body[0]
new_docstring_parts = [deprecation_note, "\n\n", summary]
wrapper.__doc__ = "".join(new_docstring_parts)
return wrapper
return decorator
|