[Python-checkins] Add example to the documentation for calling unittest.mock.patch with create=True (GH-11056)

[Miss Islington (bot)]

https://github.com/python/cpython/commit/2b3db493690c286565b91b3d604cda38adb24636
commit: 2b3db493690c286565b91b3d604cda38adb24636
branch: 3.7
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: GitHub <noreply at github.com>
date: 2019-01-09T13:50:02-08:00
summary:

Add example to the documentation for calling unittest.mock.patch with create=True (GH-11056)

(cherry picked from commit d6acf17c05315cd34124d678057d9543adbad404)

Co-authored-by: Pablo Galindo <Pablogsal at gmail.com>

files:
M Doc/library/unittest.mock.rst

diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst
index f1b25958a670..6daf0feca3ce 100644
--- a/Doc/library/unittest.mock.rst
+++ b/Doc/library/unittest.mock.rst
@@ -1097,13 +1097,13 @@ patch
     Instead of ``autospec=True`` you can pass ``autospec=some_object`` to use an
     arbitrary object as the spec instead of the one being replaced.
 
-    By default :func:`patch` will fail to replace attributes that don't exist. If
-    you pass in ``create=True``, and the attribute doesn't exist, patch will
-    create the attribute for you when the patched function is called, and
-    delete it again afterwards. This is useful for writing tests against
-    attributes that your production code creates at runtime. It is off by
-    default because it can be dangerous. With it switched on you can write
-    passing tests against APIs that don't actually exist!
+    By default :func:`patch` will fail to replace attributes that don't exist.
+    If you pass in ``create=True``, and the attribute doesn't exist, patch will
+    create the attribute for you when the patched function is called, and delete
+    it again after the patched function has exited. This is useful for writing
+    tests against attributes that your production code creates at runtime. It is
+    off by default because it can be dangerous. With it switched on you can
+    write passing tests against APIs that don't actually exist!
 
     .. note::
 
@@ -1225,6 +1225,27 @@ into a :func:`patch` call using ``**``:
       ...
     KeyError
 
+By default, attempting to patch a function in a module (or a method or an
+attribute in a class) that does not exist will fail with :exc:`AttributeError`::
+
+    >>> @patch('sys.non_existing_attribute', 42)
+    ... def test():
+    ...     assert sys.non_existing_attribute == 42
+    ...
+    >>> test()
+    Traceback (most recent call last):
+      ...
+    AttributeError: <module 'sys' (built-in)> does not have the attribute 'non_existing'
+
+but adding ``create=True`` in the call to :func:`patch` will make the previous example
+work as expected::
+
+    >>> @patch('sys.non_existing_attribute', 42, create=True)
+    ... def test(mock_stdout):
+    ...     assert sys.non_existing_attribute == 42
+    ...
+    >>> test()
+
 
 patch.object
 ~~~~~~~~~~~~