From 54b3db8c849e039c6d43141bd1351d6eb743679d Mon Sep 17 00:00:00 2001 From: Michael Foord Date: Wed, 28 Mar 2012 15:08:08 +0100 Subject: Minor unittest.mock.patch doc / docstring improvement --- Doc/library/unittest.mock.rst | 25 ++++++++++++++----------- Lib/unittest/mock.py | 27 ++++++++++++++++----------- 2 files changed, 30 insertions(+), 22 deletions(-) diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst index 3e5f9fa..2fe5849 100644 --- 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 a45a7a8..0ae498c 100644 --- 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. -- cgit v0.12