def deprecated(since, message='<STR_LIT>', name='<STR_LIT>', alternative='<STR_LIT>', pending=False,<EOL>addendum='<STR_LIT>', removal='<STR_LIT>'):
def deprecate(obj, message=message, name=name, alternative=alternative,<EOL>pending=pending, addendum=addendum):<EOL><INDENT>if not name:<EOL><INDENT>name = obj.__name__<EOL><DEDENT>if isinstance(obj, type):<EOL><INDENT>obj_type = "<STR_LIT:class>"<EOL>old_doc = obj.__doc__<EOL>func = obj.__init__<EOL>def finalize(wrapper, new_doc):<EOL><INDENT>obj.__doc__ = new_doc<EOL>obj.__init__ = wrapper<EOL>return obj<EOL><DEDENT><DEDENT>else:<EOL><INDENT>obj_type = "<STR_LIT>"<EOL>if isinstance(obj, classmethod):<EOL><INDENT>func = obj.__func__<EOL>old_doc = func.__doc__<EOL>def finalize(wrapper, new_doc):<EOL><INDENT>wrapper = functools.wraps(func)(wrapper)<EOL>wrapper.__doc__ = new_doc<EOL>return classmethod(wrapper)<EOL><DEDENT><DEDENT>else:<EOL><INDENT>func = obj<EOL>old_doc = func.__doc__<EOL>def finalize(wrapper, new_doc):<EOL><INDENT>wrapper = functools.wraps(func)(wrapper)<EOL>wrapper.__doc__ = new_doc<EOL>return wrapper<EOL><DEDENT><DEDENT><DEDENT>message = _generate_deprecation_message(<EOL>since, message, name, alternative, pending, obj_type, addendum,<EOL>removal=removal)<EOL>category = (PendingDeprecationWarning if pending<EOL>else _projectWarning)<EOL>def wrapper(*args, **kwargs):<EOL><INDENT>warnings.warn(message, category, stacklevel=<NUM_LIT:2>)<EOL>return func(*args, **kwargs)<EOL><DEDENT>old_doc = textwrap.dedent(old_doc or '<STR_LIT>').strip('<STR_LIT:\n>')<EOL>message = message.strip()<EOL>new_doc = (('<STR_LIT>'<EOL>'<STR_LIT>' %<EOL>{'<STR_LIT>': since, '<STR_LIT:message>': message}) + old_doc)<EOL>if not old_doc:<EOL><INDENT>new_doc += r'<STR_LIT>'<EOL><DEDENT>return finalize(wrapper, new_doc)<EOL><DEDENT>return deprecate<EOL>
Decorator to mark a function or a class as deprecated.
Parameters
----------
since : str
    The release at which this API became deprecated.  This is
    required.
message : str, optional
    Override the default deprecation message.  The format
    specifier `%(name)s` may be used for the name of the object,
    and `%(alternative)s` may be used in the deprecation message
    to insert the name of an alternative to the deprecated
    object.
name : str, optional
    The name of the deprecated object; if not provided the name
    is automatically determined from the passed in object,
    though this is useful in the case of renamed functions, where
    the new function is just assigned to the name of the
    deprecated function.  For example::
        def new_function():
            ...
        oldFunction = new_function
alternative : str, optional
    An alternative API that the user may use in place of the deprecated
    API.  The deprecation warning will tell the user about this alternative
    if provided.
pending : bool, optional
    If True, uses a PendingDeprecationWarning instead of a
    DeprecationWarning.  Cannot be used together with *removal*.
removal : str, optional
    The expected removal version.  With the default (an empty string), a
    removal version is automatically computed from *since*.  Set to other
    Falsy values to not schedule a removal date.  Cannot be used together
    with *pending*.
addendum : str, optional
    Additional text appended directly to the final message.
Examples
--------
    Basic example::
        @deprecated('1.4.0')
        def the_function_to_deprecate():
            pass