1 """
2 Test script for doctest.
3 """
4
5 from test import support
6 from test.support import import_helper
7 from test.support import os_helper
8 import doctest
9 import functools
10 import os
11 import sys
12 import importlib
13 import importlib.abc
14 import importlib.util
15 import unittest
16 import tempfile
17 import shutil
18 import types
19 import contextlib
20
21
22 if not support.has_subprocess_support:
23 raise unittest.SkipTest("test_CLI requires subprocess support.")
24
25
26 # NOTE: There are some additional tests relating to interaction with
27 # zipimport in the test_zipimport_support test module.
28 # There are also related tests in `test_doctest2` module.
29
30 ######################################################################
31 ## Sample Objects (used by test cases)
32 ######################################################################
33
34 def sample_func(v):
35 """
36 Blah blah
37
38 >>> print(sample_func(22))
39 44
40
41 Yee ha!
42 """
43 return v+v
44
45 class ESC[4;38;5;81mSampleClass:
46 """
47 >>> print(1)
48 1
49
50 >>> # comments get ignored. so are empty PS1 and PS2 prompts:
51 >>>
52 ...
53
54 Multiline example:
55 >>> sc = SampleClass(3)
56 >>> for i in range(10):
57 ... sc = sc.double()
58 ... print(' ', sc.get(), sep='', end='')
59 6 12 24 48 96 192 384 768 1536 3072
60 """
61 def __init__(self, val):
62 """
63 >>> print(SampleClass(12).get())
64 12
65 """
66 self.val = val
67
68 def double(self):
69 """
70 >>> print(SampleClass(12).double().get())
71 24
72 """
73 return SampleClass(self.val + self.val)
74
75 def get(self):
76 """
77 >>> print(SampleClass(-5).get())
78 -5
79 """
80 return self.val
81
82 def a_staticmethod(v):
83 """
84 >>> print(SampleClass.a_staticmethod(10))
85 11
86 """
87 return v+1
88 a_staticmethod = staticmethod(a_staticmethod)
89
90 def a_classmethod(cls, v):
91 """
92 >>> print(SampleClass.a_classmethod(10))
93 12
94 >>> print(SampleClass(0).a_classmethod(10))
95 12
96 """
97 return v+2
98 a_classmethod = classmethod(a_classmethod)
99
100 a_property = property(get, doc="""
101 >>> print(SampleClass(22).a_property)
102 22
103 """)
104
105 a_class_attribute = 42
106
107 @classmethod
108 @property
109 def a_classmethod_property(cls):
110 """
111 >>> print(SampleClass.a_classmethod_property)
112 42
113 """
114 return cls.a_class_attribute
115
116 class ESC[4;38;5;81mNestedClass:
117 """
118 >>> x = SampleClass.NestedClass(5)
119 >>> y = x.square()
120 >>> print(y.get())
121 25
122 """
123 def __init__(self, val=0):
124 """
125 >>> print(SampleClass.NestedClass().get())
126 0
127 """
128 self.val = val
129 def square(self):
130 return SampleClass.NestedClass(self.val*self.val)
131 def get(self):
132 return self.val
133
134 class ESC[4;38;5;81mSampleNewStyleClass(ESC[4;38;5;149mobject):
135 r"""
136 >>> print('1\n2\n3')
137 1
138 2
139 3
140 """
141 def __init__(self, val):
142 """
143 >>> print(SampleNewStyleClass(12).get())
144 12
145 """
146 self.val = val
147
148 def double(self):
149 """
150 >>> print(SampleNewStyleClass(12).double().get())
151 24
152 """
153 return SampleNewStyleClass(self.val + self.val)
154
155 def get(self):
156 """
157 >>> print(SampleNewStyleClass(-5).get())
158 -5
159 """
160 return self.val
161
162 ######################################################################
163 ## Fake stdin (for testing interactive debugging)
164 ######################################################################
165
166 class ESC[4;38;5;81m_FakeInput:
167 """
168 A fake input stream for pdb's interactive debugger. Whenever a
169 line is read, print it (to simulate the user typing it), and then
170 return it. The set of lines to return is specified in the
171 constructor; they should not have trailing newlines.
172 """
173 def __init__(self, lines):
174 self.lines = lines
175
176 def readline(self):
177 line = self.lines.pop(0)
178 print(line)
179 return line+'\n'
180
181 ######################################################################
182 ## Test Cases
183 ######################################################################
184
185 def test_Example(): r"""
186 Unit tests for the `Example` class.
187
188 Example is a simple container class that holds:
189 - `source`: A source string.
190 - `want`: An expected output string.
191 - `exc_msg`: An expected exception message string (or None if no
192 exception is expected).
193 - `lineno`: A line number (within the docstring).
194 - `indent`: The example's indentation in the input string.
195 - `options`: An option dictionary, mapping option flags to True or
196 False.
197
198 These attributes are set by the constructor. `source` and `want` are
199 required; the other attributes all have default values:
200
201 >>> example = doctest.Example('print(1)', '1\n')
202 >>> (example.source, example.want, example.exc_msg,
203 ... example.lineno, example.indent, example.options)
204 ('print(1)\n', '1\n', None, 0, 0, {})
205
206 The first three attributes (`source`, `want`, and `exc_msg`) may be
207 specified positionally; the remaining arguments should be specified as
208 keyword arguments:
209
210 >>> exc_msg = 'IndexError: pop from an empty list'
211 >>> example = doctest.Example('[].pop()', '', exc_msg,
212 ... lineno=5, indent=4,
213 ... options={doctest.ELLIPSIS: True})
214 >>> (example.source, example.want, example.exc_msg,
215 ... example.lineno, example.indent, example.options)
216 ('[].pop()\n', '', 'IndexError: pop from an empty list\n', 5, 4, {8: True})
217
218 The constructor normalizes the `source` string to end in a newline:
219
220 Source spans a single line: no terminating newline.
221 >>> e = doctest.Example('print(1)', '1\n')
222 >>> e.source, e.want
223 ('print(1)\n', '1\n')
224
225 >>> e = doctest.Example('print(1)\n', '1\n')
226 >>> e.source, e.want
227 ('print(1)\n', '1\n')
228
229 Source spans multiple lines: require terminating newline.
230 >>> e = doctest.Example('print(1);\nprint(2)\n', '1\n2\n')
231 >>> e.source, e.want
232 ('print(1);\nprint(2)\n', '1\n2\n')
233
234 >>> e = doctest.Example('print(1);\nprint(2)', '1\n2\n')
235 >>> e.source, e.want
236 ('print(1);\nprint(2)\n', '1\n2\n')
237
238 Empty source string (which should never appear in real examples)
239 >>> e = doctest.Example('', '')
240 >>> e.source, e.want
241 ('\n', '')
242
243 The constructor normalizes the `want` string to end in a newline,
244 unless it's the empty string:
245
246 >>> e = doctest.Example('print(1)', '1\n')
247 >>> e.source, e.want
248 ('print(1)\n', '1\n')
249
250 >>> e = doctest.Example('print(1)', '1')
251 >>> e.source, e.want
252 ('print(1)\n', '1\n')
253
254 >>> e = doctest.Example('print', '')
255 >>> e.source, e.want
256 ('print\n', '')
257
258 The constructor normalizes the `exc_msg` string to end in a newline,
259 unless it's `None`:
260
261 Message spans one line
262 >>> exc_msg = 'IndexError: pop from an empty list'
263 >>> e = doctest.Example('[].pop()', '', exc_msg)
264 >>> e.exc_msg
265 'IndexError: pop from an empty list\n'
266
267 >>> exc_msg = 'IndexError: pop from an empty list\n'
268 >>> e = doctest.Example('[].pop()', '', exc_msg)
269 >>> e.exc_msg
270 'IndexError: pop from an empty list\n'
271
272 Message spans multiple lines
273 >>> exc_msg = 'ValueError: 1\n 2'
274 >>> e = doctest.Example('raise ValueError("1\n 2")', '', exc_msg)
275 >>> e.exc_msg
276 'ValueError: 1\n 2\n'
277
278 >>> exc_msg = 'ValueError: 1\n 2\n'
279 >>> e = doctest.Example('raise ValueError("1\n 2")', '', exc_msg)
280 >>> e.exc_msg
281 'ValueError: 1\n 2\n'
282
283 Empty (but non-None) exception message (which should never appear
284 in real examples)
285 >>> exc_msg = ''
286 >>> e = doctest.Example('raise X()', '', exc_msg)
287 >>> e.exc_msg
288 '\n'
289
290 Compare `Example`:
291 >>> example = doctest.Example('print 1', '1\n')
292 >>> same_example = doctest.Example('print 1', '1\n')
293 >>> other_example = doctest.Example('print 42', '42\n')
294 >>> example == same_example
295 True
296 >>> example != same_example
297 False
298 >>> hash(example) == hash(same_example)
299 True
300 >>> example == other_example
301 False
302 >>> example != other_example
303 True
304 """
305
306 def test_DocTest(): r"""
307 Unit tests for the `DocTest` class.
308
309 DocTest is a collection of examples, extracted from a docstring, along
310 with information about where the docstring comes from (a name,
311 filename, and line number). The docstring is parsed by the `DocTest`
312 constructor:
313
314 >>> docstring = '''
315 ... >>> print(12)
316 ... 12
317 ...
318 ... Non-example text.
319 ...
320 ... >>> print('another\\example')
321 ... another
322 ... example
323 ... '''
324 >>> globs = {} # globals to run the test in.
325 >>> parser = doctest.DocTestParser()
326 >>> test = parser.get_doctest(docstring, globs, 'some_test',
327 ... 'some_file', 20)
328 >>> print(test)
329 <DocTest some_test from some_file:20 (2 examples)>
330 >>> len(test.examples)
331 2
332 >>> e1, e2 = test.examples
333 >>> (e1.source, e1.want, e1.lineno)
334 ('print(12)\n', '12\n', 1)
335 >>> (e2.source, e2.want, e2.lineno)
336 ("print('another\\example')\n", 'another\nexample\n', 6)
337
338 Source information (name, filename, and line number) is available as
339 attributes on the doctest object:
340
341 >>> (test.name, test.filename, test.lineno)
342 ('some_test', 'some_file', 20)
343
344 The line number of an example within its containing file is found by
345 adding the line number of the example and the line number of its
346 containing test:
347
348 >>> test.lineno + e1.lineno
349 21
350 >>> test.lineno + e2.lineno
351 26
352
353 If the docstring contains inconsistent leading whitespace in the
354 expected output of an example, then `DocTest` will raise a ValueError:
355
356 >>> docstring = r'''
357 ... >>> print('bad\nindentation')
358 ... bad
359 ... indentation
360 ... '''
361 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
362 Traceback (most recent call last):
363 ValueError: line 4 of the docstring for some_test has inconsistent leading whitespace: 'indentation'
364
365 If the docstring contains inconsistent leading whitespace on
366 continuation lines, then `DocTest` will raise a ValueError:
367
368 >>> docstring = r'''
369 ... >>> print(('bad indentation',
370 ... ... 2))
371 ... ('bad', 'indentation')
372 ... '''
373 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
374 Traceback (most recent call last):
375 ValueError: line 2 of the docstring for some_test has inconsistent leading whitespace: '... 2))'
376
377 If there's no blank space after a PS1 prompt ('>>>'), then `DocTest`
378 will raise a ValueError:
379
380 >>> docstring = '>>>print(1)\n1'
381 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
382 Traceback (most recent call last):
383 ValueError: line 1 of the docstring for some_test lacks blank after >>>: '>>>print(1)'
384
385 If there's no blank space after a PS2 prompt ('...'), then `DocTest`
386 will raise a ValueError:
387
388 >>> docstring = '>>> if 1:\n...print(1)\n1'
389 >>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
390 Traceback (most recent call last):
391 ValueError: line 2 of the docstring for some_test lacks blank after ...: '...print(1)'
392
393 Compare `DocTest`:
394
395 >>> docstring = '''
396 ... >>> print 12
397 ... 12
398 ... '''
399 >>> test = parser.get_doctest(docstring, globs, 'some_test',
400 ... 'some_test', 20)
401 >>> same_test = parser.get_doctest(docstring, globs, 'some_test',
402 ... 'some_test', 20)
403 >>> test == same_test
404 True
405 >>> test != same_test
406 False
407 >>> hash(test) == hash(same_test)
408 True
409 >>> docstring = '''
410 ... >>> print 42
411 ... 42
412 ... '''
413 >>> other_test = parser.get_doctest(docstring, globs, 'other_test',
414 ... 'other_file', 10)
415 >>> test == other_test
416 False
417 >>> test != other_test
418 True
419 >>> test < other_test
420 False
421 >>> other_test < test
422 True
423
424 Test comparison with lineno None on one side
425
426 >>> no_lineno = parser.get_doctest(docstring, globs, 'some_test',
427 ... 'some_test', None)
428 >>> test.lineno is None
429 False
430 >>> no_lineno.lineno is None
431 True
432 >>> test < no_lineno
433 False
434 >>> no_lineno < test
435 True
436
437 Compare `DocTestCase`:
438
439 >>> DocTestCase = doctest.DocTestCase
440 >>> test_case = DocTestCase(test)
441 >>> same_test_case = DocTestCase(same_test)
442 >>> other_test_case = DocTestCase(other_test)
443 >>> test_case == same_test_case
444 True
445 >>> test_case != same_test_case
446 False
447 >>> hash(test_case) == hash(same_test_case)
448 True
449 >>> test == other_test_case
450 False
451 >>> test != other_test_case
452 True
453
454 """
455
456 class ESC[4;38;5;81mtest_DocTestFinder:
457 def basics(): r"""
458 Unit tests for the `DocTestFinder` class.
459
460 DocTestFinder is used to extract DocTests from an object's docstring
461 and the docstrings of its contained objects. It can be used with
462 modules, functions, classes, methods, staticmethods, classmethods, and
463 properties.
464
465 Finding Tests in Functions
466 ~~~~~~~~~~~~~~~~~~~~~~~~~~
467 For a function whose docstring contains examples, DocTestFinder.find()
468 will return a single test (for that function's docstring):
469
470 >>> finder = doctest.DocTestFinder()
471
472 We'll simulate a __file__ attr that ends in pyc:
473
474 >>> import test.test_doctest
475 >>> old = test.test_doctest.__file__
476 >>> test.test_doctest.__file__ = 'test_doctest.pyc'
477
478 >>> tests = finder.find(sample_func)
479
480 >>> print(tests) # doctest: +ELLIPSIS
481 [<DocTest sample_func from test_doctest.py:34 (1 example)>]
482
483 The exact name depends on how test_doctest was invoked, so allow for
484 leading path components.
485
486 >>> tests[0].filename # doctest: +ELLIPSIS
487 '...test_doctest.py'
488
489 >>> test.test_doctest.__file__ = old
490
491
492 >>> e = tests[0].examples[0]
493 >>> (e.source, e.want, e.lineno)
494 ('print(sample_func(22))\n', '44\n', 3)
495
496 By default, tests are created for objects with no docstring:
497
498 >>> def no_docstring(v):
499 ... pass
500 >>> finder.find(no_docstring)
501 []
502
503 However, the optional argument `exclude_empty` to the DocTestFinder
504 constructor can be used to exclude tests for objects with empty
505 docstrings:
506
507 >>> def no_docstring(v):
508 ... pass
509 >>> excl_empty_finder = doctest.DocTestFinder(exclude_empty=True)
510 >>> excl_empty_finder.find(no_docstring)
511 []
512
513 If the function has a docstring with no examples, then a test with no
514 examples is returned. (This lets `DocTestRunner` collect statistics
515 about which functions have no tests -- but is that useful? And should
516 an empty test also be created when there's no docstring?)
517
518 >>> def no_examples(v):
519 ... ''' no doctest examples '''
520 >>> finder.find(no_examples) # doctest: +ELLIPSIS
521 [<DocTest no_examples from ...:1 (no examples)>]
522
523 Finding Tests in Classes
524 ~~~~~~~~~~~~~~~~~~~~~~~~
525 For a class, DocTestFinder will create a test for the class's
526 docstring, and will recursively explore its contents, including
527 methods, classmethods, staticmethods, properties, and nested classes.
528
529 >>> finder = doctest.DocTestFinder()
530 >>> tests = finder.find(SampleClass)
531 >>> for t in tests:
532 ... print('%2s %s' % (len(t.examples), t.name))
533 3 SampleClass
534 3 SampleClass.NestedClass
535 1 SampleClass.NestedClass.__init__
536 1 SampleClass.__init__
537 2 SampleClass.a_classmethod
538 1 SampleClass.a_classmethod_property
539 1 SampleClass.a_property
540 1 SampleClass.a_staticmethod
541 1 SampleClass.double
542 1 SampleClass.get
543
544 New-style classes are also supported:
545
546 >>> tests = finder.find(SampleNewStyleClass)
547 >>> for t in tests:
548 ... print('%2s %s' % (len(t.examples), t.name))
549 1 SampleNewStyleClass
550 1 SampleNewStyleClass.__init__
551 1 SampleNewStyleClass.double
552 1 SampleNewStyleClass.get
553
554 Finding Tests in Modules
555 ~~~~~~~~~~~~~~~~~~~~~~~~
556 For a module, DocTestFinder will create a test for the class's
557 docstring, and will recursively explore its contents, including
558 functions, classes, and the `__test__` dictionary, if it exists:
559
560 >>> # A module
561 >>> import types
562 >>> m = types.ModuleType('some_module')
563 >>> def triple(val):
564 ... '''
565 ... >>> print(triple(11))
566 ... 33
567 ... '''
568 ... return val*3
569 >>> m.__dict__.update({
570 ... 'sample_func': sample_func,
571 ... 'SampleClass': SampleClass,
572 ... '__doc__': '''
573 ... Module docstring.
574 ... >>> print('module')
575 ... module
576 ... ''',
577 ... '__test__': {
578 ... 'd': '>>> print(6)\n6\n>>> print(7)\n7\n',
579 ... 'c': triple}})
580
581 >>> finder = doctest.DocTestFinder()
582 >>> # Use module=test.test_doctest, to prevent doctest from
583 >>> # ignoring the objects since they weren't defined in m.
584 >>> import test.test_doctest
585 >>> tests = finder.find(m, module=test.test_doctest)
586 >>> for t in tests:
587 ... print('%2s %s' % (len(t.examples), t.name))
588 1 some_module
589 3 some_module.SampleClass
590 3 some_module.SampleClass.NestedClass
591 1 some_module.SampleClass.NestedClass.__init__
592 1 some_module.SampleClass.__init__
593 2 some_module.SampleClass.a_classmethod
594 1 some_module.SampleClass.a_classmethod_property
595 1 some_module.SampleClass.a_property
596 1 some_module.SampleClass.a_staticmethod
597 1 some_module.SampleClass.double
598 1 some_module.SampleClass.get
599 1 some_module.__test__.c
600 2 some_module.__test__.d
601 1 some_module.sample_func
602
603 Duplicate Removal
604 ~~~~~~~~~~~~~~~~~
605 If a single object is listed twice (under different names), then tests
606 will only be generated for it once:
607
608 >>> from test import doctest_aliases
609 >>> assert doctest_aliases.TwoNames.f
610 >>> assert doctest_aliases.TwoNames.g
611 >>> tests = excl_empty_finder.find(doctest_aliases)
612 >>> print(len(tests))
613 2
614 >>> print(tests[0].name)
615 test.doctest_aliases.TwoNames
616
617 TwoNames.f and TwoNames.g are bound to the same object.
618 We can't guess which will be found in doctest's traversal of
619 TwoNames.__dict__ first, so we have to allow for either.
620
621 >>> tests[1].name.split('.')[-1] in ['f', 'g']
622 True
623
624 Empty Tests
625 ~~~~~~~~~~~
626 By default, an object with no doctests doesn't create any tests:
627
628 >>> tests = doctest.DocTestFinder().find(SampleClass)
629 >>> for t in tests:
630 ... print('%2s %s' % (len(t.examples), t.name))
631 3 SampleClass
632 3 SampleClass.NestedClass
633 1 SampleClass.NestedClass.__init__
634 1 SampleClass.__init__
635 2 SampleClass.a_classmethod
636 1 SampleClass.a_classmethod_property
637 1 SampleClass.a_property
638 1 SampleClass.a_staticmethod
639 1 SampleClass.double
640 1 SampleClass.get
641
642 By default, that excluded objects with no doctests. exclude_empty=False
643 tells it to include (empty) tests for objects with no doctests. This feature
644 is really to support backward compatibility in what doctest.master.summarize()
645 displays.
646
647 >>> tests = doctest.DocTestFinder(exclude_empty=False).find(SampleClass)
648 >>> for t in tests:
649 ... print('%2s %s' % (len(t.examples), t.name))
650 3 SampleClass
651 3 SampleClass.NestedClass
652 1 SampleClass.NestedClass.__init__
653 0 SampleClass.NestedClass.get
654 0 SampleClass.NestedClass.square
655 1 SampleClass.__init__
656 2 SampleClass.a_classmethod
657 1 SampleClass.a_classmethod_property
658 1 SampleClass.a_property
659 1 SampleClass.a_staticmethod
660 1 SampleClass.double
661 1 SampleClass.get
662
663 When used with `exclude_empty=False` we are also interested in line numbers
664 of doctests that are empty.
665 It used to be broken for quite some time until `bpo-28249`.
666
667 >>> from test import doctest_lineno
668 >>> tests = doctest.DocTestFinder(exclude_empty=False).find(doctest_lineno)
669 >>> for t in tests:
670 ... print('%5s %s' % (t.lineno, t.name))
671 None test.doctest_lineno
672 22 test.doctest_lineno.ClassWithDocstring
673 30 test.doctest_lineno.ClassWithDoctest
674 None test.doctest_lineno.ClassWithoutDocstring
675 None test.doctest_lineno.MethodWrapper
676 39 test.doctest_lineno.MethodWrapper.method_with_docstring
677 45 test.doctest_lineno.MethodWrapper.method_with_doctest
678 None test.doctest_lineno.MethodWrapper.method_without_docstring
679 4 test.doctest_lineno.func_with_docstring
680 12 test.doctest_lineno.func_with_doctest
681 None test.doctest_lineno.func_without_docstring
682
683 Turning off Recursion
684 ~~~~~~~~~~~~~~~~~~~~~
685 DocTestFinder can be told not to look for tests in contained objects
686 using the `recurse` flag:
687
688 >>> tests = doctest.DocTestFinder(recurse=False).find(SampleClass)
689 >>> for t in tests:
690 ... print('%2s %s' % (len(t.examples), t.name))
691 3 SampleClass
692
693 Line numbers
694 ~~~~~~~~~~~~
695 DocTestFinder finds the line number of each example:
696
697 >>> def f(x):
698 ... '''
699 ... >>> x = 12
700 ...
701 ... some text
702 ...
703 ... >>> # examples are not created for comments & bare prompts.
704 ... >>>
705 ... ...
706 ...
707 ... >>> for x in range(10):
708 ... ... print(x, end=' ')
709 ... 0 1 2 3 4 5 6 7 8 9
710 ... >>> x//2
711 ... 6
712 ... '''
713 >>> test = doctest.DocTestFinder().find(f)[0]
714 >>> [e.lineno for e in test.examples]
715 [1, 9, 12]
716 """
717
718 if int.__doc__: # simple check for --without-doc-strings, skip if lacking
719 def non_Python_modules(): r"""
720
721 Finding Doctests in Modules Not Written in Python
722 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
723 DocTestFinder can also find doctests in most modules not written in Python.
724 We'll use builtins as an example, since it almost certainly isn't written in
725 plain ol' Python and is guaranteed to be available.
726
727 >>> import builtins
728 >>> tests = doctest.DocTestFinder().find(builtins)
729 >>> 825 < len(tests) < 845 # approximate number of objects with docstrings
730 True
731 >>> real_tests = [t for t in tests if len(t.examples) > 0]
732 >>> len(real_tests) # objects that actually have doctests
733 14
734 >>> for t in real_tests:
735 ... print('{} {}'.format(len(t.examples), t.name))
736 ...
737 1 builtins.bin
738 5 builtins.bytearray.hex
739 5 builtins.bytes.hex
740 3 builtins.float.as_integer_ratio
741 2 builtins.float.fromhex
742 2 builtins.float.hex
743 1 builtins.hex
744 1 builtins.int
745 3 builtins.int.as_integer_ratio
746 2 builtins.int.bit_count
747 2 builtins.int.bit_length
748 5 builtins.memoryview.hex
749 1 builtins.oct
750 1 builtins.zip
751
752 Note here that 'bin', 'oct', and 'hex' are functions; 'float.as_integer_ratio',
753 'float.hex', and 'int.bit_length' are methods; 'float.fromhex' is a classmethod,
754 and 'int' is a type.
755 """
756
757
758 class ESC[4;38;5;81mTestDocTestFinder(ESC[4;38;5;149munittestESC[4;38;5;149m.ESC[4;38;5;149mTestCase):
759
760 def test_issue35753(self):
761 # This import of `call` should trigger issue35753 when
762 # DocTestFinder.find() is called due to inspect.unwrap() failing,
763 # however with a patched doctest this should succeed.
764 from unittest.mock import call
765 dummy_module = types.ModuleType("dummy")
766 dummy_module.__dict__['inject_call'] = call
767 finder = doctest.DocTestFinder()
768 self.assertEqual(finder.find(dummy_module), [])
769
770 def test_empty_namespace_package(self):
771 pkg_name = 'doctest_empty_pkg'
772 with tempfile.TemporaryDirectory() as parent_dir:
773 pkg_dir = os.path.join(parent_dir, pkg_name)
774 os.mkdir(pkg_dir)
775 sys.path.append(parent_dir)
776 try:
777 mod = importlib.import_module(pkg_name)
778 finally:
779 import_helper.forget(pkg_name)
780 sys.path.pop()
781
782 include_empty_finder = doctest.DocTestFinder(exclude_empty=False)
783 exclude_empty_finder = doctest.DocTestFinder(exclude_empty=True)
784
785 self.assertEqual(len(include_empty_finder.find(mod)), 1)
786 self.assertEqual(len(exclude_empty_finder.find(mod)), 0)
787
788 def test_DocTestParser(): r"""
789 Unit tests for the `DocTestParser` class.
790
791 DocTestParser is used to parse docstrings containing doctest examples.
792
793 The `parse` method divides a docstring into examples and intervening
794 text:
795
796 >>> s = '''
797 ... >>> x, y = 2, 3 # no output expected
798 ... >>> if 1:
799 ... ... print(x)
800 ... ... print(y)
801 ... 2
802 ... 3
803 ...
804 ... Some text.
805 ... >>> x+y
806 ... 5
807 ... '''
808 >>> parser = doctest.DocTestParser()
809 >>> for piece in parser.parse(s):
810 ... if isinstance(piece, doctest.Example):
811 ... print('Example:', (piece.source, piece.want, piece.lineno))
812 ... else:
813 ... print(' Text:', repr(piece))
814 Text: '\n'
815 Example: ('x, y = 2, 3 # no output expected\n', '', 1)
816 Text: ''
817 Example: ('if 1:\n print(x)\n print(y)\n', '2\n3\n', 2)
818 Text: '\nSome text.\n'
819 Example: ('x+y\n', '5\n', 9)
820 Text: ''
821
822 The `get_examples` method returns just the examples:
823
824 >>> for piece in parser.get_examples(s):
825 ... print((piece.source, piece.want, piece.lineno))
826 ('x, y = 2, 3 # no output expected\n', '', 1)
827 ('if 1:\n print(x)\n print(y)\n', '2\n3\n', 2)
828 ('x+y\n', '5\n', 9)
829
830 The `get_doctest` method creates a Test from the examples, along with the
831 given arguments:
832
833 >>> test = parser.get_doctest(s, {}, 'name', 'filename', lineno=5)
834 >>> (test.name, test.filename, test.lineno)
835 ('name', 'filename', 5)
836 >>> for piece in test.examples:
837 ... print((piece.source, piece.want, piece.lineno))
838 ('x, y = 2, 3 # no output expected\n', '', 1)
839 ('if 1:\n print(x)\n print(y)\n', '2\n3\n', 2)
840 ('x+y\n', '5\n', 9)
841 """
842
843 class ESC[4;38;5;81mtest_DocTestRunner:
844 def basics(): r"""
845 Unit tests for the `DocTestRunner` class.
846
847 DocTestRunner is used to run DocTest test cases, and to accumulate
848 statistics. Here's a simple DocTest case we can use:
849
850 >>> def f(x):
851 ... '''
852 ... >>> x = 12
853 ... >>> print(x)
854 ... 12
855 ... >>> x//2
856 ... 6
857 ... '''
858 >>> test = doctest.DocTestFinder().find(f)[0]
859
860 The main DocTestRunner interface is the `run` method, which runs a
861 given DocTest case in a given namespace (globs). It returns a tuple
862 `(f,t)`, where `f` is the number of failed tests and `t` is the number
863 of tried tests.
864
865 >>> doctest.DocTestRunner(verbose=False).run(test)
866 TestResults(failed=0, attempted=3)
867
868 If any example produces incorrect output, then the test runner reports
869 the failure and proceeds to the next example:
870
871 >>> def f(x):
872 ... '''
873 ... >>> x = 12
874 ... >>> print(x)
875 ... 14
876 ... >>> x//2
877 ... 6
878 ... '''
879 >>> test = doctest.DocTestFinder().find(f)[0]
880 >>> doctest.DocTestRunner(verbose=True).run(test)
881 ... # doctest: +ELLIPSIS
882 Trying:
883 x = 12
884 Expecting nothing
885 ok
886 Trying:
887 print(x)
888 Expecting:
889 14
890 **********************************************************************
891 File ..., line 4, in f
892 Failed example:
893 print(x)
894 Expected:
895 14
896 Got:
897 12
898 Trying:
899 x//2
900 Expecting:
901 6
902 ok
903 TestResults(failed=1, attempted=3)
904 """
905 def verbose_flag(): r"""
906 The `verbose` flag makes the test runner generate more detailed
907 output:
908
909 >>> def f(x):
910 ... '''
911 ... >>> x = 12
912 ... >>> print(x)
913 ... 12
914 ... >>> x//2
915 ... 6
916 ... '''
917 >>> test = doctest.DocTestFinder().find(f)[0]
918
919 >>> doctest.DocTestRunner(verbose=True).run(test)
920 Trying:
921 x = 12
922 Expecting nothing
923 ok
924 Trying:
925 print(x)
926 Expecting:
927 12
928 ok
929 Trying:
930 x//2
931 Expecting:
932 6
933 ok
934 TestResults(failed=0, attempted=3)
935
936 If the `verbose` flag is unspecified, then the output will be verbose
937 iff `-v` appears in sys.argv:
938
939 >>> # Save the real sys.argv list.
940 >>> old_argv = sys.argv
941
942 >>> # If -v does not appear in sys.argv, then output isn't verbose.
943 >>> sys.argv = ['test']
944 >>> doctest.DocTestRunner().run(test)
945 TestResults(failed=0, attempted=3)
946
947 >>> # If -v does appear in sys.argv, then output is verbose.
948 >>> sys.argv = ['test', '-v']
949 >>> doctest.DocTestRunner().run(test)
950 Trying:
951 x = 12
952 Expecting nothing
953 ok
954 Trying:
955 print(x)
956 Expecting:
957 12
958 ok
959 Trying:
960 x//2
961 Expecting:
962 6
963 ok
964 TestResults(failed=0, attempted=3)
965
966 >>> # Restore sys.argv
967 >>> sys.argv = old_argv
968
969 In the remaining examples, the test runner's verbosity will be
970 explicitly set, to ensure that the test behavior is consistent.
971 """
972 def exceptions(): r"""
973 Tests of `DocTestRunner`'s exception handling.
974
975 An expected exception is specified with a traceback message. The
976 lines between the first line and the type/value may be omitted or
977 replaced with any other string:
978
979 >>> def f(x):
980 ... '''
981 ... >>> x = 12
982 ... >>> print(x//0)
983 ... Traceback (most recent call last):
984 ... ZeroDivisionError: integer division or modulo by zero
985 ... '''
986 >>> test = doctest.DocTestFinder().find(f)[0]
987 >>> doctest.DocTestRunner(verbose=False).run(test)
988 TestResults(failed=0, attempted=2)
989
990 An example may not generate output before it raises an exception; if
991 it does, then the traceback message will not be recognized as
992 signaling an expected exception, so the example will be reported as an
993 unexpected exception:
994
995 >>> def f(x):
996 ... '''
997 ... >>> x = 12
998 ... >>> print('pre-exception output', x//0)
999 ... pre-exception output
1000 ... Traceback (most recent call last):
1001 ... ZeroDivisionError: integer division or modulo by zero
1002 ... '''
1003 >>> test = doctest.DocTestFinder().find(f)[0]
1004 >>> doctest.DocTestRunner(verbose=False).run(test)
1005 ... # doctest: +ELLIPSIS
1006 **********************************************************************
1007 File ..., line 4, in f
1008 Failed example:
1009 print('pre-exception output', x//0)
1010 Exception raised:
1011 ...
1012 ZeroDivisionError: integer division or modulo by zero
1013 TestResults(failed=1, attempted=2)
1014
1015 Exception messages may contain newlines:
1016
1017 >>> def f(x):
1018 ... r'''
1019 ... >>> raise ValueError('multi\nline\nmessage')
1020 ... Traceback (most recent call last):
1021 ... ValueError: multi
1022 ... line
1023 ... message
1024 ... '''
1025 >>> test = doctest.DocTestFinder().find(f)[0]
1026 >>> doctest.DocTestRunner(verbose=False).run(test)
1027 TestResults(failed=0, attempted=1)
1028
1029 If an exception is expected, but an exception with the wrong type or
1030 message is raised, then it is reported as a failure:
1031
1032 >>> def f(x):
1033 ... r'''
1034 ... >>> raise ValueError('message')
1035 ... Traceback (most recent call last):
1036 ... ValueError: wrong message
1037 ... '''
1038 >>> test = doctest.DocTestFinder().find(f)[0]
1039 >>> doctest.DocTestRunner(verbose=False).run(test)
1040 ... # doctest: +ELLIPSIS
1041 **********************************************************************
1042 File ..., line 3, in f
1043 Failed example:
1044 raise ValueError('message')
1045 Expected:
1046 Traceback (most recent call last):
1047 ValueError: wrong message
1048 Got:
1049 Traceback (most recent call last):
1050 ...
1051 ValueError: message
1052 TestResults(failed=1, attempted=1)
1053
1054 However, IGNORE_EXCEPTION_DETAIL can be used to allow a mismatch in the
1055 detail:
1056
1057 >>> def f(x):
1058 ... r'''
1059 ... >>> raise ValueError('message') #doctest: +IGNORE_EXCEPTION_DETAIL
1060 ... Traceback (most recent call last):
1061 ... ValueError: wrong message
1062 ... '''
1063 >>> test = doctest.DocTestFinder().find(f)[0]
1064 >>> doctest.DocTestRunner(verbose=False).run(test)
1065 TestResults(failed=0, attempted=1)
1066
1067 IGNORE_EXCEPTION_DETAIL also ignores difference in exception formatting
1068 between Python versions. For example, in Python 2.x, the module path of
1069 the exception is not in the output, but this will fail under Python 3:
1070
1071 >>> def f(x):
1072 ... r'''
1073 ... >>> from http.client import HTTPException
1074 ... >>> raise HTTPException('message')
1075 ... Traceback (most recent call last):
1076 ... HTTPException: message
1077 ... '''
1078 >>> test = doctest.DocTestFinder().find(f)[0]
1079 >>> doctest.DocTestRunner(verbose=False).run(test)
1080 ... # doctest: +ELLIPSIS
1081 **********************************************************************
1082 File ..., line 4, in f
1083 Failed example:
1084 raise HTTPException('message')
1085 Expected:
1086 Traceback (most recent call last):
1087 HTTPException: message
1088 Got:
1089 Traceback (most recent call last):
1090 ...
1091 http.client.HTTPException: message
1092 TestResults(failed=1, attempted=2)
1093
1094 But in Python 3 the module path is included, and therefore a test must look
1095 like the following test to succeed in Python 3. But that test will fail under
1096 Python 2.
1097
1098 >>> def f(x):
1099 ... r'''
1100 ... >>> from http.client import HTTPException
1101 ... >>> raise HTTPException('message')
1102 ... Traceback (most recent call last):
1103 ... http.client.HTTPException: message
1104 ... '''
1105 >>> test = doctest.DocTestFinder().find(f)[0]
1106 >>> doctest.DocTestRunner(verbose=False).run(test)
1107 TestResults(failed=0, attempted=2)
1108
1109 However, with IGNORE_EXCEPTION_DETAIL, the module name of the exception
1110 (or its unexpected absence) will be ignored:
1111
1112 >>> def f(x):
1113 ... r'''
1114 ... >>> from http.client import HTTPException
1115 ... >>> raise HTTPException('message') #doctest: +IGNORE_EXCEPTION_DETAIL
1116 ... Traceback (most recent call last):
1117 ... HTTPException: message
1118 ... '''
1119 >>> test = doctest.DocTestFinder().find(f)[0]
1120 >>> doctest.DocTestRunner(verbose=False).run(test)
1121 TestResults(failed=0, attempted=2)
1122
1123 The module path will be completely ignored, so two different module paths will
1124 still pass if IGNORE_EXCEPTION_DETAIL is given. This is intentional, so it can
1125 be used when exceptions have changed module.
1126
1127 >>> def f(x):
1128 ... r'''
1129 ... >>> from http.client import HTTPException
1130 ... >>> raise HTTPException('message') #doctest: +IGNORE_EXCEPTION_DETAIL
1131 ... Traceback (most recent call last):
1132 ... foo.bar.HTTPException: message
1133 ... '''
1134 >>> test = doctest.DocTestFinder().find(f)[0]
1135 >>> doctest.DocTestRunner(verbose=False).run(test)
1136 TestResults(failed=0, attempted=2)
1137
1138 But IGNORE_EXCEPTION_DETAIL does not allow a mismatch in the exception type:
1139
1140 >>> def f(x):
1141 ... r'''
1142 ... >>> raise ValueError('message') #doctest: +IGNORE_EXCEPTION_DETAIL
1143 ... Traceback (most recent call last):
1144 ... TypeError: wrong type
1145 ... '''
1146 >>> test = doctest.DocTestFinder().find(f)[0]
1147 >>> doctest.DocTestRunner(verbose=False).run(test)
1148 ... # doctest: +ELLIPSIS
1149 **********************************************************************
1150 File ..., line 3, in f
1151 Failed example:
1152 raise ValueError('message') #doctest: +IGNORE_EXCEPTION_DETAIL
1153 Expected:
1154 Traceback (most recent call last):
1155 TypeError: wrong type
1156 Got:
1157 Traceback (most recent call last):
1158 ...
1159 ValueError: message
1160 TestResults(failed=1, attempted=1)
1161
1162 If the exception does not have a message, you can still use
1163 IGNORE_EXCEPTION_DETAIL to normalize the modules between Python 2 and 3:
1164
1165 >>> def f(x):
1166 ... r'''
1167 ... >>> from http.client import HTTPException
1168 ... >>> raise HTTPException() #doctest: +IGNORE_EXCEPTION_DETAIL
1169 ... Traceback (most recent call last):
1170 ... foo.bar.HTTPException
1171 ... '''
1172 >>> test = doctest.DocTestFinder().find(f)[0]
1173 >>> doctest.DocTestRunner(verbose=False).run(test)
1174 TestResults(failed=0, attempted=2)
1175
1176 Note that a trailing colon doesn't matter either:
1177
1178 >>> def f(x):
1179 ... r'''
1180 ... >>> from http.client import HTTPException
1181 ... >>> raise HTTPException() #doctest: +IGNORE_EXCEPTION_DETAIL
1182 ... Traceback (most recent call last):
1183 ... foo.bar.HTTPException:
1184 ... '''
1185 >>> test = doctest.DocTestFinder().find(f)[0]
1186 >>> doctest.DocTestRunner(verbose=False).run(test)
1187 TestResults(failed=0, attempted=2)
1188
1189 If an exception is raised but not expected, then it is reported as an
1190 unexpected exception:
1191
1192 >>> def f(x):
1193 ... r'''
1194 ... >>> 1//0
1195 ... 0
1196 ... '''
1197 >>> test = doctest.DocTestFinder().find(f)[0]
1198 >>> doctest.DocTestRunner(verbose=False).run(test)
1199 ... # doctest: +ELLIPSIS
1200 **********************************************************************
1201 File ..., line 3, in f
1202 Failed example:
1203 1//0
1204 Exception raised:
1205 Traceback (most recent call last):
1206 ...
1207 ZeroDivisionError: integer division or modulo by zero
1208 TestResults(failed=1, attempted=1)
1209 """
1210 def displayhook(): r"""
1211 Test that changing sys.displayhook doesn't matter for doctest.
1212
1213 >>> import sys
1214 >>> orig_displayhook = sys.displayhook
1215 >>> def my_displayhook(x):
1216 ... print('hi!')
1217 >>> sys.displayhook = my_displayhook
1218 >>> def f():
1219 ... '''
1220 ... >>> 3
1221 ... 3
1222 ... '''
1223 >>> test = doctest.DocTestFinder().find(f)[0]
1224 >>> r = doctest.DocTestRunner(verbose=False).run(test)
1225 >>> post_displayhook = sys.displayhook
1226
1227 We need to restore sys.displayhook now, so that we'll be able to test
1228 results.
1229
1230 >>> sys.displayhook = orig_displayhook
1231
1232 Ok, now we can check that everything is ok.
1233
1234 >>> r
1235 TestResults(failed=0, attempted=1)
1236 >>> post_displayhook is my_displayhook
1237 True
1238 """
1239 def optionflags(): r"""
1240 Tests of `DocTestRunner`'s option flag handling.
1241
1242 Several option flags can be used to customize the behavior of the test
1243 runner. These are defined as module constants in doctest, and passed
1244 to the DocTestRunner constructor (multiple constants should be ORed
1245 together).
1246
1247 The DONT_ACCEPT_TRUE_FOR_1 flag disables matches between True/False
1248 and 1/0:
1249
1250 >>> def f(x):
1251 ... '>>> True\n1\n'
1252
1253 >>> # Without the flag:
1254 >>> test = doctest.DocTestFinder().find(f)[0]
1255 >>> doctest.DocTestRunner(verbose=False).run(test)
1256 TestResults(failed=0, attempted=1)
1257
1258 >>> # With the flag:
1259 >>> test = doctest.DocTestFinder().find(f)[0]
1260 >>> flags = doctest.DONT_ACCEPT_TRUE_FOR_1
1261 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1262 ... # doctest: +ELLIPSIS
1263 **********************************************************************
1264 File ..., line 2, in f
1265 Failed example:
1266 True
1267 Expected:
1268 1
1269 Got:
1270 True
1271 TestResults(failed=1, attempted=1)
1272
1273 The DONT_ACCEPT_BLANKLINE flag disables the match between blank lines
1274 and the '<BLANKLINE>' marker:
1275
1276 >>> def f(x):
1277 ... '>>> print("a\\n\\nb")\na\n<BLANKLINE>\nb\n'
1278
1279 >>> # Without the flag:
1280 >>> test = doctest.DocTestFinder().find(f)[0]
1281 >>> doctest.DocTestRunner(verbose=False).run(test)
1282 TestResults(failed=0, attempted=1)
1283
1284 >>> # With the flag:
1285 >>> test = doctest.DocTestFinder().find(f)[0]
1286 >>> flags = doctest.DONT_ACCEPT_BLANKLINE
1287 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1288 ... # doctest: +ELLIPSIS
1289 **********************************************************************
1290 File ..., line 2, in f
1291 Failed example:
1292 print("a\n\nb")
1293 Expected:
1294 a
1295 <BLANKLINE>
1296 b
1297 Got:
1298 a
1299 <BLANKLINE>
1300 b
1301 TestResults(failed=1, attempted=1)
1302
1303 The NORMALIZE_WHITESPACE flag causes all sequences of whitespace to be
1304 treated as equal:
1305
1306 >>> def f(x):
1307 ... '>>> print(1, 2, 3)\n 1 2\n 3'
1308
1309 >>> # Without the flag:
1310 >>> test = doctest.DocTestFinder().find(f)[0]
1311 >>> doctest.DocTestRunner(verbose=False).run(test)
1312 ... # doctest: +ELLIPSIS
1313 **********************************************************************
1314 File ..., line 2, in f
1315 Failed example:
1316 print(1, 2, 3)
1317 Expected:
1318 1 2
1319 3
1320 Got:
1321 1 2 3
1322 TestResults(failed=1, attempted=1)
1323
1324 >>> # With the flag:
1325 >>> test = doctest.DocTestFinder().find(f)[0]
1326 >>> flags = doctest.NORMALIZE_WHITESPACE
1327 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1328 TestResults(failed=0, attempted=1)
1329
1330 An example from the docs:
1331 >>> print(list(range(20))) #doctest: +NORMALIZE_WHITESPACE
1332 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
1333 10, 11, 12, 13, 14, 15, 16, 17, 18, 19]
1334
1335 The ELLIPSIS flag causes ellipsis marker ("...") in the expected
1336 output to match any substring in the actual output:
1337
1338 >>> def f(x):
1339 ... '>>> print(list(range(15)))\n[0, 1, 2, ..., 14]\n'
1340
1341 >>> # Without the flag:
1342 >>> test = doctest.DocTestFinder().find(f)[0]
1343 >>> doctest.DocTestRunner(verbose=False).run(test)
1344 ... # doctest: +ELLIPSIS
1345 **********************************************************************
1346 File ..., line 2, in f
1347 Failed example:
1348 print(list(range(15)))
1349 Expected:
1350 [0, 1, 2, ..., 14]
1351 Got:
1352 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14]
1353 TestResults(failed=1, attempted=1)
1354
1355 >>> # With the flag:
1356 >>> test = doctest.DocTestFinder().find(f)[0]
1357 >>> flags = doctest.ELLIPSIS
1358 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1359 TestResults(failed=0, attempted=1)
1360
1361 ... also matches nothing:
1362
1363 >>> if 1:
1364 ... for i in range(100):
1365 ... print(i**2, end=' ') #doctest: +ELLIPSIS
1366 ... print('!')
1367 0 1...4...9 16 ... 36 49 64 ... 9801 !
1368
1369 ... can be surprising; e.g., this test passes:
1370
1371 >>> if 1: #doctest: +ELLIPSIS
1372 ... for i in range(20):
1373 ... print(i, end=' ')
1374 ... print(20)
1375 0 1 2 ...1...2...0
1376
1377 Examples from the docs:
1378
1379 >>> print(list(range(20))) # doctest:+ELLIPSIS
1380 [0, 1, ..., 18, 19]
1381
1382 >>> print(list(range(20))) # doctest: +ELLIPSIS
1383 ... # doctest: +NORMALIZE_WHITESPACE
1384 [0, 1, ..., 18, 19]
1385
1386 The SKIP flag causes an example to be skipped entirely. I.e., the
1387 example is not run. It can be useful in contexts where doctest
1388 examples serve as both documentation and test cases, and an example
1389 should be included for documentation purposes, but should not be
1390 checked (e.g., because its output is random, or depends on resources
1391 which would be unavailable.) The SKIP flag can also be used for
1392 'commenting out' broken examples.
1393
1394 >>> import unavailable_resource # doctest: +SKIP
1395 >>> unavailable_resource.do_something() # doctest: +SKIP
1396 >>> unavailable_resource.blow_up() # doctest: +SKIP
1397 Traceback (most recent call last):
1398 ...
1399 UncheckedBlowUpError: Nobody checks me.
1400
1401 >>> import random
1402 >>> print(random.random()) # doctest: +SKIP
1403 0.721216923889
1404
1405 The REPORT_UDIFF flag causes failures that involve multi-line expected
1406 and actual outputs to be displayed using a unified diff:
1407
1408 >>> def f(x):
1409 ... r'''
1410 ... >>> print('\n'.join('abcdefg'))
1411 ... a
1412 ... B
1413 ... c
1414 ... d
1415 ... f
1416 ... g
1417 ... h
1418 ... '''
1419
1420 >>> # Without the flag:
1421 >>> test = doctest.DocTestFinder().find(f)[0]
1422 >>> doctest.DocTestRunner(verbose=False).run(test)
1423 ... # doctest: +ELLIPSIS
1424 **********************************************************************
1425 File ..., line 3, in f
1426 Failed example:
1427 print('\n'.join('abcdefg'))
1428 Expected:
1429 a
1430 B
1431 c
1432 d
1433 f
1434 g
1435 h
1436 Got:
1437 a
1438 b
1439 c
1440 d
1441 e
1442 f
1443 g
1444 TestResults(failed=1, attempted=1)
1445
1446 >>> # With the flag:
1447 >>> test = doctest.DocTestFinder().find(f)[0]
1448 >>> flags = doctest.REPORT_UDIFF
1449 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1450 ... # doctest: +ELLIPSIS
1451 **********************************************************************
1452 File ..., line 3, in f
1453 Failed example:
1454 print('\n'.join('abcdefg'))
1455 Differences (unified diff with -expected +actual):
1456 @@ -1,7 +1,7 @@
1457 a
1458 -B
1459 +b
1460 c
1461 d
1462 +e
1463 f
1464 g
1465 -h
1466 TestResults(failed=1, attempted=1)
1467
1468 The REPORT_CDIFF flag causes failures that involve multi-line expected
1469 and actual outputs to be displayed using a context diff:
1470
1471 >>> # Reuse f() from the REPORT_UDIFF example, above.
1472 >>> test = doctest.DocTestFinder().find(f)[0]
1473 >>> flags = doctest.REPORT_CDIFF
1474 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1475 ... # doctest: +ELLIPSIS
1476 **********************************************************************
1477 File ..., line 3, in f
1478 Failed example:
1479 print('\n'.join('abcdefg'))
1480 Differences (context diff with expected followed by actual):
1481 ***************
1482 *** 1,7 ****
1483 a
1484 ! B
1485 c
1486 d
1487 f
1488 g
1489 - h
1490 --- 1,7 ----
1491 a
1492 ! b
1493 c
1494 d
1495 + e
1496 f
1497 g
1498 TestResults(failed=1, attempted=1)
1499
1500
1501 The REPORT_NDIFF flag causes failures to use the difflib.Differ algorithm
1502 used by the popular ndiff.py utility. This does intraline difference
1503 marking, as well as interline differences.
1504
1505 >>> def f(x):
1506 ... r'''
1507 ... >>> print("a b c d e f g h i j k l m")
1508 ... a b c d e f g h i j k 1 m
1509 ... '''
1510 >>> test = doctest.DocTestFinder().find(f)[0]
1511 >>> flags = doctest.REPORT_NDIFF
1512 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1513 ... # doctest: +ELLIPSIS
1514 **********************************************************************
1515 File ..., line 3, in f
1516 Failed example:
1517 print("a b c d e f g h i j k l m")
1518 Differences (ndiff with -expected +actual):
1519 - a b c d e f g h i j k 1 m
1520 ? ^
1521 + a b c d e f g h i j k l m
1522 ? + ++ ^
1523 TestResults(failed=1, attempted=1)
1524
1525 The REPORT_ONLY_FIRST_FAILURE suppresses result output after the first
1526 failing example:
1527
1528 >>> def f(x):
1529 ... r'''
1530 ... >>> print(1) # first success
1531 ... 1
1532 ... >>> print(2) # first failure
1533 ... 200
1534 ... >>> print(3) # second failure
1535 ... 300
1536 ... >>> print(4) # second success
1537 ... 4
1538 ... >>> print(5) # third failure
1539 ... 500
1540 ... '''
1541 >>> test = doctest.DocTestFinder().find(f)[0]
1542 >>> flags = doctest.REPORT_ONLY_FIRST_FAILURE
1543 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1544 ... # doctest: +ELLIPSIS
1545 **********************************************************************
1546 File ..., line 5, in f
1547 Failed example:
1548 print(2) # first failure
1549 Expected:
1550 200
1551 Got:
1552 2
1553 TestResults(failed=3, attempted=5)
1554
1555 However, output from `report_start` is not suppressed:
1556
1557 >>> doctest.DocTestRunner(verbose=True, optionflags=flags).run(test)
1558 ... # doctest: +ELLIPSIS
1559 Trying:
1560 print(1) # first success
1561 Expecting:
1562 1
1563 ok
1564 Trying:
1565 print(2) # first failure
1566 Expecting:
1567 200
1568 **********************************************************************
1569 File ..., line 5, in f
1570 Failed example:
1571 print(2) # first failure
1572 Expected:
1573 200
1574 Got:
1575 2
1576 TestResults(failed=3, attempted=5)
1577
1578 The FAIL_FAST flag causes the runner to exit after the first failing example,
1579 so subsequent examples are not even attempted:
1580
1581 >>> flags = doctest.FAIL_FAST
1582 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1583 ... # doctest: +ELLIPSIS
1584 **********************************************************************
1585 File ..., line 5, in f
1586 Failed example:
1587 print(2) # first failure
1588 Expected:
1589 200
1590 Got:
1591 2
1592 TestResults(failed=1, attempted=2)
1593
1594 Specifying both FAIL_FAST and REPORT_ONLY_FIRST_FAILURE is equivalent to
1595 FAIL_FAST only:
1596
1597 >>> flags = doctest.FAIL_FAST | doctest.REPORT_ONLY_FIRST_FAILURE
1598 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1599 ... # doctest: +ELLIPSIS
1600 **********************************************************************
1601 File ..., line 5, in f
1602 Failed example:
1603 print(2) # first failure
1604 Expected:
1605 200
1606 Got:
1607 2
1608 TestResults(failed=1, attempted=2)
1609
1610 For the purposes of both REPORT_ONLY_FIRST_FAILURE and FAIL_FAST, unexpected
1611 exceptions count as failures:
1612
1613 >>> def f(x):
1614 ... r'''
1615 ... >>> print(1) # first success
1616 ... 1
1617 ... >>> raise ValueError(2) # first failure
1618 ... 200
1619 ... >>> print(3) # second failure
1620 ... 300
1621 ... >>> print(4) # second success
1622 ... 4
1623 ... >>> print(5) # third failure
1624 ... 500
1625 ... '''
1626 >>> test = doctest.DocTestFinder().find(f)[0]
1627 >>> flags = doctest.REPORT_ONLY_FIRST_FAILURE
1628 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1629 ... # doctest: +ELLIPSIS
1630 **********************************************************************
1631 File ..., line 5, in f
1632 Failed example:
1633 raise ValueError(2) # first failure
1634 Exception raised:
1635 ...
1636 ValueError: 2
1637 TestResults(failed=3, attempted=5)
1638 >>> flags = doctest.FAIL_FAST
1639 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1640 ... # doctest: +ELLIPSIS
1641 **********************************************************************
1642 File ..., line 5, in f
1643 Failed example:
1644 raise ValueError(2) # first failure
1645 Exception raised:
1646 ...
1647 ValueError: 2
1648 TestResults(failed=1, attempted=2)
1649
1650 New option flags can also be registered, via register_optionflag(). Here
1651 we reach into doctest's internals a bit.
1652
1653 >>> unlikely = "UNLIKELY_OPTION_NAME"
1654 >>> unlikely in doctest.OPTIONFLAGS_BY_NAME
1655 False
1656 >>> new_flag_value = doctest.register_optionflag(unlikely)
1657 >>> unlikely in doctest.OPTIONFLAGS_BY_NAME
1658 True
1659
1660 Before 2.4.4/2.5, registering a name more than once erroneously created
1661 more than one flag value. Here we verify that's fixed:
1662
1663 >>> redundant_flag_value = doctest.register_optionflag(unlikely)
1664 >>> redundant_flag_value == new_flag_value
1665 True
1666
1667 Clean up.
1668 >>> del doctest.OPTIONFLAGS_BY_NAME[unlikely]
1669
1670 """
1671
1672 def option_directives(): r"""
1673 Tests of `DocTestRunner`'s option directive mechanism.
1674
1675 Option directives can be used to turn option flags on or off for a
1676 single example. To turn an option on for an example, follow that
1677 example with a comment of the form ``# doctest: +OPTION``:
1678
1679 >>> def f(x): r'''
1680 ... >>> print(list(range(10))) # should fail: no ellipsis
1681 ... [0, 1, ..., 9]
1682 ...
1683 ... >>> print(list(range(10))) # doctest: +ELLIPSIS
1684 ... [0, 1, ..., 9]
1685 ... '''
1686 >>> test = doctest.DocTestFinder().find(f)[0]
1687 >>> doctest.DocTestRunner(verbose=False).run(test)
1688 ... # doctest: +ELLIPSIS
1689 **********************************************************************
1690 File ..., line 2, in f
1691 Failed example:
1692 print(list(range(10))) # should fail: no ellipsis
1693 Expected:
1694 [0, 1, ..., 9]
1695 Got:
1696 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1697 TestResults(failed=1, attempted=2)
1698
1699 To turn an option off for an example, follow that example with a
1700 comment of the form ``# doctest: -OPTION``:
1701
1702 >>> def f(x): r'''
1703 ... >>> print(list(range(10)))
1704 ... [0, 1, ..., 9]
1705 ...
1706 ... >>> # should fail: no ellipsis
1707 ... >>> print(list(range(10))) # doctest: -ELLIPSIS
1708 ... [0, 1, ..., 9]
1709 ... '''
1710 >>> test = doctest.DocTestFinder().find(f)[0]
1711 >>> doctest.DocTestRunner(verbose=False,
1712 ... optionflags=doctest.ELLIPSIS).run(test)
1713 ... # doctest: +ELLIPSIS
1714 **********************************************************************
1715 File ..., line 6, in f
1716 Failed example:
1717 print(list(range(10))) # doctest: -ELLIPSIS
1718 Expected:
1719 [0, 1, ..., 9]
1720 Got:
1721 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1722 TestResults(failed=1, attempted=2)
1723
1724 Option directives affect only the example that they appear with; they
1725 do not change the options for surrounding examples:
1726
1727 >>> def f(x): r'''
1728 ... >>> print(list(range(10))) # Should fail: no ellipsis
1729 ... [0, 1, ..., 9]
1730 ...
1731 ... >>> print(list(range(10))) # doctest: +ELLIPSIS
1732 ... [0, 1, ..., 9]
1733 ...
1734 ... >>> print(list(range(10))) # Should fail: no ellipsis
1735 ... [0, 1, ..., 9]
1736 ... '''
1737 >>> test = doctest.DocTestFinder().find(f)[0]
1738 >>> doctest.DocTestRunner(verbose=False).run(test)
1739 ... # doctest: +ELLIPSIS
1740 **********************************************************************
1741 File ..., line 2, in f
1742 Failed example:
1743 print(list(range(10))) # Should fail: no ellipsis
1744 Expected:
1745 [0, 1, ..., 9]
1746 Got:
1747 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1748 **********************************************************************
1749 File ..., line 8, in f
1750 Failed example:
1751 print(list(range(10))) # Should fail: no ellipsis
1752 Expected:
1753 [0, 1, ..., 9]
1754 Got:
1755 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1756 TestResults(failed=2, attempted=3)
1757
1758 Multiple options may be modified by a single option directive. They
1759 may be separated by whitespace, commas, or both:
1760
1761 >>> def f(x): r'''
1762 ... >>> print(list(range(10))) # Should fail
1763 ... [0, 1, ..., 9]
1764 ... >>> print(list(range(10))) # Should succeed
1765 ... ... # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
1766 ... [0, 1, ..., 9]
1767 ... '''
1768 >>> test = doctest.DocTestFinder().find(f)[0]
1769 >>> doctest.DocTestRunner(verbose=False).run(test)
1770 ... # doctest: +ELLIPSIS
1771 **********************************************************************
1772 File ..., line 2, in f
1773 Failed example:
1774 print(list(range(10))) # Should fail
1775 Expected:
1776 [0, 1, ..., 9]
1777 Got:
1778 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1779 TestResults(failed=1, attempted=2)
1780
1781 >>> def f(x): r'''
1782 ... >>> print(list(range(10))) # Should fail
1783 ... [0, 1, ..., 9]
1784 ... >>> print(list(range(10))) # Should succeed
1785 ... ... # doctest: +ELLIPSIS,+NORMALIZE_WHITESPACE
1786 ... [0, 1, ..., 9]
1787 ... '''
1788 >>> test = doctest.DocTestFinder().find(f)[0]
1789 >>> doctest.DocTestRunner(verbose=False).run(test)
1790 ... # doctest: +ELLIPSIS
1791 **********************************************************************
1792 File ..., line 2, in f
1793 Failed example:
1794 print(list(range(10))) # Should fail
1795 Expected:
1796 [0, 1, ..., 9]
1797 Got:
1798 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1799 TestResults(failed=1, attempted=2)
1800
1801 >>> def f(x): r'''
1802 ... >>> print(list(range(10))) # Should fail
1803 ... [0, 1, ..., 9]
1804 ... >>> print(list(range(10))) # Should succeed
1805 ... ... # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
1806 ... [0, 1, ..., 9]
1807 ... '''
1808 >>> test = doctest.DocTestFinder().find(f)[0]
1809 >>> doctest.DocTestRunner(verbose=False).run(test)
1810 ... # doctest: +ELLIPSIS
1811 **********************************************************************
1812 File ..., line 2, in f
1813 Failed example:
1814 print(list(range(10))) # Should fail
1815 Expected:
1816 [0, 1, ..., 9]
1817 Got:
1818 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1819 TestResults(failed=1, attempted=2)
1820
1821 The option directive may be put on the line following the source, as
1822 long as a continuation prompt is used:
1823
1824 >>> def f(x): r'''
1825 ... >>> print(list(range(10)))
1826 ... ... # doctest: +ELLIPSIS
1827 ... [0, 1, ..., 9]
1828 ... '''
1829 >>> test = doctest.DocTestFinder().find(f)[0]
1830 >>> doctest.DocTestRunner(verbose=False).run(test)
1831 TestResults(failed=0, attempted=1)
1832
1833 For examples with multi-line source, the option directive may appear
1834 at the end of any line:
1835
1836 >>> def f(x): r'''
1837 ... >>> for x in range(10): # doctest: +ELLIPSIS
1838 ... ... print(' ', x, end='', sep='')
1839 ... 0 1 2 ... 9
1840 ...
1841 ... >>> for x in range(10):
1842 ... ... print(' ', x, end='', sep='') # doctest: +ELLIPSIS
1843 ... 0 1 2 ... 9
1844 ... '''
1845 >>> test = doctest.DocTestFinder().find(f)[0]
1846 >>> doctest.DocTestRunner(verbose=False).run(test)
1847 TestResults(failed=0, attempted=2)
1848
1849 If more than one line of an example with multi-line source has an
1850 option directive, then they are combined:
1851
1852 >>> def f(x): r'''
1853 ... Should fail (option directive not on the last line):
1854 ... >>> for x in range(10): # doctest: +ELLIPSIS
1855 ... ... print(x, end=' ') # doctest: +NORMALIZE_WHITESPACE
1856 ... 0 1 2...9
1857 ... '''
1858 >>> test = doctest.DocTestFinder().find(f)[0]
1859 >>> doctest.DocTestRunner(verbose=False).run(test)
1860 TestResults(failed=0, attempted=1)
1861
1862 It is an error to have a comment of the form ``# doctest:`` that is
1863 *not* followed by words of the form ``+OPTION`` or ``-OPTION``, where
1864 ``OPTION`` is an option that has been registered with
1865 `register_option`:
1866
1867 >>> # Error: Option not registered
1868 >>> s = '>>> print(12) #doctest: +BADOPTION'
1869 >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1870 Traceback (most recent call last):
1871 ValueError: line 1 of the doctest for s has an invalid option: '+BADOPTION'
1872
1873 >>> # Error: No + or - prefix
1874 >>> s = '>>> print(12) #doctest: ELLIPSIS'
1875 >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1876 Traceback (most recent call last):
1877 ValueError: line 1 of the doctest for s has an invalid option: 'ELLIPSIS'
1878
1879 It is an error to use an option directive on a line that contains no
1880 source:
1881
1882 >>> s = '>>> # doctest: +ELLIPSIS'
1883 >>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1884 Traceback (most recent call last):
1885 ValueError: line 0 of the doctest for s has an option directive on a line with no example: '# doctest: +ELLIPSIS'
1886 """
1887
1888 def test_testsource(): r"""
1889 Unit tests for `testsource()`.
1890
1891 The testsource() function takes a module and a name, finds the (first)
1892 test with that name in that module, and converts it to a script. The
1893 example code is converted to regular Python code. The surrounding
1894 words and expected output are converted to comments:
1895
1896 >>> import test.test_doctest
1897 >>> name = 'test.test_doctest.sample_func'
1898 >>> print(doctest.testsource(test.test_doctest, name))
1899 # Blah blah
1900 #
1901 print(sample_func(22))
1902 # Expected:
1903 ## 44
1904 #
1905 # Yee ha!
1906 <BLANKLINE>
1907
1908 >>> name = 'test.test_doctest.SampleNewStyleClass'
1909 >>> print(doctest.testsource(test.test_doctest, name))
1910 print('1\n2\n3')
1911 # Expected:
1912 ## 1
1913 ## 2
1914 ## 3
1915 <BLANKLINE>
1916
1917 >>> name = 'test.test_doctest.SampleClass.a_classmethod'
1918 >>> print(doctest.testsource(test.test_doctest, name))
1919 print(SampleClass.a_classmethod(10))
1920 # Expected:
1921 ## 12
1922 print(SampleClass(0).a_classmethod(10))
1923 # Expected:
1924 ## 12
1925 <BLANKLINE>
1926 """
1927
1928 def test_debug(): r"""
1929
1930 Create a docstring that we want to debug:
1931
1932 >>> s = '''
1933 ... >>> x = 12
1934 ... >>> print(x)
1935 ... 12
1936 ... '''
1937
1938 Create some fake stdin input, to feed to the debugger:
1939
1940 >>> real_stdin = sys.stdin
1941 >>> sys.stdin = _FakeInput(['next', 'print(x)', 'continue'])
1942
1943 Run the debugger on the docstring, and then restore sys.stdin.
1944
1945 >>> try: doctest.debug_src(s)
1946 ... finally: sys.stdin = real_stdin
1947 > <string>(1)<module>()
1948 (Pdb) next
1949 12
1950 --Return--
1951 > <string>(1)<module>()->None
1952 (Pdb) print(x)
1953 12
1954 (Pdb) continue
1955
1956 """
1957
1958 if not hasattr(sys, 'gettrace') or not sys.gettrace():
1959 def test_pdb_set_trace():
1960 """Using pdb.set_trace from a doctest.
1961
1962 You can use pdb.set_trace from a doctest. To do so, you must
1963 retrieve the set_trace function from the pdb module at the time
1964 you use it. The doctest module changes sys.stdout so that it can
1965 capture program output. It also temporarily replaces pdb.set_trace
1966 with a version that restores stdout. This is necessary for you to
1967 see debugger output.
1968
1969 >>> doc = '''
1970 ... >>> x = 42
1971 ... >>> raise Exception('clé')
1972 ... Traceback (most recent call last):
1973 ... Exception: clé
1974 ... >>> import pdb; pdb.set_trace()
1975 ... '''
1976 >>> parser = doctest.DocTestParser()
1977 >>> test = parser.get_doctest(doc, {}, "foo-bar@baz", "foo-bar@baz.py", 0)
1978 >>> runner = doctest.DocTestRunner(verbose=False)
1979
1980 To demonstrate this, we'll create a fake standard input that
1981 captures our debugger input:
1982
1983 >>> real_stdin = sys.stdin
1984 >>> sys.stdin = _FakeInput([
1985 ... 'print(x)', # print data defined by the example
1986 ... 'continue', # stop debugging
1987 ... ''])
1988
1989 >>> try: runner.run(test)
1990 ... finally: sys.stdin = real_stdin
1991 --Return--
1992 > <doctest foo-bar@baz[2]>(1)<module>()->None
1993 -> import pdb; pdb.set_trace()
1994 (Pdb) print(x)
1995 42
1996 (Pdb) continue
1997 TestResults(failed=0, attempted=3)
1998
1999 You can also put pdb.set_trace in a function called from a test:
2000
2001 >>> def calls_set_trace():
2002 ... y=2
2003 ... import pdb; pdb.set_trace()
2004
2005 >>> doc = '''
2006 ... >>> x=1
2007 ... >>> calls_set_trace()
2008 ... '''
2009 >>> test = parser.get_doctest(doc, globals(), "foo-bar@baz", "foo-bar@baz.py", 0)
2010 >>> real_stdin = sys.stdin
2011 >>> sys.stdin = _FakeInput([
2012 ... 'print(y)', # print data defined in the function
2013 ... 'up', # out of function
2014 ... 'print(x)', # print data defined by the example
2015 ... 'continue', # stop debugging
2016 ... ''])
2017
2018 >>> try:
2019 ... runner.run(test)
2020 ... finally:
2021 ... sys.stdin = real_stdin
2022 --Return--
2023 > <doctest test.test_doctest.test_pdb_set_trace[7]>(3)calls_set_trace()->None
2024 -> import pdb; pdb.set_trace()
2025 (Pdb) print(y)
2026 2
2027 (Pdb) up
2028 > <doctest foo-bar@baz[1]>(1)<module>()
2029 -> calls_set_trace()
2030 (Pdb) print(x)
2031 1
2032 (Pdb) continue
2033 TestResults(failed=0, attempted=2)
2034
2035 During interactive debugging, source code is shown, even for
2036 doctest examples:
2037
2038 >>> doc = '''
2039 ... >>> def f(x):
2040 ... ... g(x*2)
2041 ... >>> def g(x):
2042 ... ... print(x+3)
2043 ... ... import pdb; pdb.set_trace()
2044 ... >>> f(3)
2045 ... '''
2046 >>> test = parser.get_doctest(doc, globals(), "foo-bar@baz", "foo-bar@baz.py", 0)
2047 >>> real_stdin = sys.stdin
2048 >>> sys.stdin = _FakeInput([
2049 ... 'list', # list source from example 2
2050 ... 'next', # return from g()
2051 ... 'list', # list source from example 1
2052 ... 'next', # return from f()
2053 ... 'list', # list source from example 3
2054 ... 'continue', # stop debugging
2055 ... ''])
2056 >>> try: runner.run(test)
2057 ... finally: sys.stdin = real_stdin
2058 ... # doctest: +NORMALIZE_WHITESPACE
2059 --Return--
2060 > <doctest foo-bar@baz[1]>(3)g()->None
2061 -> import pdb; pdb.set_trace()
2062 (Pdb) list
2063 1 def g(x):
2064 2 print(x+3)
2065 3 -> import pdb; pdb.set_trace()
2066 [EOF]
2067 (Pdb) next
2068 --Return--
2069 > <doctest foo-bar@baz[0]>(2)f()->None
2070 -> g(x*2)
2071 (Pdb) list
2072 1 def f(x):
2073 2 -> g(x*2)
2074 [EOF]
2075 (Pdb) next
2076 --Return--
2077 > <doctest foo-bar@baz[2]>(1)<module>()->None
2078 -> f(3)
2079 (Pdb) list
2080 1 -> f(3)
2081 [EOF]
2082 (Pdb) continue
2083 **********************************************************************
2084 File "foo-bar@baz.py", line 7, in foo-bar@baz
2085 Failed example:
2086 f(3)
2087 Expected nothing
2088 Got:
2089 9
2090 TestResults(failed=1, attempted=3)
2091 """
2092
2093 def test_pdb_set_trace_nested():
2094 """This illustrates more-demanding use of set_trace with nested functions.
2095
2096 >>> class C(object):
2097 ... def calls_set_trace(self):
2098 ... y = 1
2099 ... import pdb; pdb.set_trace()
2100 ... self.f1()
2101 ... y = 2
2102 ... def f1(self):
2103 ... x = 1
2104 ... self.f2()
2105 ... x = 2
2106 ... def f2(self):
2107 ... z = 1
2108 ... z = 2
2109
2110 >>> calls_set_trace = C().calls_set_trace
2111
2112 >>> doc = '''
2113 ... >>> a = 1
2114 ... >>> calls_set_trace()
2115 ... '''
2116 >>> parser = doctest.DocTestParser()
2117 >>> runner = doctest.DocTestRunner(verbose=False)
2118 >>> test = parser.get_doctest(doc, globals(), "foo-bar@baz", "foo-bar@baz.py", 0)
2119 >>> real_stdin = sys.stdin
2120 >>> sys.stdin = _FakeInput([
2121 ... 'print(y)', # print data defined in the function
2122 ... 'step', 'step', 'step', 'step', 'step', 'step', 'print(z)',
2123 ... 'up', 'print(x)',
2124 ... 'up', 'print(y)',
2125 ... 'up', 'print(foo)',
2126 ... 'continue', # stop debugging
2127 ... ''])
2128
2129 >>> try:
2130 ... runner.run(test)
2131 ... finally:
2132 ... sys.stdin = real_stdin
2133 ... # doctest: +REPORT_NDIFF
2134 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(5)calls_set_trace()
2135 -> self.f1()
2136 (Pdb) print(y)
2137 1
2138 (Pdb) step
2139 --Call--
2140 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(7)f1()
2141 -> def f1(self):
2142 (Pdb) step
2143 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(8)f1()
2144 -> x = 1
2145 (Pdb) step
2146 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(9)f1()
2147 -> self.f2()
2148 (Pdb) step
2149 --Call--
2150 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(11)f2()
2151 -> def f2(self):
2152 (Pdb) step
2153 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(12)f2()
2154 -> z = 1
2155 (Pdb) step
2156 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(13)f2()
2157 -> z = 2
2158 (Pdb) print(z)
2159 1
2160 (Pdb) up
2161 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(9)f1()
2162 -> self.f2()
2163 (Pdb) print(x)
2164 1
2165 (Pdb) up
2166 > <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(5)calls_set_trace()
2167 -> self.f1()
2168 (Pdb) print(y)
2169 1
2170 (Pdb) up
2171 > <doctest foo-bar@baz[1]>(1)<module>()
2172 -> calls_set_trace()
2173 (Pdb) print(foo)
2174 *** NameError: name 'foo' is not defined
2175 (Pdb) continue
2176 TestResults(failed=0, attempted=2)
2177 """
2178
2179 def test_DocTestSuite():
2180 """DocTestSuite creates a unittest test suite from a doctest.
2181
2182 We create a Suite by providing a module. A module can be provided
2183 by passing a module object:
2184
2185 >>> import unittest
2186 >>> import test.sample_doctest
2187 >>> suite = doctest.DocTestSuite(test.sample_doctest)
2188 >>> suite.run(unittest.TestResult())
2189 <unittest.result.TestResult run=9 errors=0 failures=4>
2190
2191 We can also supply the module by name:
2192
2193 >>> suite = doctest.DocTestSuite('test.sample_doctest')
2194 >>> suite.run(unittest.TestResult())
2195 <unittest.result.TestResult run=9 errors=0 failures=4>
2196
2197 The module need not contain any doctest examples:
2198
2199 >>> suite = doctest.DocTestSuite('test.sample_doctest_no_doctests')
2200 >>> suite.run(unittest.TestResult())
2201 <unittest.result.TestResult run=0 errors=0 failures=0>
2202
2203 The module need not contain any docstrings either:
2204
2205 >>> suite = doctest.DocTestSuite('test.sample_doctest_no_docstrings')
2206 >>> suite.run(unittest.TestResult())
2207 <unittest.result.TestResult run=0 errors=0 failures=0>
2208
2209 We can use the current module:
2210
2211 >>> suite = test.sample_doctest.test_suite()
2212 >>> suite.run(unittest.TestResult())
2213 <unittest.result.TestResult run=9 errors=0 failures=4>
2214
2215 We can also provide a DocTestFinder:
2216
2217 >>> finder = doctest.DocTestFinder()
2218 >>> suite = doctest.DocTestSuite('test.sample_doctest',
2219 ... test_finder=finder)
2220 >>> suite.run(unittest.TestResult())
2221 <unittest.result.TestResult run=9 errors=0 failures=4>
2222
2223 The DocTestFinder need not return any tests:
2224
2225 >>> finder = doctest.DocTestFinder()
2226 >>> suite = doctest.DocTestSuite('test.sample_doctest_no_docstrings',
2227 ... test_finder=finder)
2228 >>> suite.run(unittest.TestResult())
2229 <unittest.result.TestResult run=0 errors=0 failures=0>
2230
2231 We can supply global variables. If we pass globs, they will be
2232 used instead of the module globals. Here we'll pass an empty
2233 globals, triggering an extra error:
2234
2235 >>> suite = doctest.DocTestSuite('test.sample_doctest', globs={})
2236 >>> suite.run(unittest.TestResult())
2237 <unittest.result.TestResult run=9 errors=0 failures=5>
2238
2239 Alternatively, we can provide extra globals. Here we'll make an
2240 error go away by providing an extra global variable:
2241
2242 >>> suite = doctest.DocTestSuite('test.sample_doctest',
2243 ... extraglobs={'y': 1})
2244 >>> suite.run(unittest.TestResult())
2245 <unittest.result.TestResult run=9 errors=0 failures=3>
2246
2247 You can pass option flags. Here we'll cause an extra error
2248 by disabling the blank-line feature:
2249
2250 >>> suite = doctest.DocTestSuite('test.sample_doctest',
2251 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE)
2252 >>> suite.run(unittest.TestResult())
2253 <unittest.result.TestResult run=9 errors=0 failures=5>
2254
2255 You can supply setUp and tearDown functions:
2256
2257 >>> def setUp(t):
2258 ... import test.test_doctest
2259 ... test.test_doctest.sillySetup = True
2260
2261 >>> def tearDown(t):
2262 ... import test.test_doctest
2263 ... del test.test_doctest.sillySetup
2264
2265 Here, we installed a silly variable that the test expects:
2266
2267 >>> suite = doctest.DocTestSuite('test.sample_doctest',
2268 ... setUp=setUp, tearDown=tearDown)
2269 >>> suite.run(unittest.TestResult())
2270 <unittest.result.TestResult run=9 errors=0 failures=3>
2271
2272 But the tearDown restores sanity:
2273
2274 >>> import test.test_doctest
2275 >>> test.test_doctest.sillySetup
2276 Traceback (most recent call last):
2277 ...
2278 AttributeError: module 'test.test_doctest' has no attribute 'sillySetup'
2279
2280 The setUp and tearDown functions are passed test objects. Here
2281 we'll use the setUp function to supply the missing variable y:
2282
2283 >>> def setUp(test):
2284 ... test.globs['y'] = 1
2285
2286 >>> suite = doctest.DocTestSuite('test.sample_doctest', setUp=setUp)
2287 >>> suite.run(unittest.TestResult())
2288 <unittest.result.TestResult run=9 errors=0 failures=3>
2289
2290 Here, we didn't need to use a tearDown function because we
2291 modified the test globals, which are a copy of the
2292 sample_doctest module dictionary. The test globals are
2293 automatically cleared for us after a test.
2294 """
2295
2296 def test_DocFileSuite():
2297 """We can test tests found in text files using a DocFileSuite.
2298
2299 We create a suite by providing the names of one or more text
2300 files that include examples:
2301
2302 >>> import unittest
2303 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2304 ... 'test_doctest2.txt',
2305 ... 'test_doctest4.txt')
2306 >>> suite.run(unittest.TestResult())
2307 <unittest.result.TestResult run=3 errors=0 failures=2>
2308
2309 The test files are looked for in the directory containing the
2310 calling module. A package keyword argument can be provided to
2311 specify a different relative location.
2312
2313 >>> import unittest
2314 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2315 ... 'test_doctest2.txt',
2316 ... 'test_doctest4.txt',
2317 ... package='test')
2318 >>> suite.run(unittest.TestResult())
2319 <unittest.result.TestResult run=3 errors=0 failures=2>
2320
2321 Support for using a package's __loader__.get_data() is also
2322 provided.
2323
2324 >>> import unittest, pkgutil, test
2325 >>> added_loader = False
2326 >>> if not hasattr(test, '__loader__'):
2327 ... test.__loader__ = pkgutil.get_loader(test)
2328 ... added_loader = True
2329 >>> try:
2330 ... suite = doctest.DocFileSuite('test_doctest.txt',
2331 ... 'test_doctest2.txt',
2332 ... 'test_doctest4.txt',
2333 ... package='test')
2334 ... suite.run(unittest.TestResult())
2335 ... finally:
2336 ... if added_loader:
2337 ... del test.__loader__
2338 <unittest.result.TestResult run=3 errors=0 failures=2>
2339
2340 '/' should be used as a path separator. It will be converted
2341 to a native separator at run time:
2342
2343 >>> suite = doctest.DocFileSuite('../test/test_doctest.txt')
2344 >>> suite.run(unittest.TestResult())
2345 <unittest.result.TestResult run=1 errors=0 failures=1>
2346
2347 If DocFileSuite is used from an interactive session, then files
2348 are resolved relative to the directory of sys.argv[0]:
2349
2350 >>> import types, os.path, test.test_doctest
2351 >>> save_argv = sys.argv
2352 >>> sys.argv = [test.test_doctest.__file__]
2353 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2354 ... package=types.ModuleType('__main__'))
2355 >>> sys.argv = save_argv
2356
2357 By setting `module_relative=False`, os-specific paths may be
2358 used (including absolute paths and paths relative to the
2359 working directory):
2360
2361 >>> # Get the absolute path of the test package.
2362 >>> test_doctest_path = os.path.abspath(test.test_doctest.__file__)
2363 >>> test_pkg_path = os.path.split(test_doctest_path)[0]
2364
2365 >>> # Use it to find the absolute path of test_doctest.txt.
2366 >>> test_file = os.path.join(test_pkg_path, 'test_doctest.txt')
2367
2368 >>> suite = doctest.DocFileSuite(test_file, module_relative=False)
2369 >>> suite.run(unittest.TestResult())
2370 <unittest.result.TestResult run=1 errors=0 failures=1>
2371
2372 It is an error to specify `package` when `module_relative=False`:
2373
2374 >>> suite = doctest.DocFileSuite(test_file, module_relative=False,
2375 ... package='test')
2376 Traceback (most recent call last):
2377 ValueError: Package may only be specified for module-relative paths.
2378
2379 You can specify initial global variables:
2380
2381 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2382 ... 'test_doctest2.txt',
2383 ... 'test_doctest4.txt',
2384 ... globs={'favorite_color': 'blue'})
2385 >>> suite.run(unittest.TestResult())
2386 <unittest.result.TestResult run=3 errors=0 failures=1>
2387
2388 In this case, we supplied a missing favorite color. You can
2389 provide doctest options:
2390
2391 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2392 ... 'test_doctest2.txt',
2393 ... 'test_doctest4.txt',
2394 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE,
2395 ... globs={'favorite_color': 'blue'})
2396 >>> suite.run(unittest.TestResult())
2397 <unittest.result.TestResult run=3 errors=0 failures=2>
2398
2399 And, you can provide setUp and tearDown functions:
2400
2401 >>> def setUp(t):
2402 ... import test.test_doctest
2403 ... test.test_doctest.sillySetup = True
2404
2405 >>> def tearDown(t):
2406 ... import test.test_doctest
2407 ... del test.test_doctest.sillySetup
2408
2409 Here, we installed a silly variable that the test expects:
2410
2411 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2412 ... 'test_doctest2.txt',
2413 ... 'test_doctest4.txt',
2414 ... setUp=setUp, tearDown=tearDown)
2415 >>> suite.run(unittest.TestResult())
2416 <unittest.result.TestResult run=3 errors=0 failures=1>
2417
2418 But the tearDown restores sanity:
2419
2420 >>> import test.test_doctest
2421 >>> test.test_doctest.sillySetup
2422 Traceback (most recent call last):
2423 ...
2424 AttributeError: module 'test.test_doctest' has no attribute 'sillySetup'
2425
2426 The setUp and tearDown functions are passed test objects.
2427 Here, we'll use a setUp function to set the favorite color in
2428 test_doctest.txt:
2429
2430 >>> def setUp(test):
2431 ... test.globs['favorite_color'] = 'blue'
2432
2433 >>> suite = doctest.DocFileSuite('test_doctest.txt', setUp=setUp)
2434 >>> suite.run(unittest.TestResult())
2435 <unittest.result.TestResult run=1 errors=0 failures=0>
2436
2437 Here, we didn't need to use a tearDown function because we
2438 modified the test globals. The test globals are
2439 automatically cleared for us after a test.
2440
2441 Tests in a file run using `DocFileSuite` can also access the
2442 `__file__` global, which is set to the name of the file
2443 containing the tests:
2444
2445 >>> suite = doctest.DocFileSuite('test_doctest3.txt')
2446 >>> suite.run(unittest.TestResult())
2447 <unittest.result.TestResult run=1 errors=0 failures=0>
2448
2449 If the tests contain non-ASCII characters, we have to specify which
2450 encoding the file is encoded with. We do so by using the `encoding`
2451 parameter:
2452
2453 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2454 ... 'test_doctest2.txt',
2455 ... 'test_doctest4.txt',
2456 ... encoding='utf-8')
2457 >>> suite.run(unittest.TestResult())
2458 <unittest.result.TestResult run=3 errors=0 failures=2>
2459
2460 """
2461
2462 def test_trailing_space_in_test():
2463 """
2464 Trailing spaces in expected output are significant:
2465
2466 >>> x, y = 'foo', ''
2467 >>> print(x, y)
2468 foo \n
2469 """
2470
2471 class ESC[4;38;5;81mWrapper:
2472 def __init__(self, func):
2473 self.func = func
2474 functools.update_wrapper(self, func)
2475
2476 def __call__(self, *args, **kwargs):
2477 self.func(*args, **kwargs)
2478
2479 @Wrapper
2480 def test_look_in_unwrapped():
2481 """
2482 Docstrings in wrapped functions must be detected as well.
2483
2484 >>> 'one other test'
2485 'one other test'
2486 """
2487
2488 def test_unittest_reportflags():
2489 """Default unittest reporting flags can be set to control reporting
2490
2491 Here, we'll set the REPORT_ONLY_FIRST_FAILURE option so we see
2492 only the first failure of each test. First, we'll look at the
2493 output without the flag. The file test_doctest.txt file has two
2494 tests. They both fail if blank lines are disabled:
2495
2496 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2497 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE)
2498 >>> import unittest
2499 >>> result = suite.run(unittest.TestResult())
2500 >>> print(result.failures[0][1]) # doctest: +ELLIPSIS
2501 Traceback ...
2502 Failed example:
2503 favorite_color
2504 ...
2505 Failed example:
2506 if 1:
2507 ...
2508
2509 Note that we see both failures displayed.
2510
2511 >>> old = doctest.set_unittest_reportflags(
2512 ... doctest.REPORT_ONLY_FIRST_FAILURE)
2513
2514 Now, when we run the test:
2515
2516 >>> result = suite.run(unittest.TestResult())
2517 >>> print(result.failures[0][1]) # doctest: +ELLIPSIS
2518 Traceback ...
2519 Failed example:
2520 favorite_color
2521 Exception raised:
2522 ...
2523 NameError: name 'favorite_color' is not defined
2524 <BLANKLINE>
2525 <BLANKLINE>
2526
2527 We get only the first failure.
2528
2529 If we give any reporting options when we set up the tests,
2530 however:
2531
2532 >>> suite = doctest.DocFileSuite('test_doctest.txt',
2533 ... optionflags=doctest.DONT_ACCEPT_BLANKLINE | doctest.REPORT_NDIFF)
2534
2535 Then the default eporting options are ignored:
2536
2537 >>> result = suite.run(unittest.TestResult())
2538
2539 *NOTE*: These doctest are intentionally not placed in raw string to depict
2540 the trailing whitespace using `\x20` in the diff below.
2541
2542 >>> print(result.failures[0][1]) # doctest: +ELLIPSIS
2543 Traceback ...
2544 Failed example:
2545 favorite_color
2546 ...
2547 Failed example:
2548 if 1:
2549 print('a')
2550 print()
2551 print('b')
2552 Differences (ndiff with -expected +actual):
2553 a
2554 - <BLANKLINE>
2555 +\x20
2556 b
2557 <BLANKLINE>
2558 <BLANKLINE>
2559
2560
2561 Test runners can restore the formatting flags after they run:
2562
2563 >>> ignored = doctest.set_unittest_reportflags(old)
2564
2565 """
2566
2567 def test_testfile(): r"""
2568 Tests for the `testfile()` function. This function runs all the
2569 doctest examples in a given file. In its simple invocation, it is
2570 called with the name of a file, which is taken to be relative to the
2571 calling module. The return value is (#failures, #tests).
2572
2573 We don't want `-v` in sys.argv for these tests.
2574
2575 >>> save_argv = sys.argv
2576 >>> if '-v' in sys.argv:
2577 ... sys.argv = [arg for arg in save_argv if arg != '-v']
2578
2579
2580 >>> doctest.testfile('test_doctest.txt') # doctest: +ELLIPSIS
2581 **********************************************************************
2582 File "...", line 6, in test_doctest.txt
2583 Failed example:
2584 favorite_color
2585 Exception raised:
2586 ...
2587 NameError: name 'favorite_color' is not defined
2588 **********************************************************************
2589 1 items had failures:
2590 1 of 2 in test_doctest.txt
2591 ***Test Failed*** 1 failures.
2592 TestResults(failed=1, attempted=2)
2593 >>> doctest.master = None # Reset master.
2594
2595 (Note: we'll be clearing doctest.master after each call to
2596 `doctest.testfile`, to suppress warnings about multiple tests with the
2597 same name.)
2598
2599 Globals may be specified with the `globs` and `extraglobs` parameters:
2600
2601 >>> globs = {'favorite_color': 'blue'}
2602 >>> doctest.testfile('test_doctest.txt', globs=globs)
2603 TestResults(failed=0, attempted=2)
2604 >>> doctest.master = None # Reset master.
2605
2606 >>> extraglobs = {'favorite_color': 'red'}
2607 >>> doctest.testfile('test_doctest.txt', globs=globs,
2608 ... extraglobs=extraglobs) # doctest: +ELLIPSIS
2609 **********************************************************************
2610 File "...", line 6, in test_doctest.txt
2611 Failed example:
2612 favorite_color
2613 Expected:
2614 'blue'
2615 Got:
2616 'red'
2617 **********************************************************************
2618 1 items had failures:
2619 1 of 2 in test_doctest.txt
2620 ***Test Failed*** 1 failures.
2621 TestResults(failed=1, attempted=2)
2622 >>> doctest.master = None # Reset master.
2623
2624 The file may be made relative to a given module or package, using the
2625 optional `module_relative` parameter:
2626
2627 >>> doctest.testfile('test_doctest.txt', globs=globs,
2628 ... module_relative='test')
2629 TestResults(failed=0, attempted=2)
2630 >>> doctest.master = None # Reset master.
2631
2632 Verbosity can be increased with the optional `verbose` parameter:
2633
2634 >>> doctest.testfile('test_doctest.txt', globs=globs, verbose=True)
2635 Trying:
2636 favorite_color
2637 Expecting:
2638 'blue'
2639 ok
2640 Trying:
2641 if 1:
2642 print('a')
2643 print()
2644 print('b')
2645 Expecting:
2646 a
2647 <BLANKLINE>
2648 b
2649 ok
2650 1 items passed all tests:
2651 2 tests in test_doctest.txt
2652 2 tests in 1 items.
2653 2 passed and 0 failed.
2654 Test passed.
2655 TestResults(failed=0, attempted=2)
2656 >>> doctest.master = None # Reset master.
2657
2658 The name of the test may be specified with the optional `name`
2659 parameter:
2660
2661 >>> doctest.testfile('test_doctest.txt', name='newname')
2662 ... # doctest: +ELLIPSIS
2663 **********************************************************************
2664 File "...", line 6, in newname
2665 ...
2666 TestResults(failed=1, attempted=2)
2667 >>> doctest.master = None # Reset master.
2668
2669 The summary report may be suppressed with the optional `report`
2670 parameter:
2671
2672 >>> doctest.testfile('test_doctest.txt', report=False)
2673 ... # doctest: +ELLIPSIS
2674 **********************************************************************
2675 File "...", line 6, in test_doctest.txt
2676 Failed example:
2677 favorite_color
2678 Exception raised:
2679 ...
2680 NameError: name 'favorite_color' is not defined
2681 TestResults(failed=1, attempted=2)
2682 >>> doctest.master = None # Reset master.
2683
2684 The optional keyword argument `raise_on_error` can be used to raise an
2685 exception on the first error (which may be useful for postmortem
2686 debugging):
2687
2688 >>> doctest.testfile('test_doctest.txt', raise_on_error=True)
2689 ... # doctest: +ELLIPSIS
2690 Traceback (most recent call last):
2691 doctest.UnexpectedException: ...
2692 >>> doctest.master = None # Reset master.
2693
2694 If the tests contain non-ASCII characters, the tests might fail, since
2695 it's unknown which encoding is used. The encoding can be specified
2696 using the optional keyword argument `encoding`:
2697
2698 >>> doctest.testfile('test_doctest4.txt', encoding='latin-1') # doctest: +ELLIPSIS
2699 **********************************************************************
2700 File "...", line 7, in test_doctest4.txt
2701 Failed example:
2702 '...'
2703 Expected:
2704 'f\xf6\xf6'
2705 Got:
2706 'f\xc3\xb6\xc3\xb6'
2707 **********************************************************************
2708 ...
2709 **********************************************************************
2710 1 items had failures:
2711 2 of 2 in test_doctest4.txt
2712 ***Test Failed*** 2 failures.
2713 TestResults(failed=2, attempted=2)
2714 >>> doctest.master = None # Reset master.
2715
2716 >>> doctest.testfile('test_doctest4.txt', encoding='utf-8')
2717 TestResults(failed=0, attempted=2)
2718 >>> doctest.master = None # Reset master.
2719
2720 Test the verbose output:
2721
2722 >>> doctest.testfile('test_doctest4.txt', encoding='utf-8', verbose=True)
2723 Trying:
2724 'föö'
2725 Expecting:
2726 'f\xf6\xf6'
2727 ok
2728 Trying:
2729 'bąr'
2730 Expecting:
2731 'b\u0105r'
2732 ok
2733 1 items passed all tests:
2734 2 tests in test_doctest4.txt
2735 2 tests in 1 items.
2736 2 passed and 0 failed.
2737 Test passed.
2738 TestResults(failed=0, attempted=2)
2739 >>> doctest.master = None # Reset master.
2740 >>> sys.argv = save_argv
2741 """
2742
2743 class ESC[4;38;5;81mTestImporter(ESC[4;38;5;149mimportlibESC[4;38;5;149m.ESC[4;38;5;149mabcESC[4;38;5;149m.ESC[4;38;5;149mMetaPathFinder, ESC[4;38;5;149mimportlibESC[4;38;5;149m.ESC[4;38;5;149mabcESC[4;38;5;149m.ESC[4;38;5;149mResourceLoader):
2744
2745 def find_spec(self, fullname, path, target=None):
2746 return importlib.util.spec_from_file_location(fullname, path, loader=self)
2747
2748 def get_data(self, path):
2749 with open(path, mode='rb') as f:
2750 return f.read()
2751
2752 class ESC[4;38;5;81mTestHook:
2753
2754 def __init__(self, pathdir):
2755 self.sys_path = sys.path[:]
2756 self.meta_path = sys.meta_path[:]
2757 self.path_hooks = sys.path_hooks[:]
2758 sys.path.append(pathdir)
2759 sys.path_importer_cache.clear()
2760 self.modules_before = sys.modules.copy()
2761 self.importer = TestImporter()
2762 sys.meta_path.append(self.importer)
2763
2764 def remove(self):
2765 sys.path[:] = self.sys_path
2766 sys.meta_path[:] = self.meta_path
2767 sys.path_hooks[:] = self.path_hooks
2768 sys.path_importer_cache.clear()
2769 sys.modules.clear()
2770 sys.modules.update(self.modules_before)
2771
2772
2773 @contextlib.contextmanager
2774 def test_hook(pathdir):
2775 hook = TestHook(pathdir)
2776 try:
2777 yield hook
2778 finally:
2779 hook.remove()
2780
2781
2782 def test_lineendings(): r"""
2783 *nix systems use \n line endings, while Windows systems use \r\n, and
2784 old Mac systems used \r, which Python still recognizes as a line ending. Python
2785 handles this using universal newline mode for reading files. Let's make
2786 sure doctest does so (issue 8473) by creating temporary test files using each
2787 of the three line disciplines. At least one will not match either the universal
2788 newline \n or os.linesep for the platform the test is run on.
2789
2790 Windows line endings first:
2791
2792 >>> import tempfile, os
2793 >>> fn = tempfile.mktemp()
2794 >>> with open(fn, 'wb') as f:
2795 ... f.write(b'Test:\r\n\r\n >>> x = 1 + 1\r\n\r\nDone.\r\n')
2796 35
2797 >>> doctest.testfile(fn, module_relative=False, verbose=False)
2798 TestResults(failed=0, attempted=1)
2799 >>> os.remove(fn)
2800
2801 And now *nix line endings:
2802
2803 >>> fn = tempfile.mktemp()
2804 >>> with open(fn, 'wb') as f:
2805 ... f.write(b'Test:\n\n >>> x = 1 + 1\n\nDone.\n')
2806 30
2807 >>> doctest.testfile(fn, module_relative=False, verbose=False)
2808 TestResults(failed=0, attempted=1)
2809 >>> os.remove(fn)
2810
2811 And finally old Mac line endings:
2812
2813 >>> fn = tempfile.mktemp()
2814 >>> with open(fn, 'wb') as f:
2815 ... f.write(b'Test:\r\r >>> x = 1 + 1\r\rDone.\r')
2816 30
2817 >>> doctest.testfile(fn, module_relative=False, verbose=False)
2818 TestResults(failed=0, attempted=1)
2819 >>> os.remove(fn)
2820
2821 Now we test with a package loader that has a get_data method, since that
2822 bypasses the standard universal newline handling so doctest has to do the
2823 newline conversion itself; let's make sure it does so correctly (issue 1812).
2824 We'll write a file inside the package that has all three kinds of line endings
2825 in it, and use a package hook to install a custom loader; on any platform,
2826 at least one of the line endings will raise a ValueError for inconsistent
2827 whitespace if doctest does not correctly do the newline conversion.
2828
2829 >>> dn = tempfile.mkdtemp()
2830 >>> pkg = os.path.join(dn, "doctest_testpkg")
2831 >>> os.mkdir(pkg)
2832 >>> os_helper.create_empty_file(os.path.join(pkg, "__init__.py"))
2833 >>> fn = os.path.join(pkg, "doctest_testfile.txt")
2834 >>> with open(fn, 'wb') as f:
2835 ... f.write(
2836 ... b'Test:\r\n\r\n'
2837 ... b' >>> x = 1 + 1\r\n\r\n'
2838 ... b'Done.\r\n'
2839 ... b'Test:\n\n'
2840 ... b' >>> x = 1 + 1\n\n'
2841 ... b'Done.\n'
2842 ... b'Test:\r\r'
2843 ... b' >>> x = 1 + 1\r\r'
2844 ... b'Done.\r'
2845 ... )
2846 95
2847 >>> with test_hook(dn):
2848 ... doctest.testfile("doctest_testfile.txt", package="doctest_testpkg", verbose=False)
2849 TestResults(failed=0, attempted=3)
2850 >>> shutil.rmtree(dn)
2851
2852 """
2853
2854 def test_testmod(): r"""
2855 Tests for the testmod function. More might be useful, but for now we're just
2856 testing the case raised by Issue 6195, where trying to doctest a C module would
2857 fail with a UnicodeDecodeError because doctest tried to read the "source" lines
2858 out of the binary module.
2859
2860 >>> import unicodedata
2861 >>> doctest.testmod(unicodedata, verbose=False)
2862 TestResults(failed=0, attempted=0)
2863 """
2864
2865 try:
2866 os.fsencode("foo-bär@baz.py")
2867 supports_unicode = True
2868 except UnicodeEncodeError:
2869 # Skip the test: the filesystem encoding is unable to encode the filename
2870 supports_unicode = False
2871
2872 if supports_unicode:
2873 def test_unicode(): """
2874 Check doctest with a non-ascii filename:
2875
2876 >>> doc = '''
2877 ... >>> raise Exception('clé')
2878 ... '''
2879 ...
2880 >>> parser = doctest.DocTestParser()
2881 >>> test = parser.get_doctest(doc, {}, "foo-bär@baz", "foo-bär@baz.py", 0)
2882 >>> test
2883 <DocTest foo-bär@baz from foo-bär@baz.py:0 (1 example)>
2884 >>> runner = doctest.DocTestRunner(verbose=False)
2885 >>> runner.run(test) # doctest: +ELLIPSIS
2886 **********************************************************************
2887 File "foo-bär@baz.py", line 2, in foo-bär@baz
2888 Failed example:
2889 raise Exception('clé')
2890 Exception raised:
2891 Traceback (most recent call last):
2892 File ...
2893 exec(compile(example.source, filename, "single",
2894 File "<doctest foo-bär@baz[0]>", line 1, in <module>
2895 raise Exception('clé')
2896 Exception: clé
2897 TestResults(failed=1, attempted=1)
2898 """
2899
2900 def test_CLI(): r"""
2901 The doctest module can be used to run doctests against an arbitrary file.
2902 These tests test this CLI functionality.
2903
2904 We'll use the support module's script_helpers for this, and write a test files
2905 to a temp dir to run the command against. Due to a current limitation in
2906 script_helpers, though, we need a little utility function to turn the returned
2907 output into something we can doctest against:
2908
2909 >>> def normalize(s):
2910 ... return '\n'.join(s.decode().splitlines())
2911
2912 With those preliminaries out of the way, we'll start with a file with two
2913 simple tests and no errors. We'll run both the unadorned doctest command, and
2914 the verbose version, and then check the output:
2915
2916 >>> from test.support import script_helper
2917 >>> from test.support.os_helper import temp_dir
2918 >>> with temp_dir() as tmpdir:
2919 ... fn = os.path.join(tmpdir, 'myfile.doc')
2920 ... with open(fn, 'w', encoding='utf-8') as f:
2921 ... _ = f.write('This is a very simple test file.\n')
2922 ... _ = f.write(' >>> 1 + 1\n')
2923 ... _ = f.write(' 2\n')
2924 ... _ = f.write(' >>> "a"\n')
2925 ... _ = f.write(" 'a'\n")
2926 ... _ = f.write('\n')
2927 ... _ = f.write('And that is it.\n')
2928 ... rc1, out1, err1 = script_helper.assert_python_ok(
2929 ... '-m', 'doctest', fn)
2930 ... rc2, out2, err2 = script_helper.assert_python_ok(
2931 ... '-m', 'doctest', '-v', fn)
2932
2933 With no arguments and passing tests, we should get no output:
2934
2935 >>> rc1, out1, err1
2936 (0, b'', b'')
2937
2938 With the verbose flag, we should see the test output, but no error output:
2939
2940 >>> rc2, err2
2941 (0, b'')
2942 >>> print(normalize(out2))
2943 Trying:
2944 1 + 1
2945 Expecting:
2946 2
2947 ok
2948 Trying:
2949 "a"
2950 Expecting:
2951 'a'
2952 ok
2953 1 items passed all tests:
2954 2 tests in myfile.doc
2955 2 tests in 1 items.
2956 2 passed and 0 failed.
2957 Test passed.
2958
2959 Now we'll write a couple files, one with three tests, the other a python module
2960 with two tests, both of the files having "errors" in the tests that can be made
2961 non-errors by applying the appropriate doctest options to the run (ELLIPSIS in
2962 the first file, NORMALIZE_WHITESPACE in the second). This combination will
2963 allow thoroughly testing the -f and -o flags, as well as the doctest command's
2964 ability to process more than one file on the command line and, since the second
2965 file ends in '.py', its handling of python module files (as opposed to straight
2966 text files).
2967
2968 >>> from test.support import script_helper
2969 >>> from test.support.os_helper import temp_dir
2970 >>> with temp_dir() as tmpdir:
2971 ... fn = os.path.join(tmpdir, 'myfile.doc')
2972 ... with open(fn, 'w', encoding="utf-8") as f:
2973 ... _ = f.write('This is another simple test file.\n')
2974 ... _ = f.write(' >>> 1 + 1\n')
2975 ... _ = f.write(' 2\n')
2976 ... _ = f.write(' >>> "abcdef"\n')
2977 ... _ = f.write(" 'a...f'\n")
2978 ... _ = f.write(' >>> "ajkml"\n')
2979 ... _ = f.write(" 'a...l'\n")
2980 ... _ = f.write('\n')
2981 ... _ = f.write('And that is it.\n')
2982 ... fn2 = os.path.join(tmpdir, 'myfile2.py')
2983 ... with open(fn2, 'w', encoding='utf-8') as f:
2984 ... _ = f.write('def test_func():\n')
2985 ... _ = f.write(' \"\"\"\n')
2986 ... _ = f.write(' This is simple python test function.\n')
2987 ... _ = f.write(' >>> 1 + 1\n')
2988 ... _ = f.write(' 2\n')
2989 ... _ = f.write(' >>> "abc def"\n')
2990 ... _ = f.write(" 'abc def'\n")
2991 ... _ = f.write("\n")
2992 ... _ = f.write(' \"\"\"\n')
2993 ... rc1, out1, err1 = script_helper.assert_python_failure(
2994 ... '-m', 'doctest', fn, fn2)
2995 ... rc2, out2, err2 = script_helper.assert_python_ok(
2996 ... '-m', 'doctest', '-o', 'ELLIPSIS', fn)
2997 ... rc3, out3, err3 = script_helper.assert_python_ok(
2998 ... '-m', 'doctest', '-o', 'ELLIPSIS',
2999 ... '-o', 'NORMALIZE_WHITESPACE', fn, fn2)
3000 ... rc4, out4, err4 = script_helper.assert_python_failure(
3001 ... '-m', 'doctest', '-f', fn, fn2)
3002 ... rc5, out5, err5 = script_helper.assert_python_ok(
3003 ... '-m', 'doctest', '-v', '-o', 'ELLIPSIS',
3004 ... '-o', 'NORMALIZE_WHITESPACE', fn, fn2)
3005
3006 Our first test run will show the errors from the first file (doctest stops if a
3007 file has errors). Note that doctest test-run error output appears on stdout,
3008 not stderr:
3009
3010 >>> rc1, err1
3011 (1, b'')
3012 >>> print(normalize(out1)) # doctest: +ELLIPSIS
3013 **********************************************************************
3014 File "...myfile.doc", line 4, in myfile.doc
3015 Failed example:
3016 "abcdef"
3017 Expected:
3018 'a...f'
3019 Got:
3020 'abcdef'
3021 **********************************************************************
3022 File "...myfile.doc", line 6, in myfile.doc
3023 Failed example:
3024 "ajkml"
3025 Expected:
3026 'a...l'
3027 Got:
3028 'ajkml'
3029 **********************************************************************
3030 1 items had failures:
3031 2 of 3 in myfile.doc
3032 ***Test Failed*** 2 failures.
3033
3034 With -o ELLIPSIS specified, the second run, against just the first file, should
3035 produce no errors, and with -o NORMALIZE_WHITESPACE also specified, neither
3036 should the third, which ran against both files:
3037
3038 >>> rc2, out2, err2
3039 (0, b'', b'')
3040 >>> rc3, out3, err3
3041 (0, b'', b'')
3042
3043 The fourth run uses FAIL_FAST, so we should see only one error:
3044
3045 >>> rc4, err4
3046 (1, b'')
3047 >>> print(normalize(out4)) # doctest: +ELLIPSIS
3048 **********************************************************************
3049 File "...myfile.doc", line 4, in myfile.doc
3050 Failed example:
3051 "abcdef"
3052 Expected:
3053 'a...f'
3054 Got:
3055 'abcdef'
3056 **********************************************************************
3057 1 items had failures:
3058 1 of 2 in myfile.doc
3059 ***Test Failed*** 1 failures.
3060
3061 The fifth test uses verbose with the two options, so we should get verbose
3062 success output for the tests in both files:
3063
3064 >>> rc5, err5
3065 (0, b'')
3066 >>> print(normalize(out5))
3067 Trying:
3068 1 + 1
3069 Expecting:
3070 2
3071 ok
3072 Trying:
3073 "abcdef"
3074 Expecting:
3075 'a...f'
3076 ok
3077 Trying:
3078 "ajkml"
3079 Expecting:
3080 'a...l'
3081 ok
3082 1 items passed all tests:
3083 3 tests in myfile.doc
3084 3 tests in 1 items.
3085 3 passed and 0 failed.
3086 Test passed.
3087 Trying:
3088 1 + 1
3089 Expecting:
3090 2
3091 ok
3092 Trying:
3093 "abc def"
3094 Expecting:
3095 'abc def'
3096 ok
3097 1 items had no tests:
3098 myfile2
3099 1 items passed all tests:
3100 2 tests in myfile2.test_func
3101 2 tests in 2 items.
3102 2 passed and 0 failed.
3103 Test passed.
3104
3105 We should also check some typical error cases.
3106
3107 Invalid file name:
3108
3109 >>> rc, out, err = script_helper.assert_python_failure(
3110 ... '-m', 'doctest', 'nosuchfile')
3111 >>> rc, out
3112 (1, b'')
3113 >>> # The exact error message changes depending on the platform.
3114 >>> print(normalize(err)) # doctest: +ELLIPSIS
3115 Traceback (most recent call last):
3116 ...
3117 FileNotFoundError: [Errno ...] ...nosuchfile...
3118
3119 Invalid doctest option:
3120
3121 >>> rc, out, err = script_helper.assert_python_failure(
3122 ... '-m', 'doctest', '-o', 'nosuchoption')
3123 >>> rc, out
3124 (2, b'')
3125 >>> print(normalize(err)) # doctest: +ELLIPSIS
3126 usage...invalid...nosuchoption...
3127
3128 """
3129
3130 def test_no_trailing_whitespace_stripping():
3131 r"""
3132 The fancy reports had a bug for a long time where any trailing whitespace on
3133 the reported diff lines was stripped, making it impossible to see the
3134 differences in line reported as different that differed only in the amount of
3135 trailing whitespace. The whitespace still isn't particularly visible unless
3136 you use NDIFF, but at least it is now there to be found.
3137
3138 *NOTE*: This snippet was intentionally put inside a raw string to get rid of
3139 leading whitespace error in executing the example below
3140
3141 >>> def f(x):
3142 ... r'''
3143 ... >>> print('\n'.join(['a ', 'b']))
3144 ... a
3145 ... b
3146 ... '''
3147 """
3148 """
3149 *NOTE*: These doctest are not placed in raw string to depict the trailing whitespace
3150 using `\x20`
3151
3152 >>> test = doctest.DocTestFinder().find(f)[0]
3153 >>> flags = doctest.REPORT_NDIFF
3154 >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
3155 ... # doctest: +ELLIPSIS
3156 **********************************************************************
3157 File ..., line 3, in f
3158 Failed example:
3159 print('\n'.join(['a ', 'b']))
3160 Differences (ndiff with -expected +actual):
3161 - a
3162 + a
3163 b
3164 TestResults(failed=1, attempted=1)
3165
3166 *NOTE*: `\x20` is for checking the trailing whitespace on the +a line above.
3167 We cannot use actual spaces there, as a commit hook prevents from committing
3168 patches that contain trailing whitespace. More info on Issue 24746.
3169 """
3170
3171
3172 def test_run_doctestsuite_multiple_times():
3173 """
3174 It was not possible to run the same DocTestSuite multiple times
3175 http://bugs.python.org/issue2604
3176 http://bugs.python.org/issue9736
3177
3178 >>> import unittest
3179 >>> import test.sample_doctest
3180 >>> suite = doctest.DocTestSuite(test.sample_doctest)
3181 >>> suite.run(unittest.TestResult())
3182 <unittest.result.TestResult run=9 errors=0 failures=4>
3183 >>> suite.run(unittest.TestResult())
3184 <unittest.result.TestResult run=9 errors=0 failures=4>
3185 """
3186
3187
3188 def test_exception_with_note(note):
3189 """
3190 >>> test_exception_with_note('Note')
3191 Traceback (most recent call last):
3192 ...
3193 ValueError: Text
3194 Note
3195
3196 >>> test_exception_with_note('Note') # doctest: +IGNORE_EXCEPTION_DETAIL
3197 Traceback (most recent call last):
3198 ...
3199 ValueError: Text
3200 Note
3201
3202 >>> test_exception_with_note('''Note
3203 ... multiline
3204 ... example''')
3205 Traceback (most recent call last):
3206 ValueError: Text
3207 Note
3208 multiline
3209 example
3210
3211 Different note will fail the test:
3212
3213 >>> def f(x):
3214 ... r'''
3215 ... >>> exc = ValueError('message')
3216 ... >>> exc.add_note('note')
3217 ... >>> raise exc
3218 ... Traceback (most recent call last):
3219 ... ValueError: message
3220 ... wrong note
3221 ... '''
3222 >>> test = doctest.DocTestFinder().find(f)[0]
3223 >>> doctest.DocTestRunner(verbose=False).run(test)
3224 ... # doctest: +ELLIPSIS
3225 **********************************************************************
3226 File "...", line 5, in f
3227 Failed example:
3228 raise exc
3229 Expected:
3230 Traceback (most recent call last):
3231 ValueError: message
3232 wrong note
3233 Got:
3234 Traceback (most recent call last):
3235 ...
3236 ValueError: message
3237 note
3238 TestResults(failed=1, attempted=...)
3239 """
3240 exc = ValueError('Text')
3241 exc.add_note(note)
3242 raise exc
3243
3244
3245 def test_exception_with_multiple_notes():
3246 """
3247 >>> test_exception_with_multiple_notes()
3248 Traceback (most recent call last):
3249 ...
3250 ValueError: Text
3251 One
3252 Two
3253 """
3254 exc = ValueError('Text')
3255 exc.add_note('One')
3256 exc.add_note('Two')
3257 raise exc
3258
3259
3260 def test_syntax_error_with_note(cls, multiline=False):
3261 """
3262 >>> test_syntax_error_with_note(SyntaxError)
3263 Traceback (most recent call last):
3264 ...
3265 SyntaxError: error
3266 Note
3267
3268 >>> test_syntax_error_with_note(SyntaxError)
3269 Traceback (most recent call last):
3270 SyntaxError: error
3271 Note
3272
3273 >>> test_syntax_error_with_note(SyntaxError)
3274 Traceback (most recent call last):
3275 ...
3276 File "x.py", line 23
3277 bad syntax
3278 SyntaxError: error
3279 Note
3280
3281 >>> test_syntax_error_with_note(IndentationError)
3282 Traceback (most recent call last):
3283 ...
3284 IndentationError: error
3285 Note
3286
3287 >>> test_syntax_error_with_note(TabError, multiline=True)
3288 Traceback (most recent call last):
3289 ...
3290 TabError: error
3291 Note
3292 Line
3293 """
3294 exc = cls("error", ("x.py", 23, None, "bad syntax"))
3295 exc.add_note('Note\nLine' if multiline else 'Note')
3296 raise exc
3297
3298
3299 def test_syntax_error_subclass_from_stdlib():
3300 """
3301 `ParseError` is a subclass of `SyntaxError`, but it is not a builtin:
3302
3303 >>> test_syntax_error_subclass_from_stdlib()
3304 Traceback (most recent call last):
3305 ...
3306 xml.etree.ElementTree.ParseError: error
3307 error
3308 Note
3309 Line
3310 """
3311 from xml.etree.ElementTree import ParseError
3312 exc = ParseError("error\nerror")
3313 exc.add_note('Note\nLine')
3314 raise exc
3315
3316
3317 def test_syntax_error_with_incorrect_expected_note():
3318 """
3319 >>> def f(x):
3320 ... r'''
3321 ... >>> exc = SyntaxError("error", ("x.py", 23, None, "bad syntax"))
3322 ... >>> exc.add_note('note1')
3323 ... >>> exc.add_note('note2')
3324 ... >>> raise exc
3325 ... Traceback (most recent call last):
3326 ... SyntaxError: error
3327 ... wrong note
3328 ... '''
3329 >>> test = doctest.DocTestFinder().find(f)[0]
3330 >>> doctest.DocTestRunner(verbose=False).run(test)
3331 ... # doctest: +ELLIPSIS
3332 **********************************************************************
3333 File "...", line 6, in f
3334 Failed example:
3335 raise exc
3336 Expected:
3337 Traceback (most recent call last):
3338 SyntaxError: error
3339 wrong note
3340 Got:
3341 Traceback (most recent call last):
3342 ...
3343 SyntaxError: error
3344 note1
3345 note2
3346 TestResults(failed=1, attempted=...)
3347 """
3348
3349
3350 def load_tests(loader, tests, pattern):
3351 tests.addTest(doctest.DocTestSuite(doctest))
3352 tests.addTest(doctest.DocTestSuite())
3353 return tests
3354
3355
3356 if __name__ == '__main__':
3357 unittest.main(module='test.test_doctest')