intermediate changes

ref:68b1302de4b5da30b6bdf02193f7a2604d8b5cf8

1 files changed, 95 insertions, 15 deletions

diff --git a/contrib/python/pytest/py3/_pytest/outcomes.py b/contrib/python/pytest/py3/_pytest/outcomes.py
index 8f6203fd7f..25206fe0e8 100644
--- a/contrib/python/pytest/py3/_pytest/outcomes.py
+++ b/contrib/python/pytest/py3/_pytest/outcomes.py
@@ -1,6 +1,7 @@
 """Exception classes and constants handling test outcomes as well as
 functions creating them."""
 import sys
+import warnings
 from typing import Any
 from typing import Callable
 from typing import cast
@@ -8,6 +9,8 @@ from typing import Optional
 from typing import Type
 from typing import TypeVar
 
+from _pytest.deprecated import KEYWORD_MSG_ARG
+
 TYPE_CHECKING = False  # Avoid circular import through compat.
 
 if TYPE_CHECKING:
@@ -33,7 +36,7 @@ class OutcomeException(BaseException):
                 "Perhaps you meant to use a mark?"
             )
             raise TypeError(error_msg.format(type(self).__name__, type(msg).__name__))
-        BaseException.__init__(self, msg)
+        super().__init__(msg)
         self.msg = msg
         self.pytrace = pytrace
 
@@ -58,9 +61,14 @@ class Skipped(OutcomeException):
         msg: Optional[str] = None,
         pytrace: bool = True,
         allow_module_level: bool = False,
+        *,
+        _use_item_location: bool = False,
     ) -> None:
-        OutcomeException.__init__(self, msg=msg, pytrace=pytrace)
+        super().__init__(msg=msg, pytrace=pytrace)
         self.allow_module_level = allow_module_level
+        # If true, the skip location is reported as the item's location,
+        # instead of the place that raises the exception/calls skip().
+        self._use_item_location = _use_item_location
 
 
 class Failed(OutcomeException):
@@ -105,52 +113,124 @@ def _with_exception(exception_type: _ET) -> Callable[[_F], _WithException[_F, _E
 
 
 @_with_exception(Exit)
-def exit(msg: str, returncode: Optional[int] = None) -> "NoReturn":
+def exit(
+    reason: str = "", returncode: Optional[int] = None, *, msg: Optional[str] = None
+) -> "NoReturn":
     """Exit testing process.
 
-    :param str msg: Message to display upon exit.
-    :param int returncode: Return code to be used when exiting pytest.
+    :param reason:
+        The message to show as the reason for exiting pytest.  reason has a default value
+        only because `msg` is deprecated.
+
+    :param returncode:
+        Return code to be used when exiting pytest.
+
+    :param msg:
+        Same as ``reason``, but deprecated. Will be removed in a future version, use ``reason`` instead.
     """
     __tracebackhide__ = True
-    raise Exit(msg, returncode)
+    from _pytest.config import UsageError
+
+    if reason and msg:
+        raise UsageError(
+            "cannot pass reason and msg to exit(), `msg` is deprecated, use `reason`."
+        )
+    if not reason:
+        if msg is None:
+            raise UsageError("exit() requires a reason argument")
+        warnings.warn(KEYWORD_MSG_ARG.format(func="exit"), stacklevel=2)
+        reason = msg
+    raise Exit(reason, returncode)
 
 
 @_with_exception(Skipped)
-def skip(msg: str = "", *, allow_module_level: bool = False) -> "NoReturn":
+def skip(
+    reason: str = "", *, allow_module_level: bool = False, msg: Optional[str] = None
+) -> "NoReturn":
     """Skip an executing test with the given message.
 
     This function should be called only during testing (setup, call or teardown) or
     during collection by using the ``allow_module_level`` flag.  This function can
     be called in doctests as well.
 
-    :param bool allow_module_level:
+    :param reason:
+        The message to show the user as reason for the skip.
+
+    :param allow_module_level:
         Allows this function to be called at module level, skipping the rest
         of the module. Defaults to False.
 
+    :param msg:
+        Same as ``reason``, but deprecated. Will be removed in a future version, use ``reason`` instead.
+
     .. note::
         It is better to use the :ref:`pytest.mark.skipif ref` marker when
         possible to declare a test to be skipped under certain conditions
         like mismatching platforms or dependencies.
-        Similarly, use the ``# doctest: +SKIP`` directive (see `doctest.SKIP
-        <https://docs.python.org/3/library/doctest.html#doctest.SKIP>`_)
+        Similarly, use the ``# doctest: +SKIP`` directive (see :py:data:`doctest.SKIP`)
         to skip a doctest statically.
     """
     __tracebackhide__ = True
-    raise Skipped(msg=msg, allow_module_level=allow_module_level)
+    reason = _resolve_msg_to_reason("skip", reason, msg)
+    raise Skipped(msg=reason, allow_module_level=allow_module_level)
 
 
 @_with_exception(Failed)
-def fail(msg: str = "", pytrace: bool = True) -> "NoReturn":
+def fail(
+    reason: str = "", pytrace: bool = True, msg: Optional[str] = None
+) -> "NoReturn":
     """Explicitly fail an executing test with the given message.
 
-    :param str msg:
+    :param reason:
         The message to show the user as reason for the failure.
-    :param bool pytrace:
+
+    :param pytrace:
         If False, msg represents the full failure information and no
         python traceback will be reported.
+
+    :param msg:
+        Same as ``reason``, but deprecated. Will be removed in a future version, use ``reason`` instead.
+    """
+    __tracebackhide__ = True
+    reason = _resolve_msg_to_reason("fail", reason, msg)
+    raise Failed(msg=reason, pytrace=pytrace)
+
+
+def _resolve_msg_to_reason(
+    func_name: str, reason: str, msg: Optional[str] = None
+) -> str:
+    """
+    Handles converting the deprecated msg parameter if provided into
+    reason, raising a deprecation warning.  This function will be removed
+    when the optional msg argument is removed from here in future.
+
+    :param str func_name:
+        The name of the offending function, this is formatted into the deprecation message.
+
+    :param str reason:
+        The reason= passed into either pytest.fail() or pytest.skip()
+
+    :param str msg:
+        The msg= passed into either pytest.fail() or pytest.skip().  This will
+        be converted into reason if it is provided to allow pytest.skip(msg=) or
+        pytest.fail(msg=) to continue working in the interim period.
+
+    :returns:
+        The value to use as reason.
+
     """
     __tracebackhide__ = True
-    raise Failed(msg=msg, pytrace=pytrace)
+    if msg is not None:
+
+        if reason:
+            from pytest import UsageError
+
+            raise UsageError(
+                f"Passing both ``reason`` and ``msg`` to pytest.{func_name}(...) is not permitted."
+            )
+        warnings.warn(KEYWORD_MSG_ARG.format(func=func_name), stacklevel=3)
+        reason = msg
+    return reason
 
 
 class XFailed(Failed):