Function warn_until

salt/utils/versions.py:112–199

Helper function to raise a warning, by default, a ``DeprecationWarning``, until the provided ``version``, after which, a ``RuntimeError`` will be raised to remind the developers to remove the warning because the target version has been reached. :param version: The version info

(
    version,
    message,
    category=DeprecationWarning,
    stacklevel=None,
    _version_info_=None,
    _dont_call_warnings=False,
)

def warn_until(
    version,
    message,
    category=DeprecationWarning,
    stacklevel=None,
    _version_info_=None,
    _dont_call_warnings=False,
):
    """
    Helper function to raise a warning, by default, a ``DeprecationWarning``,
    until the provided ``version``, after which, a ``RuntimeError`` will
    be raised to remind the developers to remove the warning because the
    target version has been reached.

    :param version: The version info or name after which the warning becomes a ``RuntimeError``.
                    For example ``(2019, 2)``, ``3000``, ``Hydrogen`` or an instance of
                    :class:`salt.version.SaltStackVersion` or :class:`salt.version.SaltVersion`.
    :param message: The warning message to be displayed.
    :param category: The warning class to be thrown, by default
                     ``DeprecationWarning``
    :param stacklevel: There should be no need to set the value of
                       ``stacklevel``. Salt should be able to do the right thing.
    :param _version_info_: In order to reuse this function for other SaltStack
                           projects, they need to be able to provide the
                           version info to compare to.
    :param _dont_call_warnings: This parameter is used just to get the
                                functionality until the actual error is to be
                                issued. When we're only after the salt version
                                checks to raise a ``RuntimeError``.
    """
    if isinstance(version, salt.version.SaltVersion):
        version = salt.version.SaltStackVersion(*version.info)
    elif isinstance(version, int):
        version = salt.version.SaltStackVersion(version)
    elif isinstance(version, tuple):
        version = salt.version.SaltStackVersion(*version)
    elif isinstance(version, str):
        if version.lower() not in salt.version.SaltStackVersion.LNAMES:
            raise RuntimeError(
                "Incorrect spelling for the release name in the warn_utils "
                "call. Expecting one of these release names: {}".format(
                    [vs.name for vs in salt.version.SaltVersionsInfo.versions()]
                )
            )
        version = salt.version.SaltStackVersion.from_name(version)
    elif not isinstance(version, salt.version.SaltStackVersion):
        raise RuntimeError(
            "The 'version' argument should be passed as a tuple, integer, string or "
            "an instance of 'salt.version.SaltVersion' or "
            "'salt.version.SaltStackVersion'."
        )

    if stacklevel is None:
        # Attribute the warning to the calling function, not to warn_until()
        stacklevel = 2

    if _version_info_ is None:
        _version_info_ = salt.version.__version_info__