bpo-34962: make doctest in Doc/ now passes, and is enforced in CI (GH-9806)

1 files changed, 68 insertions, 32 deletions

diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst
index 06009e4a09..edafca0c67 100644
--- a/Doc/library/unittest.mock.rst
+++ b/Doc/library/unittest.mock.rst
@@ -41,6 +41,22 @@ available as `mock on PyPI <https://pypi.org/project/mock>`_.
 Quick Guide
 -----------
 
+.. testsetup::
+
+    class ProductionClass:
+        def method(self, a, b, c):
+            pass
+
+    class SomeClass:
+        @staticmethod
+        def static_method(args):
+            return args
+
+        @classmethod
+        def class_method(cls, args):
+            return args
+
+
 :class:`Mock` and :class:`MagicMock` objects create all attributes and
 methods as you access them and store details of how they have been used. You
 can configure them, to specify return values or limit what attributes are
@@ -80,7 +96,7 @@ that don't exist on the spec will fail with an :exc:`AttributeError`.
 
 The :func:`patch` decorator / context manager makes it easy to mock classes or
 objects in a module under test. The object you specify will be replaced with a
-mock (or other object) during the test and restored when the test ends:
+mock (or other object) during the test and restored when the test ends::
 
     >>> from unittest.mock import patch
     >>> @patch('module.ClassName2')
@@ -183,6 +199,12 @@ the ``__call__`` method.
 The Mock Class
 --------------
 
+.. testsetup::
+
+    import unittest
+    from unittest.mock import sentinel, DEFAULT, ANY
+    from unittest.mock import patch, call, Mock, MagicMock, PropertyMock
+    from unittest.mock import mock_open
 
 :class:`Mock` is a flexible mock object intended to replace the use of stubs and
 test doubles throughout your code. Mocks are callable and create attributes as
@@ -774,7 +796,7 @@ apply to method calls on the mock object.
    so you can specify a return value when it is fetched.
 
    Fetching a :class:`PropertyMock` instance from an object calls the mock, with
-   no args. Setting it calls the mock with the value being set.
+   no args. Setting it calls the mock with the value being set. ::
 
         >>> class Foo:
         ...     @property
@@ -1001,7 +1023,7 @@ the "parenting" if for some reason you don't want it to happen.
 
 Mocks created for you by :func:`patch` are automatically given names. To
 attach mocks that have names to a parent you use the :meth:`~Mock.attach_mock`
-method:
+method::
 
     >>> thing1 = object()
     >>> thing2 = object()
@@ -1117,7 +1139,7 @@ patch
     available for alternate use-cases.
 
 :func:`patch` as function decorator, creating the mock for you and passing it into
-the decorated function:
+the decorated function::
 
     >>> @patch('__main__.SomeClass')
     ... def function(normal_argument, mock_class):
@@ -1135,7 +1157,7 @@ If the class is instantiated multiple times you could use
 can set the *return_value* to be anything you want.
 
 To configure return values on methods of *instances* on the patched class
-you must do this on the :attr:`return_value`. For example:
+you must do this on the :attr:`return_value`. For example::
 
     >>> class Class:
     ...     def method(self):
@@ -1149,7 +1171,7 @@ you must do this on the :attr:`return_value`. For example:
     ...
 
 If you use *spec* or *spec_set* and :func:`patch` is replacing a *class*, then the
-return value of the created mock will have the same spec.
+return value of the created mock will have the same spec. ::
 
     >>> Original = Class
     >>> patcher = patch('__main__.Class', spec=True)
@@ -1160,7 +1182,7 @@ return value of the created mock will have the same spec.
 
 The *new_callable* argument is useful where you want to use an alternative
 class to the default :class:`MagicMock` for the created mock. For example, if
-you wanted a :class:`NonCallableMock` to be used:
+you wanted a :class:`NonCallableMock` to be used::
 
     >>> thing = object()
     >>> with patch('__main__.thing', new_callable=NonCallableMock) as mock_thing:
@@ -1171,7 +1193,7 @@ you wanted a :class:`NonCallableMock` to be used:
       ...
     TypeError: 'NonCallableMock' object is not callable
 
-Another use case might be to replace an object with an :class:`io.StringIO` instance:
+Another use case might be to replace an object with an :class:`io.StringIO` instance::
 
     >>> from io import StringIO
     >>> def foo():
@@ -1187,7 +1209,7 @@ Another use case might be to replace an object with an :class:`io.StringIO` inst
 When :func:`patch` is creating a mock for you, it is common that the first thing
 you need to do is to configure the mock. Some of that configuration can be done
 in the call to patch. Any arbitrary keywords you pass into the call will be
-used to set attributes on the created mock:
+used to set attributes on the created mock::
 
     >>> patcher = patch('__main__.thing', first='one', second='two')
     >>> mock_thing = patcher.start()
@@ -1200,7 +1222,7 @@ As well as attributes on the created mock attributes, like the
 :attr:`~Mock.return_value` and :attr:`~Mock.side_effect`, of child mocks can
 also be configured. These aren't syntactically valid to pass in directly as
 keyword arguments, but a dictionary with these as keys can still be expanded
-into a :func:`patch` call using ``**``:
+into a :func:`patch` call using ``**``::
 
     >>> config = {'method.return_value': 3, 'other.side_effect': KeyError}
     >>> patcher = patch('__main__.thing', **config)
@@ -1359,7 +1381,7 @@ patch.multiple
 
 If you want :func:`patch.multiple` to create mocks for you, then you can use
 :data:`DEFAULT` as the value. If you use :func:`patch.multiple` as a decorator
-then the created mocks are passed into the decorated function by keyword.
+then the created mocks are passed into the decorated function by keyword. ::
 
     >>> thing = object()
     >>> other = object()
@@ -1372,7 +1394,7 @@ then the created mocks are passed into the decorated function by keyword.
     >>> test_function()
 
 :func:`patch.multiple` can be nested with other ``patch`` decorators, but put arguments
-passed by keyword *after* any of the standard arguments created by :func:`patch`:
+passed by keyword *after* any of the standard arguments created by :func:`patch`::
 
     >>> @patch('sys.exit')
     ... @patch.multiple('__main__', thing=DEFAULT, other=DEFAULT)
@@ -1384,7 +1406,7 @@ passed by keyword *after* any of the standard arguments created by :func:`patch`
     >>> test_function()
 
 If :func:`patch.multiple` is used as a context manager, the value returned by the
-context manger is a dictionary where created mocks are keyed by name:
+context manger is a dictionary where created mocks are keyed by name::
 
     >>> with patch.multiple('__main__', thing=DEFAULT, other=DEFAULT) as values:
     ...     assert 'other' in repr(values['other'])
@@ -1408,7 +1430,7 @@ normal and keep a reference to the returned ``patcher`` object. You can then
 call :meth:`start` to put the patch in place and :meth:`stop` to undo it.
 
 If you are using :func:`patch` to create a mock for you then it will be returned by
-the call to ``patcher.start``.
+the call to ``patcher.start``. ::
 
     >>> patcher = patch('package.module.ClassName')
     >>> from package import module
@@ -1422,9 +1444,9 @@ the call to ``patcher.start``.
 
 
 A typical use case for this might be for doing multiple patches in the ``setUp``
-method of a :class:`TestCase`:
+method of a :class:`TestCase`::
 
-    >>> class MyTest(TestCase):
+    >>> class MyTest(unittest.TestCase):
     ...     def setUp(self):
     ...         self.patcher1 = patch('package.module.Class1')
     ...         self.patcher2 = patch('package.module.Class2')
@@ -1446,9 +1468,9 @@ method of a :class:`TestCase`:
     If you use this technique you must ensure that the patching is "undone" by
     calling ``stop``. This can be fiddlier than you might think, because if an
     exception is raised in the ``setUp`` then ``tearDown`` is not called.
-    :meth:`unittest.TestCase.addCleanup` makes this easier:
+    :meth:`unittest.TestCase.addCleanup` makes this easier::
 
-        >>> class MyTest(TestCase):
+        >>> class MyTest(unittest.TestCase):
         ...     def setUp(self):
         ...         patcher = patch('package.module.Class')
         ...         self.MockClass = patcher.start()
@@ -1474,7 +1496,7 @@ It is also possible to stop all patches which have been started by using
 patch builtins
 ~~~~~~~~~~~~~~
 You can patch any builtins within a module. The following example patches
-builtin :func:`ord`:
+builtin :func:`ord`::
 
     >>> @patch('__main__.ord')
     ... def test(mock_ord):
@@ -1494,7 +1516,7 @@ start with ``'test'`` as being test methods. This is the same way that the
 :class:`unittest.TestLoader` finds test methods by default.
 
 It is possible that you want to use a different prefix for your tests. You can
-inform the patchers of the different prefix by setting ``patch.TEST_PREFIX``:
+inform the patchers of the different prefix by setting ``patch.TEST_PREFIX``::
 
     >>> patch.TEST_PREFIX = 'foo'
     >>> value = 3
@@ -1931,7 +1953,7 @@ arguments are a dictionary:
     >>> args
     (1, 2, 3)
     >>> kwargs
-    {'arg2': 'two', 'arg': 'one'}
+    {'arg': 'one', 'arg2': 'two'}
     >>> args is kall[0]
     True
     >>> kwargs is kall[1]
@@ -1947,7 +1969,7 @@ arguments are a dictionary:
     >>> args
     (4, 5, 6)
     >>> kwargs
-    {'arg2': 'three', 'arg': 'two'}
+    {'arg': 'two', 'arg2': 'three'}
     >>> name is m.mock_calls[0][0]
     True
 
@@ -2027,11 +2049,17 @@ If the mock was created with a *spec* (or *autospec* of course) then all the
 attributes from the original are shown, even if they haven't been accessed
 yet:
 
+.. doctest::
+    :options: +ELLIPSIS,+NORMALIZE_WHITESPACE
+
     >>> dir(Mock())
     ['assert_any_call',
+     'assert_called',
+     'assert_called_once',
      'assert_called_once_with',
      'assert_called_with',
      'assert_has_calls',
+     'assert_not_called',
      'attach_mock',
      ...
     >>> from urllib import request
@@ -2048,6 +2076,9 @@ filtered from the result of calling :func:`dir` on a :class:`Mock`. If you disli
 behaviour you can switch it off by setting the module level switch
 :data:`FILTER_DIR`:
 
+.. doctest::
+    :options: +ELLIPSIS,+NORMALIZE_WHITESPACE
+
     >>> from unittest import mock
     >>> mock.FILTER_DIR = False
     >>> dir(mock.Mock())
@@ -2110,7 +2141,7 @@ The issue is that even if you mock out the call to :func:`open` it is the
 :meth:`__exit__` called).
 
 Mocking context managers with a :class:`MagicMock` is common enough and fiddly
-enough that a helper function is useful.
+enough that a helper function is useful. ::
 
     >>> m = mock_open()
     >>> with patch('__main__.open', m):
@@ -2126,7 +2157,7 @@ enough that a helper function is useful.
     >>> handle = m()
     >>> handle.write.assert_called_once_with('some stuff')
 
-And for reading files:
+And for reading files::
 
     >>> with patch('__main__.open', mock_open(read_data='bibble')) as m:
     ...     with open('foo') as h:
@@ -2219,7 +2250,7 @@ accessed) you can use it with very complex or deeply nested objects (like
 modules that import modules that import modules) without a big performance
 hit.
 
-Here's an example of it in use:
+Here's an example of it in use::
 
     >>> from urllib import request
     >>> patcher = patch('__main__.request', autospec=True)
@@ -2231,7 +2262,7 @@ Here's an example of it in use:
 
 You can see that :class:`request.Request` has a spec. :class:`request.Request` takes two
 arguments in the constructor (one of which is *self*). Here's what happens if
-we try to call it incorrectly:
+we try to call it incorrectly::
 
     >>> req = request.Request()
     Traceback (most recent call last):
@@ -2239,7 +2270,7 @@ we try to call it incorrectly:
     TypeError: <lambda>() takes at least 2 arguments (1 given)
 
 The spec also applies to instantiated classes (i.e. the return value of
-specced mocks):
+specced mocks)::
 
     >>> req = request.Request('foo')
     >>> req
@@ -2247,7 +2278,7 @@ specced mocks):
 
 :class:`Request` objects are not callable, so the return value of instantiating our
 mocked out :class:`request.Request` is a non-callable mock. With the spec in place
-any typos in our asserts will raise the correct error:
+any typos in our asserts will raise the correct error::
 
     >>> req.add_header('spam', 'eggs')
     <MagicMock name='request.Request().add_header()' id='...'>
@@ -2281,7 +2312,7 @@ objects so that introspection is safe [#]_.
 A more serious problem is that it is common for instance attributes to be
 created in the :meth:`__init__` method and not to exist on the class at all.
 *autospec* can't know about any dynamically created attributes and restricts
-the api to visible attributes.
+the api to visible attributes. ::
 
     >>> class Something:
     ...   def __init__(self):
@@ -2299,7 +2330,7 @@ There are a few different ways of resolving this problem. The easiest, but
 not necessarily the least annoying, way is to simply set the required
 attributes on the mock after creation. Just because *autospec* doesn't allow
 you to fetch attributes that don't exist on the spec it doesn't prevent you
-setting them:
+setting them::
 
     >>> with patch('__main__.Something', autospec=True):
     ...   thing = Something()
@@ -2350,7 +2381,7 @@ spec rather than the class. The other is to create a subclass of the
 production class and add the defaults to the subclass without affecting the
 production class. Both of these require you to use an alternative object as
 the spec. Thankfully :func:`patch` supports this - you can simply pass the
-alternative object as the *autospec* argument:
+alternative object as the *autospec* argument::
 
     >>> class Something:
     ...   def __init__(self):
@@ -2372,6 +2403,11 @@ alternative object as the *autospec* argument:
 Sealing mocks
 ~~~~~~~~~~~~~
 
+
+.. testsetup::
+
+    from unittest.mock import seal
+
 .. function:: seal(mock)
 
     Seal will disable the creation of mock children by preventing getting or setting
@@ -2379,7 +2415,7 @@ Sealing mocks
 
     If a mock instance is assigned to an attribute instead of being dynamically created
     it won't be considered in the sealing chain. This allows one to prevent seal from
-    fixing part of the mock object.
+    fixing part of the mock object. ::
 
         >>> mock = Mock()
         >>> mock.submock.attribute1 = 2