Debian Codegraph @

Lib/test/test_doctest/test_doctest.py

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