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

gh-124234: Improve docs for `Mock.reset_mock` (GH-124237)
(cherry picked from commit 19fed6cf6eb51044fd0c02c6338259e2dd7fd462)

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

diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst
index ec5651f1570c9414dbe3d9738c7645dd167de1ac..bb3baa97275e7f9720728612a3dc5aea73f2bf42 100644 (file)
--- a/Doc/library/unittest.mock.rst
+++ b/Doc/library/unittest.mock.rst
@@ -397,6 +397,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
@@ -405,20 +407,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 805c6b3cea61409b0db34b471ede0659c1e5e3a6..3e9791b22dc4504f17cf809d581e9f8bd2b2500e 100644 (file)
--- a/Lib/unittest/mock.py
+++ b/Lib/unittest/mock.py
@@ -598,7 +598,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 = []
@@ -2189,7 +2191,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