[3.13] gh-124234: Improve docs for `Mock.reset_mock` (GH-124237) (#130408)

Co-authored-by: sobolevn <mail@sobolevn.me>

diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst
index 2c3574067a8407b6862b8d04f415833207f811a4..f6c616a353f5ab0df4c590d535fdf20d3e0c1a38 100644 (file)
--- a/Doc/library/unittest.mock.rst
+++ b/Doc/library/unittest.mock.rst
@@ -401,6 +401,8 @@ the *new_callable* argument to :func:`patch`.
 
         The reset_mock method resets all the call attributes on a mock object:
 
+        .. doctest::
+
             >>> mock = Mock(return_value=None)
             >>> mock('hello')
             >>> mock.called
@@ -409,20 +411,41 @@ the *new_callable* argument to :func:`patch`.
             >>> mock.called
             False
 
-        .. versionchanged:: 3.6
-           Added two keyword-only arguments to the reset_mock function.
-
         This can be useful where you want to make a series of assertions that
-        reuse the same object. Note that :meth:`reset_mock` *doesn't* clear the
+        reuse the same object.
+
+        *return_value* parameter when set to ``True`` resets :attr:`return_value`:
+
+        .. doctest::
+
+            >>> mock = Mock(return_value=5)
+            >>> mock('hello')
+            5
+            >>> mock.reset_mock(return_value=True)
+            >>> mock('hello')  # doctest: +ELLIPSIS
+            <Mock name='mock()' id='...'>
+
+        *side_effect* parameter when set to ``True`` resets :attr:`side_effect`:
+
+        .. doctest::
+
+            >>> mock = Mock(side_effect=ValueError)
+            >>> mock('hello')
+            Traceback (most recent call last):
+              ...
+            ValueError
+            >>> mock.reset_mock(side_effect=True)
+            >>> mock('hello')  # doctest: +ELLIPSIS
+            <Mock name='mock()' id='...'>
+
+        Note that :meth:`reset_mock` *doesn't* clear the
         :attr:`return_value`, :attr:`side_effect` or any child attributes you have
-        set using normal assignment by default. In case you want to reset
-        :attr:`return_value` or :attr:`side_effect`, then pass the corresponding
-        parameter as ``True``. Child mocks and the return value mock
-        (if any) are reset as well.
+        set using normal assignment by default.
 
-        .. note:: *return_value*, and *side_effect* are keyword-only
-                  arguments.
+        Child mocks are reset as well.
 
+        .. versionchanged:: 3.6
+           Added two keyword-only arguments to the reset_mock function.
 
     .. method:: mock_add_spec(spec, spec_set=False)
 

diff --git a/Lib/unittest/mock.py b/Lib/unittest/mock.py
index 495a666eddb7d07156ec6139a9b17c12cd76a7d8..6cec61ff35ccd84c7c27f34d0de8058bf81369bb 100644 (file)
--- a/Lib/unittest/mock.py
+++ b/Lib/unittest/mock.py
@@ -628,7 +628,9 @@ class NonCallableMock(Base):
     side_effect = property(__get_side_effect, __set_side_effect)
 
 
-    def reset_mock(self, visited=None, *, return_value=False, side_effect=False):
+    def reset_mock(self, visited=None, *,
+                   return_value: bool = False,
+                   side_effect: bool = False):
         "Restore the mock object to its initial state."
         if visited is None:
             visited = []
@@ -2228,7 +2230,7 @@ class MagicMock(MagicMixin, Mock):
         self._mock_add_spec(spec, spec_set)
         self._mock_set_magics()
 
-    def reset_mock(self, /, *args, return_value=False, **kwargs):
+    def reset_mock(self, /, *args, return_value: bool = False, **kwargs):
         if (
             return_value
             and self._mock_name