Source code for qblox_scheduler.helpers.deprecation

# Repository: https://gitlab.com/qblox/packages/software/qblox-scheduler
# Licensed according to the LICENSE file on the main branch
#
# Copyright 2020-2025, Quantify Consortium
# Copyright 2025, Qblox B.V.
"""Helper functions for code deprecation."""

from __future__ import annotations

import functools
import warnings
from typing import TYPE_CHECKING, Any

if TYPE_CHECKING:
    from collections.abc import Callable




def deprecated_arg_alias(depr_version: str, **aliases: str) -> Callable:
    """
    Decorator for deprecated function and method arguments.

    From: https://stackoverflow.com/questions/49802412/how-to-implement-deprecation-in-python-with-argument-alias/49802489#49802489

    Use as follows:

    .. code-block:: python

        @deprecated_arg_alias("0.x.0", old_arg="new_arg")
        def myfunc(new_arg):
            ...

    Parameters
    ----------
    depr_version
        The qblox-scheduler version in which the parameter names will be removed.
    aliases
        Parameter name aliases provided as ``old="new"``.

    Returns
    -------
    :
        The same function or method, that raises a FutureWarning if a deprecated
        argument is passed, or a TypeError if both the new and the deprecated arguments
        are passed.

    """

    def deco(f: Callable) -> Callable:
        @functools.wraps(f)
        def wrapper(*args, **kwargs):  # noqa: ANN202
            func_name = f.__name__ if f.__name__ != "__init__" else f.__qualname__.split(".")[0]
            _rename_kwargs(func_name, depr_version, kwargs, aliases)
            return f(*args, **kwargs)

        return wrapper

    return deco





def _rename_kwargs(
    func_name: str, depr_version: str, kwargs: dict[str, Any], aliases: dict[str, str]
) -> None:
    """Helper function for deprecating function arguments."""
    for alias, new in aliases.items():
        if alias in kwargs:
            if new in kwargs:
                raise TypeError(
                    f"{func_name} received both {alias} and {new} as arguments! "
                    f"{alias} is deprecated and will be removed in qblox-scheduler "
                    f">= {depr_version}, use {new} instead."
                )
            warnings.warn(
                message=(
                    f"{alias} is deprecated as an argument to {func_name} and will be "
                    f"removed in qblox-scheduler >= {depr_version}; use {new} "
                    "instead."
                ),
                category=FutureWarning,
                stacklevel=3,
            )
            kwargs[new] = kwargs.pop(alias)





def standardize_pulse_info_keys(pulse_data: dict[str, Any]) -> None:
    """
    Replace (in-place) deprecated pulse info arguments with new ones.

    Currently: amp, gain => amplitude.
    """
    deprecated_amp = pulse_data.pop("amp", None)
    deprecated_gain = pulse_data.pop("gain", None)

    if deprecated_amp is not None or deprecated_gain is not None:
        msg = (
            "amp and gain are deprecated as a key in pulse_info and will be removed "
            "in qblox-scheduler >= 2.0;"
        )
        if "amplitude" in pulse_data:
            msg += " amplitude will be used."
        else:
            pulse_data["amplitude"] = (
                deprecated_amp if deprecated_amp is not None else deprecated_gain
            )
            msg += " use amplitude instead."

        warnings.warn(msg, category=FutureWarning, stacklevel=3)