diff -r 44874b20e612 -r 0ebfa64fe320 Doc/library/unittest.mock.rst
--- a/Doc/library/unittest.mock.rst	Wed Nov 16 20:03:03 2016 +0200
+++ b/Doc/library/unittest.mock.rst	Fri Nov 18 14:11:56 2016 +0100
@@ -2126,6 +2126,18 @@
     >>> m.assert_called_once_with('foo')
     >>> assert result == 'bibble'
 
+Usually in real-life tests, :func:`open` will be called in some module other than
+:mod:`__main__`, and must be mocked-out from :mod:`builtins`::
+
+    # file_writer.py
+    def write_file():
+        with open('some_file.txt', 'w') as f:
+            f.write('spam')
+
+    >>> import file_writer
+    >>> with patch('builtins.open', mock_open()) as m:
+    ...     file_writer.write_file()
+    ...     assert call().write('spam') in m.mock_calls
 
 .. _auto-speccing: