Add example to the documentation for calling unittest.mock.patch with create=True (GH-11056)
diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst
index bfab00e..c011e54 100644
--- a/Doc/library/unittest.mock.rst
+++ b/Doc/library/unittest.mock.rst
@@ -1119,13 +1119,13 @@
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::
@@ -1247,6 +1247,27 @@
...
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
~~~~~~~~~~~~