import warnings
import functools


def deprecated(func):
    """ Decorator to be used to mark functions as deprecated.
    It will result in a warning being emitted when the function is used.

    Usage::

        @other_decorators_must_be_upper
        @deprecated
        def some_old_function(x,y):
            return x + y

        class SomeClass:

            @deprecated
            def some_old_method(self, x,y):
                return x + y
    """

    @functools.wraps(func)
    def new_func(*args, **kwargs):
        warnings.warn_explicit("Call to deprecated function %(funcname)s." % {
                'funcname': func.__name__,
            },
            category=DeprecationWarning,
            filename=func.func_code.co_filename,
            lineno=func.func_code.co_firstlineno + 1
        )
        return func(*args, **kwargs)

    return new_func