1 files changed, 47 insertions, 5 deletions
diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst
index d7d735c5f5..9a51194b8a 100644
--- a/Doc/library/unittest.mock.rst
+++ b/Doc/library/unittest.mock.rst
@@ -198,7 +198,7 @@ a :class:`MagicMock` for you. You can specify an alternative class of :class:`Mo
 the *new_callable* argument to :func:`patch`.
 
 
-.. class:: Mock(spec=None, side_effect=None, return_value=DEFAULT, wraps=None, name=None, spec_set=None, **kwargs)
+.. class:: Mock(spec=None, side_effect=None, return_value=DEFAULT, wraps=None, name=None, spec_set=None, unsafe=False, **kwargs)
 
     Create a new :class:`Mock` object. :class:`Mock` takes several optional arguments
     that specify the behaviour of the Mock object:
@@ -235,6 +235,12 @@ the *new_callable* argument to :func:`patch`.
       this is a new Mock (created on first access). See the
       :attr:`return_value` attribute.
 
+    * *unsafe*: By default if any attribute starts with *assert* or
+      *assret* will raise an :exc:`AttributeError`. Passing ``unsafe=True``
+      will allow access to these attributes.
+
+      .. versionadded:: 3.5
+
     * *wraps*: Item for the mock object to wrap. If *wraps* is not None then
       calling the Mock will pass the call through to the wrapped object
       (returning the real result). Attribute access on the mock will return a
@@ -315,6 +321,20 @@ the *new_callable* argument to :func:`patch`.
             >>> calls = [call(4), call(2), call(3)]
             >>> mock.assert_has_calls(calls, any_order=True)
 
+    .. method:: assert_not_called(*args, **kwargs)
+
+        Assert the mock was never called.
+
+            >>> m = Mock()
+            >>> m.hello.assert_not_called()
+            >>> obj = m.hello()
+            >>> m.hello.assert_not_called()
+            Traceback (most recent call last):
+              ...
+            AssertionError: Expected 'hello' to not have been called. Called 1 times.
+
+        .. versionadded:: 3.5
+
 
     .. method:: reset_mock()
 
@@ -1032,6 +1052,12 @@ patch
     default because it can be dangerous. With it switched on you can write
     passing tests against APIs that don't actually exist!
 
+    .. note::
+
+        .. versionchanged:: 3.5
+           If you are patching builtins in a module then you don't
+           need to pass ``create=True``, it will be added by default.
+
     Patch can be used as a :class:`TestCase` class decorator. It works by
     decorating each test method in the class. This reduces the boilerplate
     code when your test methods share a common patchings set. :func:`patch` finds
@@ -1403,6 +1429,22 @@ It is also possible to stop all patches which have been started by using
     Stop all active patches. Only stops patches started with ``start``.
 
 
+.. _patch-builtins:
+
+patch builtins
+~~~~~~~~~~~~~~
+You can patch any builtins within a module. The following example patches
+builtin :func:`ord`:
+
+    >>> @patch('__main__.ord')
+    ... def test(mock_ord):
+    ...     mock_ord.return_value = 101
+    ...     print(ord('c'))
+    ...
+    >>> test()
+    101
+
+
 TEST_PREFIX
 ~~~~~~~~~~~
 
@@ -1587,7 +1629,7 @@ The full list of supported magic methods is:
 * Context manager: ``__enter__`` and ``__exit__``
 * Unary numeric methods: ``__neg__``, ``__pos__`` and ``__invert__``
 * The numeric methods (including right hand and in-place variants):
-  ``__add__``, ``__sub__``, ``__mul__``, ``__div__``, ``__truediv__``,
+  ``__add__``, ``__sub__``, ``__mul__``, ``__matmul__``, ``__div__``, ``__truediv__``,
   ``__floordiv__``, ``__mod__``, ``__divmod__``, ``__lshift__``,
   ``__rshift__``, ``__and__``, ``__xor__``, ``__or__``, and ``__pow__``
 * Numeric conversion methods: ``__complex__``, ``__int__``, ``__float__``
@@ -2006,7 +2048,7 @@ mock_open
       The mock of :meth:`~io.IOBase.read` changed to consume *read_data* rather
       than returning it on each call.
 
-   .. versionchanged:: 3.4.4
+   .. versionchanged:: 3.5
       *read_data* is now reset on each call to the *mock*.
 
 Using :func:`open` as a context manager is a great way to ensure your file handles
@@ -2023,7 +2065,7 @@ Mocking context managers with a :class:`MagicMock` is common enough and fiddly
 enough that a helper function is useful.
 
     >>> m = mock_open()
-    >>> with patch('__main__.open', m, create=True):
+    >>> with patch('__main__.open', m):
     ...     with open('foo', 'w') as h:
     ...         h.write('some stuff')
     ...
@@ -2038,7 +2080,7 @@ enough that a helper function is useful.
 
 And for reading files:
 
-    >>> with patch('__main__.open', mock_open(read_data='bibble'), create=True) as m:
+    >>> with patch('__main__.open', mock_open(read_data='bibble')) as m:
     ...     with open('foo') as h:
     ...         result = h.read()
     ...