from __future__ import annotations

from functools import wraps
import inspect
from inspect import Parameter
from inspect import Signature
from pathlib import Path
from typing import TYPE_CHECKING
from typing import TypeVar
from typing import overload

from typing_extensions import ParamSpec

from pyvista._version import version_info
from pyvista._warn_external import warn_external

if TYPE_CHECKING:
    from collections.abc import Callable

_MAX_POSITIONAL_ARGS = 3  # Should match value in pyproject.toml


P = ParamSpec('P')
T = TypeVar('T')


@overload
def _deprecate_positional_args(
    func: Callable[P, T],
    *,
    version: tuple[int, int] = ...,
    allowed: list[str] | None = ...,
    n_allowed: int = ...,
) -> Callable[P, T]: ...
@overload
def _deprecate_positional_args(
    *, version: tuple[int, int] = ..., allowed: list[str] | None = ..., n_allowed: int = ...
) -> Callable[[Callable[P, T]], Callable[P, T]]: ...
def _deprecate_positional_args(
    func: Callable[..., T] | None = None,
    *,
    version: tuple[int, int] = (0, 50),
    allowed: list[str] | None = None,
    n_allowed: int | None = None,
) -> Callable[..., T] | Callable[[Callable[P, T]], Callable[P, T]]:
    """Use a decorator to deprecate positional arguments.

    Parameters
    ----------
    func : callable, default=None
        Function to check arguments on.

    version : tuple[int, int], default: (0, 50)
        The version (major, minor) when positional arguments will result in RuntimeError.

    allowed : list[str], optional
        List of argument names which are allowed to be positional. This value is limited
        based on rule PLR0917.

    n_allowed : int, optional
        Override the number of allowed positional arguments to this value.

    """

    def _inner_deprecate_positional_args(f: Callable[P, T]) -> Callable[P, T]:
        def qualified_name() -> str:
            return f.__qualname__ if hasattr(f, '__qualname__') else f.__name__

        decorator_name = _deprecate_positional_args.__name__
        sig = inspect.signature(f)
        param_names = list(sig.parameters)

        # Validate n_allowed itself
        if n_allowed:
            if n_allowed <= _MAX_POSITIONAL_ARGS:
                msg = (
                    f'In decorator {decorator_name!r} for function {qualified_name()!r}:\n'
                    f'`n_allowed` must be greater than {_MAX_POSITIONAL_ARGS} for it to be useful.'
                )
                raise ValueError(msg)
            n_allowed_ = n_allowed
        else:
            n_allowed_ = _MAX_POSITIONAL_ARGS

        if allowed is not None:
            # Validate input type
            if not isinstance(allowed, list):
                msg = (  # type: ignore[unreachable]
                    f'In decorator {decorator_name!r} for function {qualified_name()!r}:\n'
                    f'Allowed arguments must be a list, got {type(allowed)}.'
                )
                raise TypeError(msg)

            # Validate number of allowed args
            if len(allowed) > n_allowed_:
                msg = (
                    f'In decorator {decorator_name!r} for function {qualified_name()!r}:\n'
                    f'A maximum of {n_allowed_} positional arguments are allowed.\n'
                    f'Got {len(allowed)}: {allowed}'
                )
                raise ValueError(msg)

            # Validate allowed against actual parameter names
            for name in allowed:
                if name not in param_names:
                    msg = (
                        f'Allowed positional argument {name!r} in decorator '
                        f'{decorator_name!r}\n'
                        f'is not a parameter of function {qualified_name()!r}.'
                    )
                    raise ValueError(msg)

            # Check that allowed args appears in the same order as in the signature
            sig_allowed = [name for name in param_names if name in allowed]
            if sig_allowed != allowed:
                msg = (
                    f'The `allowed` list {allowed} in decorator {decorator_name!r} is not in the\n'
                    f'same order as the parameters in {qualified_name()!r}.\n'
                    f'Expected order: {sig_allowed}.'
                )
                raise ValueError(msg)

            # Check that allowed args are not already kwonly
            for name in allowed:
                if sig.parameters[name].kind == Parameter.KEYWORD_ONLY:
                    msg = (
                        f'Parameter {name!r} in decorator {decorator_name!r} is already '
                        f'keyword-only\nand should be removed from the allowed list.'
                    )
                    raise ValueError(msg)

        # Check if the decorator is even needed at all
        n_positional = 0
        for name in param_names:
            if name not in ['cls', 'self'] and sig.parameters[name].kind in [
                Parameter.POSITIONAL_ONLY,
                Parameter.POSITIONAL_OR_KEYWORD,
            ]:
                n_positional += 1
        actual_n_allowed = len(allowed) if allowed else 0
        if n_positional <= actual_n_allowed:
            msg = (
                f'Function {qualified_name()!r} has {actual_n_allowed} positional arguments, '
                f'which is less than or equal to the\nmaximum number of allowed positional '
                f'arguments ({n_allowed_}).\nThis decorator is not necessary and can be removed.'
            )
            raise RuntimeError(msg)

        # Raise error post-deprecation
        if version_info >= version:
            # Construct expected positional args and signature
            new_parameters = []
            max_args_to_print = actual_n_allowed + 2
            cls_or_self = 'cls' in param_names or 'self' in param_names
            max_args_to_print = (max_args_to_print + 1) if cls_or_self else max_args_to_print
            has_too_many_to_print = False
            for i, name in enumerate(param_names):
                if i > max_args_to_print:
                    has_too_many_to_print = True
                    break
                if name in ['cls', 'self', *(allowed or [])]:
                    current_kind = sig.parameters[name].kind
                    new_kind = (
                        current_kind
                        if current_kind != Parameter.KEYWORD_ONLY
                        else Parameter.KEYWORD_ONLY
                    )
                    new_parameters.append(Parameter(name, kind=new_kind))
                else:
                    new_parameters.append(Parameter(name, kind=Parameter.KEYWORD_ONLY))

            signature_string = f'{qualified_name()}{Signature(new_parameters)}'
            if has_too_many_to_print:
                # Replace ending bracket with ellipses
                signature_string = f'{signature_string[:-1]}, ...)'

            # Get source file and line number
            file = Path(inspect.getfile(f)).as_posix()
            lineno = inspect.getsourcelines(f)[1]
            location = f'{file}:{lineno}'

            msg = (
                f'Positional arguments are no longer allowed in {qualified_name()!r}.\n'
                f'Update the function signature at:\n'
                f'{location} to enforce keyword-only args:\n'
                f'    {signature_string}\n'
                f'and remove the {decorator_name!r} decorator.'
            )
            raise RuntimeError(msg)

        @wraps(f)
        def inner_f(*args: P.args, **kwargs: P.kwargs) -> T:
            passed_positional_names = param_names[: len(args)]

            # Exclude allowed ones
            if allowed:
                offending_args = [name for name in passed_positional_names if name not in allowed]
            else:
                offending_args = passed_positional_names

            if 'self' in offending_args:
                offending_args.remove('self')
            if 'cls' in offending_args:
                offending_args.remove('cls')

            if offending_args:
                # Craft a message to print a warning or raise an error
                if len(offending_args) == 1:
                    a = ' a '
                    s = ''
                    this = 'this'
                else:
                    a = ' '
                    s = 's'
                    this = 'these'

                if version_info < version:
                    # Print warning
                    version_str = '.'.join(map(str, version))
                    arg_list = ', '.join(f'{a!r}' for a in offending_args)
                    stack_level = 3

                    def call_site() -> str:
                        # Get location where the function is called
                        frame = inspect.stack()[stack_level]
                        file = Path(frame.filename).as_posix()
                        return f'{file}:{frame.lineno}'

                    def warn_positional_args() -> None:
                        from pyvista.core.errors import PyVistaDeprecationWarning  # noqa: PLC0415

                        msg = (
                            f'\n{call_site()}: '
                            f'Argument{s} {arg_list} must be passed as{a}keyword argument{s} '
                            f'to function {qualified_name()!r}.\n'
                            f'From version {version_str}, passing {this} as{a}positional '
                            f'argument{s} will result in a TypeError.'
                        )
                        warn_external(msg, PyVistaDeprecationWarning)

                    warn_positional_args()

            return f(*args, **kwargs)

        return inner_f

    if func is not None:
        return _inner_deprecate_positional_args(func)
    return _inner_deprecate_positional_args
