# Copyright 2021-2022 VMware, Inc.
# SPDX-License-Identifier: Apache-2.0
#
import inspect
import pathlib
import sys
import warnings
from typing import Any
from typing import Callable
from typing import Dict
from typing import Optional
from typing import Tuple
from typing import Type
from typing import TYPE_CHECKING
from typing import Union
import packaging.version
import pytestshellutils
if TYPE_CHECKING:
from packaging.version import Version
[docs]def resolved_pathlib_path(path: Union[str, pathlib.Path]) -> pathlib.Path:
"""
Return a resolved ``pathlib.Path``.
"""
if isinstance(path, str):
path = pathlib.Path(path)
return path.resolve()
[docs]def warn_until(
version: str,
message: str,
category: Type[Warning] = DeprecationWarning,
stacklevel: Optional[int] = None,
_dont_call_warnings: bool = False,
_pkg_version_: Optional[str] = None,
) -> None:
"""
Show a deprecation warning.
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 string after which the warning becomes a ``RuntimeError``.
For example ``2.1``.
: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``.
: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 version checks to
raise a ``RuntimeError``.
"""
_version = packaging.version.parse(version)
if _pkg_version_ is None:
_pkg_version_ = pytestshellutils.__version__ # type: ignore[attr-defined]
_pkg_version = packaging.version.parse(_pkg_version_)
if stacklevel is None:
# Attribute the warning to the calling function, not to warn_until()
stacklevel = 3
if _pkg_version >= _version:
caller = inspect.getframeinfo(sys._getframe(stacklevel - 1))
raise RuntimeError(
"The warning triggered on filename '{filename}', line number "
"{lineno}, is supposed to be shown until version "
"{until_version} is released. Current version is now "
"{version}. Please remove the warning.".format(
filename=caller.filename,
lineno=caller.lineno,
until_version=_pkg_version_,
version=version,
),
)
if _dont_call_warnings is False:
warnings.warn(
message.format(version=version),
category,
stacklevel=stacklevel,
)