import functools
import inspect
import sys
import warnings
from collections import Counter
from inspect import iscoroutinefunction

from django.middleware import MiddlewareMixin as _MiddlewareMixin
from django.utils.inspect import signature
from django.utils.warnings import django_file_prefixes


class RemovedInDjango70Warning(DeprecationWarning):
    pass


class RemovedInDjango71Warning(PendingDeprecationWarning):
    pass


RemovedInNextVersionWarning = RemovedInDjango70Warning
RemovedAfterNextVersionWarning = RemovedInDjango71Warning


def __getattr__(name):
    if name == "MiddlewareMixin":
        warnings.warn(
            "Importing MiddlewareMixin from django.utils.deprecation is deprecated. "
            "Import from django.middleware.MiddlewareMixin instead.",
            RemovedInDjango71Warning,
            stacklevel=2,
        )
        return _MiddlewareMixin
    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")


def warn_about_external_use(
    message,
    category,
    *,
    skip_name_prefixes=None,
    skip_frames=0,
    internal_modules=None,
):
    """Issue a warning when a deprecated feature is used outside of Django.

    Skip the warning when called from within Django, to avoid cascading
    warnings when one deprecated feature is implemented on top of another.

    Examine the stack to determine the "effective caller" (the code using the
    deprecated feature). By default, this is the third frame from the top
    (ignoring this helper plus the call site).

    Provide `skip_name_prefixes` (a string or tuple of strings) to skip
    additional frames by prefix-matching each frame's fully qualified name
    (dotted module path plus qualname). `skip_name_prefixes` can be used to
    skip specific functions, all methods in a class, or everything in a module.
    Skipping stops at the first non-matching frame. Useful when a shared helper
    is called through multiple paths of varying depth with a common prefix.

    Provide `skip_frames` (an integer) to skip a fixed number of additional
    frames (e.g., exactly one decorator or shared helper function). If both
    options are provided, `skip_name_prefixes` is applied first.

    Provide `internal_modules` (a tuple of names, defaulting to ("django",)) to
    customize what counts as "internal". A frame is internal when its fully
    qualified name starts with one of these names followed by a dot.

    The warning is issued only if the effective caller (the first non-skipped
    frame) is outside Django, attributed to that frame. If all frames are
    skipped, it falls back to the base of the stack.

    Note: To unconditionally issue a warning identifying the first caller
    outside Django as its source, don't use this function. Instead, use::

        warnings.warn(..., skip_file_prefixes=django_file_prefixes())

    to avoid unnecessary stack inspection overhead.
    """

    if internal_modules is None:
        internal_modules = ("django",)
    if not isinstance(internal_modules, tuple):
        raise TypeError("internal_modules must be a tuple of module names")
    internal_prefixes = tuple(f"{mod}." for mod in internal_modules)

    def get_fq_name(frame):
        mod_name = frame.f_globals.get("__name__", "__main__")
        return f"{mod_name}.{frame.f_code.co_qualname}"

    def back(frame, level):
        if frame is not None:
            return frame.f_back, level + 1
        return None, level

    frame, level = inspect.currentframe(), 0
    try:
        # Back two frames: ignore warn_about_external_use() and its caller.
        frame, level = back(*back(frame, level))

        if skip_name_prefixes is not None:
            while frame and get_fq_name(frame).startswith(skip_name_prefixes):
                frame, level = back(frame, level)

        for _ in range(skip_frames):
            frame, level = back(frame, level)

        is_internal = frame and get_fq_name(frame).startswith(internal_prefixes)
    finally:
        del frame

    if not is_internal:
        warnings.warn(message, category=category, stacklevel=level + 1)


def warn_about_implementation(message, category, target):
    """Issue a warning about a specific function, class, or method definition.

    The warning will point to the source filename and line number where
    'target' is _defined_ (not where it is being _called_ as with other warning
    helpers). Use this to warn about code that isn't currently on the call
    stack, e.g., deprecation based on the return value of a called method or
    inspecting a function's signature to see if it supports an updated API.

    Supported usage:
    warn_about_implementation(message, category, some_function)
    warn_about_implementation(message, category, SomeClass)
    warn_about_implementation(message, category, SomeClass.method)
    warn_about_implementation(message, category, self.method) [a bound method]

    To warn about a property without invoking its descriptor, call with
    'target' set to inspect.getattr_static(class_or_instance, "property_name").
    """
    if inspect.ismethod(target) or isinstance(target, (classmethod, staticmethod)):
        function = target.__func__
    elif inspect.isfunction(target) or inspect.isclass(target):
        function = target
    elif isinstance(target, property):
        function = target.fget
    else:
        raise TypeError(
            "target must be a function, class, bound method, or unbound descriptor "
            "(classmethod, staticmethod, or property)."
        )

    function = inspect.unwrap(function)

    try:
        filename = inspect.getsourcefile(function)
        _, lineno = inspect.getsourcelines(function)
    except (AttributeError, OSError, TypeError):
        # Can't identify the source. Issue the warning generically.
        warnings.warn(message, category, skip_file_prefixes=django_file_prefixes())
        return

    # Find or create the module's warning registry so warning filters work.
    module = function.__module__
    try:
        registry = sys.modules[module].__dict__.setdefault("__warningregistry__", {})
    except (AttributeError, KeyError):
        registry = None

    warnings.warn_explicit(
        message, category, filename, lineno, module=module, registry=registry
    )


class warn_about_renamed_method:
    def __init__(
        self, class_name, old_method_name, new_method_name, deprecation_warning
    ):
        self.class_name = class_name
        self.old_method_name = old_method_name
        self.new_method_name = new_method_name
        self.deprecation_warning = deprecation_warning

    def __call__(self, f):
        def wrapper(*args, **kwargs):
            warnings.warn(
                "`%s.%s` is deprecated, use `%s` instead."
                % (self.class_name, self.old_method_name, self.new_method_name),
                self.deprecation_warning,
                2,
            )
            return f(*args, **kwargs)

        return wrapper


class RenameMethodsBase(type):
    """
    Handles the deprecation paths when renaming a method.

    It does the following:
        1) Define the new method if missing and complain about it.
        2) Define the old method if missing.
        3) Complain whenever an old method is called.

    See #15363 for more details.
    """

    renamed_methods = ()

    def __new__(cls, name, bases, attrs):
        new_class = super().__new__(cls, name, bases, attrs)

        for base in inspect.getmro(new_class):
            class_name = base.__name__
            for renamed_method in cls.renamed_methods:
                old_method_name = renamed_method[0]
                old_method = base.__dict__.get(old_method_name)
                new_method_name = renamed_method[1]
                new_method = base.__dict__.get(new_method_name)
                deprecation_warning = renamed_method[2]
                wrapper = warn_about_renamed_method(class_name, *renamed_method)

                # Define the new method if missing and complain about it
                if not new_method and old_method:
                    warnings.warn(
                        "`%s.%s` method should be renamed `%s`."
                        % (class_name, old_method_name, new_method_name),
                        deprecation_warning,
                        2,
                    )
                    setattr(base, new_method_name, old_method)
                    setattr(base, old_method_name, wrapper(old_method))

                # Define the old method as a wrapped call to the new method.
                if not old_method and new_method:
                    setattr(base, old_method_name, wrapper(new_method))

        return new_class


def deprecate_posargs(deprecation_warning, remappable_names, /):
    """
    Function/method decorator to deprecate some or all positional arguments.

    The decorated function will map any positional arguments after the ``*`` to
    the corresponding keyword arguments and issue a deprecation warning.

    The decorator takes two arguments: a RemovedInDjangoXXWarning warning
    category and a list of parameter names that have been changed from
    positional-or-keyword to keyword-only, in their original positional order.

    Works on both functions and methods. To apply to a class constructor,
    decorate its __init__() method. To apply to a staticmethod or classmethod,
    use @deprecate_posargs after @staticmethod or @classmethod.

    Example: to deprecate passing option1 or option2 as posargs, change::

        def some_func(request, option1, option2=True):
            ...

    to::

        @deprecate_posargs(RemovedInDjangoXXWarning, ["option1", "option2"])
        def some_func(request, *, option1, option2=True):
            ...

    After the deprecation period, remove the decorator (but keep the ``*``)::

        def some_func(request, *, option1, option2=True):
            ...

    Caution: during the deprecation period, do not add any new *positional*
    parameters or change the remaining ones. For example, this attempt to add a
    new param would break code using the deprecated posargs::

        @deprecate_posargs(RemovedInDjangoXXWarning, ["option1", "option2"])
        def some_func(request, wrong_new_param=None, *, option1, option2=True):
            # Broken: existing code may pass a value intended as option1 in the
            # wrong_new_param position.
            ...

    However, it's acceptable to add new *keyword-only* parameters and to
    re-order the existing ones, so long as the list passed to
    @deprecate_posargs is kept in the original posargs order. This change will
    work without breaking existing code::

        @deprecate_posargs(RemovedInDjangoXXWarning, ["option1", "option2"])
        def some_func(request, *, new_param=None, option2=True, option1):
            ...

    The @deprecate_posargs decorator adds a small amount of overhead. In most
    cases it won't be significant, but use with care in performance-critical
    code paths.
    """

    def decorator(func):
        if isinstance(func, type):
            raise TypeError(
                "@deprecate_posargs cannot be applied to a class. (Apply it "
                "to the __init__ method.)"
            )
        if isinstance(func, classmethod):
            raise TypeError("Apply @classmethod before @deprecate_posargs.")
        if isinstance(func, staticmethod):
            raise TypeError("Apply @staticmethod before @deprecate_posargs.")

        params = signature(func).parameters
        num_by_kind = Counter(param.kind for param in params.values())

        if num_by_kind[inspect.Parameter.VAR_POSITIONAL] > 0:
            raise TypeError(
                "@deprecate_posargs() cannot be used with variable positional `*args`."
            )

        num_positional_params = (
            num_by_kind[inspect.Parameter.POSITIONAL_ONLY]
            + num_by_kind[inspect.Parameter.POSITIONAL_OR_KEYWORD]
        )
        num_keyword_only_params = num_by_kind[inspect.Parameter.KEYWORD_ONLY]
        if num_keyword_only_params < 1:
            raise TypeError(
                "@deprecate_posargs() requires at least one keyword-only parameter "
                "(after a `*` entry in the parameters list)."
            )
        if any(
            name not in params or params[name].kind != inspect.Parameter.KEYWORD_ONLY
            for name in remappable_names
        ):
            raise TypeError(
                "@deprecate_posargs() requires all remappable_names to be "
                "keyword-only parameters."
            )

        num_remappable_args = len(remappable_names)
        max_positional_args = num_positional_params + num_remappable_args

        func_name = func.__name__
        if func_name == "__init__":
            # In the warning, show "ClassName()" instead of "__init__()".
            # The class isn't defined yet, but its name is in __qualname__.
            # Some examples of __qualname__:
            # - ClassName.__init__
            # - Nested.ClassName.__init__
            # - MyTests.test_case.<locals>.ClassName.__init__
            local_name = func.__qualname__.rsplit("<locals>.", 1)[-1]
            class_name = local_name.replace(".__init__", "")
            func_name = class_name

        def remap_deprecated_args(args, kwargs):
            """
            Move deprecated positional args to kwargs and issue a warning.
            Return updated (args, kwargs).
            """
            if (num_positional_args := len(args)) > max_positional_args:
                raise TypeError(
                    f"{func_name}() takes at most {max_positional_args} positional "
                    f"argument(s) (including {num_remappable_args} deprecated) but "
                    f"{num_positional_args} were given."
                )

            # Identify which of the _potentially remappable_ params are
            # actually _being remapped_ in this particular call.
            remapped_names = remappable_names[
                : num_positional_args - num_positional_params
            ]
            conflicts = set(remapped_names) & set(kwargs)
            if conflicts:
                # Report duplicate names in the original parameter order.
                conflicts_str = ", ".join(
                    f"'{name}'" for name in remapped_names if name in conflicts
                )
                raise TypeError(
                    f"{func_name}() got both deprecated positional and keyword "
                    f"argument values for {conflicts_str}."
                )

            # Do the remapping.
            remapped_kwargs = dict(
                zip(remapped_names, args[num_positional_params:], strict=True)
            )
            remaining_args = args[:num_positional_params]
            updated_kwargs = kwargs | remapped_kwargs

            # Issue the deprecation warning.
            remapped_names_str = ", ".join(f"'{name}'" for name in remapped_names)
            warnings.warn(
                f"Passing positional argument(s) {remapped_names_str} to {func_name}() "
                "is deprecated. Use keyword arguments instead.",
                deprecation_warning,
                skip_file_prefixes=django_file_prefixes(),
            )

            return remaining_args, updated_kwargs

        if iscoroutinefunction(func):

            @functools.wraps(func)
            async def wrapper(*args, **kwargs):
                if len(args) > num_positional_params:
                    args, kwargs = remap_deprecated_args(args, kwargs)
                return await func(*args, **kwargs)

        else:

            @functools.wraps(func)
            def wrapper(*args, **kwargs):
                if len(args) > num_positional_params:
                    args, kwargs = remap_deprecated_args(args, kwargs)
                return func(*args, **kwargs)

        return wrapper

    return decorator