import inspect
import warnings


def deprecated(func, solution):
    """
    Mark a parser or combiner as deprecated, and give a message of how to fix
    this.  This will emit a warning in the logs when the function is used.
    When combined with modifications to conftest, this causes deprecations to
    become fatal errors when testing, so they get fixed.

    Arguments:
        func (function): the function or method being deprecated.
        solution (str): a string describing the replacement class, method or
            function that replaces the thing being deprecated.  For example,
            "use the `fnord()` function" or "use the `search()` method with
            the parameter `name='(value)'`".
    """

    def get_name_line(src):
        for line in src:
            if "@" not in line:
                return line.strip()

    path = inspect.getsourcefile(func)
    src, line_no = inspect.getsourcelines(func)
    name = get_name_line(src) or "Unknown"
    the_msg = "<{c}> at {p}:{l} is deprecated: {s}".format(
        c=name, p=path, l=line_no, s=solution
    )

    warnings.warn(the_msg, DeprecationWarning)