# Copyright (c) 2009, 2025, Oracle and/or its affiliates.
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License, version 2.0, as
# published by the Free Software Foundation.
#
# This program is designed to work with certain software (including
# but not limited to OpenSSL) that is licensed under separate terms,
# as designated in a particular file or component or in included license
# documentation. The authors of MySQL hereby grant you an
# additional permission to link the program and your derivative works
# with the separately licensed software that they have either included with
# the program or referenced in the documentation.
#
# Without limiting anything contained in the foregoing, this file,
# which is part of MySQL Connector/Python, is also subject to the
# Universal FOSS Exception, version 1.0, a copy of which can be found at
# http://oss.oracle.com/licenses/universal-foss-exception.
#
# This program is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
# See the GNU General Public License, version 2.0, for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software Foundation, Inc.,
# 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA

"""Decorators Hub."""

import functools
import warnings

from typing import TYPE_CHECKING, Any, Callable

from .constants import RefreshOption

if TYPE_CHECKING:
    from .abstracts import MySQLConnectionAbstract


def cmd_refresh_verify_options() -> Callable:
    """Decorator verifying which options are relevant and which aren't based on
    the server version the client is connecting to."""

    def decorator(cmd_refresh: Callable) -> Callable:
        @functools.wraps(cmd_refresh)
        def wrapper(
            cnx: "MySQLConnectionAbstract", *args: Any, **kwargs: Any
        ) -> Callable:
            options: int = args[0]
            if (options & RefreshOption.GRANT) and cnx.server_version >= (
                9,
                2,
                0,
            ):
                warnings.warn(
                    "As of MySQL Server 9.2.0, refreshing grant tables is not needed "
                    "if you use statements GRANT, REVOKE, CREATE, DROP, or ALTER. "
                    "You should expect this option to be unsupported in a future "
                    "version of MySQL Connector/Python when MySQL Server removes it.",
                    category=DeprecationWarning,
                    stacklevel=1,
                )

            return cmd_refresh(cnx, options, **kwargs)

        return wrapper

    return decorator


def handle_read_write_timeout() -> Callable:
    """
    Decorator to close the current connection if a read or a write timeout
    is raised by the method passed via the func parameter.
    """

    def decorator(cnx_method: Callable) -> Callable:
        @functools.wraps(cnx_method)
        def handle_cnx_method(
            cnx: "MySQLConnectionAbstract", *args: Any, **kwargs: Any
        ) -> Any:
            try:
                return cnx_method(cnx, *args, **kwargs)
            except Exception as err:
                if isinstance(err, TimeoutError):
                    cnx.close()
                raise err

        return handle_cnx_method

    return decorator


def deprecated(reason: str) -> Callable:
    """Use it to decorate deprecated methods."""

    def decorator(func: Callable) -> Callable:
        @functools.wraps(func)
        def wrapper(*args: Any, **kwargs: Any) -> Callable:
            warnings.warn(
                f"Call to deprecated function {func.__name__}. Reason: {reason}",
                category=DeprecationWarning,
                stacklevel=2,
            )
            return func(*args, **kwargs)

        return wrapper

    return decorator