Minor unittest.mock.patch doc / docstring improvement

diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst
index 3e5f9fa9be6d247c28fee6840393a9e7dc6fc550..2fe5849b45ef490bfba0f374c476de51506c0f4e 100644 (file)
--- a/Doc/library/unittest.mock.rst
+++ b/Doc/library/unittest.mock.rst
@@ -920,17 +920,20 @@ patch
 
     `patch` acts as a function decorator, class decorator or a context
     manager. Inside the body of the function or with statement, the `target`
-    (specified in the form `'package.module.ClassName'`) is patched
-    with a `new` object. When the function/with statement exits the patch is
-    undone.
-
-    The `target` is imported and the specified attribute patched with the new
-    object, so it must be importable from the environment you are calling the
-    decorator from. The target is imported when the decorated function is
-    executed, not at decoration time.
-
-    If `new` is omitted, then a new `MagicMock` is created and passed in as an
-    extra argument to the decorated function.
+    is patched with a `new` object. When the function/with statement exits
+    the patch is undone.
+
+    If `new` is omitted, then the target is replaced with a
+    :class:`MagicMock`. If `patch` is used as a decorator and `new` is
+    omitted, the created mock is passed in as an extra argument to the
+    decorated function. If `patch` is used as a context manager the created
+    mock is returned by the context manager.
+
+    `target` should be a string in the form `'package.module.ClassName'`. The
+    `target` is imported and the specified object replaced with the `new`
+    object, so the `target` must be importable from the environment you are
+    calling `patch` from. The target is imported when the decorated function
+    is executed, not at decoration time.
 
     The `spec` and `spec_set` keyword arguments are passed to the `MagicMock`
     if patch is creating one for you.

diff --git a/Lib/unittest/mock.py b/Lib/unittest/mock.py
index a45a7a83fbc74b06a0f129a286addf2368299c55..0ae498c080829e6e1998b704fe58540fd0fdbe91 100644 (file)
--- a/Lib/unittest/mock.py
+++ b/Lib/unittest/mock.py
@@ -1351,18 +1351,23 @@ def patch(
     ):
     """
     `patch` acts as a function decorator, class decorator or a context
-    manager. Inside the body of the function or with statement, the `target`
-    (specified in the form `'package.module.ClassName'`) is patched
-    with a `new` object. When the function/with statement exits the patch is
-    undone.
-
-    The `target` is imported and the specified attribute patched with the new
-    object, so it must be importable from the environment you are calling the
-    decorator from. The target is imported when the decorated function is
-    executed, not at decoration time.
 
-    If `new` is omitted, then a new `MagicMock` is created and passed in as an
-    extra argument to the decorated function.
+    `patch` acts as a function decorator, class decorator or a context
+    manager. Inside the body of the function or with statement, the `target`
+    is patched with a `new` object. When the function/with statement exits
+    the patch is undone.
+
+    If `new` is omitted, then the target is replaced with a
+    `MagicMock`. If `patch` is used as a decorator and `new` is
+    omitted, the created mock is passed in as an extra argument to the
+    decorated function. If `patch` is used as a context manager the created
+    mock is returned by the context manager.
+
+    `target` should be a string in the form `'package.module.ClassName'`. The
+    `target` is imported and the specified object replaced with the `new`
+    object, so the `target` must be importable from the environment you are
+    calling `patch` from. The target is imported when the decorated function
+    is executed, not at decoration time.
 
     The `spec` and `spec_set` keyword arguments are passed to the `MagicMock`
     if patch is creating one for you.