import warnings


def deprecated(comment=None, replacement=None):
    """ A decorator which can be used to mark functions as deprecated.
        Emits a DeprecationWarning showing the module and method being flagged
        as deprecated. If replacement is set, the warn will also show which is
        the function or class to be used instead.
    """
    def old(oldcall):
        def new(*args, **kwargs):
            message = "Deprecated: '%s.%s'" % \
                (oldcall.__module__,
                 oldcall.__name__)
            if replacement is not None:
                message += ". Use '%s.%s' instead" % \
                (replacement.__module__,
                 replacement.__name__)
            if comment is not None:
                message += ". %s" % comment
            warnings.warn(message, category=DeprecationWarning, stacklevel=2)
            return oldcall(*args, **kwargs)
        return new
    return old