2
# Released to the public domain 16-Jan-2001, by Tim Peters (tim@python.org).
3
# Major enhancements and refactoring by:
7
# Provided as-is; use at your own risk; no warranty; no promises; enjoy!
9
r"""Module doctest -- a framework for running examples in docstrings.
11
In simplest use, end each module M to be tested with:
17
if __name__ == "__main__":
20
Then running the module as a script will cause the examples in the
21
docstrings to get executed and verified:
25
This won't display anything unless an example fails, in which case the
26
failing example(s) and the cause(s) of the failure(s) are printed to stdout
27
(why not stderr? because stderr is a lame hack <0.2 wink>), and the final
28
line of output is "Test failed.".
30
Run it with the -v switch instead:
34
and a detailed report of all examples tried is printed to stdout, along
35
with assorted summaries at the end.
37
You can force verbose mode by passing "verbose=True" to testmod, or prohibit
38
it by passing "verbose=False". In either of those cases, sys.argv is not
41
There are a variety of other ways to run doctests, including integration
42
with the unittest framework, and support for running non-Python text
43
files containing doctests. There are also many ways to override parts
44
of doctest's default behaviors. See the Library Reference Manual for
48
__docformat__ = 'reStructuredText en'
52
'register_optionflag',
53
'DONT_ACCEPT_TRUE_FOR_1',
54
'DONT_ACCEPT_BLANKLINE',
55
'NORMALIZE_WHITESPACE',
58
'IGNORE_EXCEPTION_DETAIL',
63
'REPORT_ONLY_FIRST_FAILURE',
65
# 1. Utility Functions
66
# 2. Example & DocTest
77
'UnexpectedException',
82
'run_docstring_examples',
86
'set_unittest_reportflags',
87
# 8. Debugging Support
88
'script_from_examples',
96
import sys, traceback, inspect, linecache, os, re
97
import unittest, difflib, pdb, tempfile
99
from io import StringIO
100
from collections import namedtuple
102
TestResults = namedtuple('TestResults', 'failed attempted')
104
# There are 4 basic classes:
105
# - Example: a <source, want> pair, plus an intra-docstring line number.
106
# - DocTest: a collection of examples, parsed from a docstring, plus
107
# info about where the docstring came from (name, filename, lineno).
108
# - DocTestFinder: extracts DocTests from a given object's docstring and
109
# its contained objects' docstrings.
110
# - DocTestRunner: runs DocTest cases, and accumulates statistics.
112
# So the basic picture is:
115
# +------+ +---------+ +-------+
116
# |object| --DocTestFinder-> | DocTest | --DocTestRunner-> |results|
117
# +------+ +---------+ +-------+
125
OPTIONFLAGS_BY_NAME = {}
126
def register_optionflag(name):
127
# Create a new flag unless `name` is already known.
128
return OPTIONFLAGS_BY_NAME.setdefault(name, 1 << len(OPTIONFLAGS_BY_NAME))
130
DONT_ACCEPT_TRUE_FOR_1 = register_optionflag('DONT_ACCEPT_TRUE_FOR_1')
131
DONT_ACCEPT_BLANKLINE = register_optionflag('DONT_ACCEPT_BLANKLINE')
132
NORMALIZE_WHITESPACE = register_optionflag('NORMALIZE_WHITESPACE')
133
ELLIPSIS = register_optionflag('ELLIPSIS')
134
SKIP = register_optionflag('SKIP')
135
IGNORE_EXCEPTION_DETAIL = register_optionflag('IGNORE_EXCEPTION_DETAIL')
137
COMPARISON_FLAGS = (DONT_ACCEPT_TRUE_FOR_1 |
138
DONT_ACCEPT_BLANKLINE |
139
NORMALIZE_WHITESPACE |
142
IGNORE_EXCEPTION_DETAIL)
144
REPORT_UDIFF = register_optionflag('REPORT_UDIFF')
145
REPORT_CDIFF = register_optionflag('REPORT_CDIFF')
146
REPORT_NDIFF = register_optionflag('REPORT_NDIFF')
147
REPORT_ONLY_FIRST_FAILURE = register_optionflag('REPORT_ONLY_FIRST_FAILURE')
149
REPORTING_FLAGS = (REPORT_UDIFF |
152
REPORT_ONLY_FIRST_FAILURE)
154
# Special string markers for use in `want` strings:
155
BLANKLINE_MARKER = '<BLANKLINE>'
156
ELLIPSIS_MARKER = '...'
158
######################################################################
160
######################################################################
161
# 1. Utility Functions
162
# 2. Example & DocTest -- store test cases
163
# 3. DocTest Parser -- extracts examples from strings
164
# 4. DocTest Finder -- extracts test cases from objects
165
# 5. DocTest Runner -- runs test cases
166
# 6. Test Functions -- convenient wrappers for testing
167
# 7. Unittest Support
168
# 8. Debugging Support
171
######################################################################
172
## 1. Utility Functions
173
######################################################################
175
def _extract_future_flags(globs):
177
Return the compiler-flags associated with the future features that
178
have been imported into the given namespace (globs).
181
for fname in __future__.all_feature_names:
182
feature = globs.get(fname, None)
183
if feature is getattr(__future__, fname):
184
flags |= feature.compiler_flag
187
def _normalize_module(module, depth=2):
189
Return the module specified by `module`. In particular:
190
- If `module` is a module, then return module.
191
- If `module` is a string, then import and return the
192
module with that name.
193
- If `module` is None, then return the calling module.
194
The calling module is assumed to be the module of
195
the stack frame at the given depth in the call stack.
197
if inspect.ismodule(module):
199
elif isinstance(module, str):
200
return __import__(module, globals(), locals(), ["*"])
202
return sys.modules[sys._getframe(depth).f_globals['__name__']]
204
raise TypeError("Expected a module, string, or None")
206
def _load_testfile(filename, package, module_relative, encoding):
208
package = _normalize_module(package, 3)
209
filename = _module_relative_path(package, filename)
210
if hasattr(package, '__loader__'):
211
if hasattr(package.__loader__, 'get_data'):
212
file_contents = package.__loader__.get_data(filename)
213
file_contents = file_contents.decode(encoding)
214
# get_data() opens files as 'rb', so one must do the equivalent
215
# conversion as universal newlines would do.
216
return file_contents.replace(os.linesep, '\n'), filename
217
return open(filename, encoding=encoding).read(), filename
219
def _indent(s, indent=4):
221
Add the given number of space characters to the beginning every
222
non-blank line in `s`, and return the result.
224
# This regexp matches the start of non-blank lines:
225
return re.sub('(?m)^(?!$)', indent*' ', s)
227
def _exception_traceback(exc_info):
229
Return a string containing a traceback message for the given
230
exc_info tuple (as returned by sys.exc_info()).
232
# Get a traceback message.
234
exc_type, exc_val, exc_tb = exc_info
235
traceback.print_exception(exc_type, exc_val, exc_tb, file=excout)
236
return excout.getvalue()
238
# Override some StringIO methods.
239
class _SpoofOut(StringIO):
241
result = StringIO.getvalue(self)
242
# If anything at all was written, make sure there's a trailing
243
# newline. There's no way for the expected output to indicate
244
# that a trailing newline is missing.
245
if result and not result.endswith("\n"):
249
def truncate(self, size=None):
250
StringIO.truncate(self, size)
252
# Worst-case linear-time ellipsis matching.
253
def _ellipsis_match(want, got):
255
Essentially the only subtle case:
256
>>> _ellipsis_match('aa...aa', 'aaa')
259
if ELLIPSIS_MARKER not in want:
262
# Find "the real" strings.
263
ws = want.split(ELLIPSIS_MARKER)
266
# Deal with exact matches possibly needed at one or both ends.
267
startpos, endpos = 0, len(got)
269
if w: # starts with exact match
270
if got.startswith(w):
276
if w: # ends with exact match
283
if startpos > endpos:
284
# Exact end matches required more characters than we have, as in
285
# _ellipsis_match('aa...aa', 'aaa')
288
# For the rest, we only need to find the leftmost non-overlapping
289
# match for each piece. If there's no overall match that way alone,
290
# there's no overall match period.
292
# w may be '' at times, if there are consecutive ellipses, or
293
# due to an ellipsis at the start or end of `want`. That's OK.
294
# Search for an empty string succeeds, and doesn't change startpos.
295
startpos = got.find(w, startpos, endpos)
302
def _comment_line(line):
303
"Return a commented form of the given line"
310
class _OutputRedirectingPdb(pdb.Pdb):
312
A specialized version of the python debugger that redirects stdout
313
to a given stream when interacting with the user. Stdout is *not*
314
redirected when traced code is executed.
316
def __init__(self, out):
318
self.__debugger_used = False
319
pdb.Pdb.__init__(self, stdout=out)
321
def set_trace(self, frame=None):
322
self.__debugger_used = True
324
frame = sys._getframe().f_back
325
pdb.Pdb.set_trace(self, frame)
327
def set_continue(self):
328
# Calling set_continue unconditionally would break unit test
329
# coverage reporting, as Bdb.set_continue calls sys.settrace(None).
330
if self.__debugger_used:
331
pdb.Pdb.set_continue(self)
333
def trace_dispatch(self, *args):
334
# Redirect stdout to the given stream.
335
save_stdout = sys.stdout
336
sys.stdout = self.__out
337
# Call Pdb's trace dispatch method.
339
return pdb.Pdb.trace_dispatch(self, *args)
341
sys.stdout = save_stdout
343
# [XX] Normalize with respect to os.path.pardir?
344
def _module_relative_path(module, path):
345
if not inspect.ismodule(module):
346
raise TypeError('Expected a module: %r' % module)
347
if path.startswith('/'):
348
raise ValueError('Module-relative files may not have absolute paths')
350
# Find the base directory for the path.
351
if hasattr(module, '__file__'):
352
# A normal module/package
353
basedir = os.path.split(module.__file__)[0]
354
elif module.__name__ == '__main__':
355
# An interactive session.
356
if len(sys.argv)>0 and sys.argv[0] != '':
357
basedir = os.path.split(sys.argv[0])[0]
361
# A module w/o __file__ (this includes builtins)
362
raise ValueError("Can't resolve paths relative to the module " +
363
module + " (it has no __file__)")
365
# Combine the base directory and the path.
366
return os.path.join(basedir, *(path.split('/')))
368
######################################################################
369
## 2. Example & DocTest
370
######################################################################
371
## - An "example" is a <source, want> pair, where "source" is a
372
## fragment of source code, and "want" is the expected output for
373
## "source." The Example class also includes information about
374
## where the example was extracted from.
376
## - A "doctest" is a collection of examples, typically extracted from
377
## a string (such as an object's docstring). The DocTest class also
378
## includes information about where the string was extracted from.
382
A single doctest example, consisting of source code and expected
383
output. `Example` defines the following attributes:
385
- source: A single Python statement, always ending with a newline.
386
The constructor adds a newline if needed.
388
- want: The expected output from running the source code (either
389
from stdout, or a traceback in case of exception). `want` ends
390
with a newline unless it's empty, in which case it's an empty
391
string. The constructor adds a newline if needed.
393
- exc_msg: The exception message generated by the example, if
394
the example is expected to generate an exception; or `None` if
395
it is not expected to generate an exception. This exception
396
message is compared against the return value of
397
`traceback.format_exception_only()`. `exc_msg` ends with a
398
newline unless it's `None`. The constructor adds a newline
401
- lineno: The line number within the DocTest string containing
402
this Example where the Example begins. This line number is
403
zero-based, with respect to the beginning of the DocTest.
405
- indent: The example's indentation in the DocTest string.
406
I.e., the number of space characters that preceed the
407
example's first prompt.
409
- options: A dictionary mapping from option flags to True or
410
False, which is used to override default options for this
411
example. Any option flags not contained in this dictionary
412
are left at their default value (as specified by the
413
DocTestRunner's optionflags). By default, no options are set.
415
def __init__(self, source, want, exc_msg=None, lineno=0, indent=0,
418
if not source.endswith('\n'):
420
if want and not want.endswith('\n'):
422
if exc_msg is not None and not exc_msg.endswith('\n'):
429
if options is None: options = {}
430
self.options = options
431
self.exc_msg = exc_msg
435
A collection of doctest examples that should be run in a single
436
namespace. Each `DocTest` defines the following attributes:
438
- examples: the list of examples.
440
- globs: The namespace (aka globals) that the examples should
443
- name: A name identifying the DocTest (typically, the name of
444
the object whose docstring this DocTest was extracted from).
446
- filename: The name of the file that this DocTest was extracted
447
from, or `None` if the filename is unknown.
449
- lineno: The line number within filename where this DocTest
450
begins, or `None` if the line number is unavailable. This
451
line number is zero-based, with respect to the beginning of
454
- docstring: The string that the examples were extracted from,
455
or `None` if the string is unavailable.
457
def __init__(self, examples, globs, name, filename, lineno, docstring):
459
Create a new DocTest containing the given examples. The
460
DocTest's globals are initialized with a copy of `globs`.
462
assert not isinstance(examples, str), \
463
"DocTest no longer accepts str; use DocTestParser instead"
464
self.examples = examples
465
self.docstring = docstring
466
self.globs = globs.copy()
468
self.filename = filename
472
if len(self.examples) == 0:
473
examples = 'no examples'
474
elif len(self.examples) == 1:
475
examples = '1 example'
477
examples = '%d examples' % len(self.examples)
478
return ('<DocTest %s from %s:%s (%s)>' %
479
(self.name, self.filename, self.lineno, examples))
482
# This lets us sort tests by name:
483
def __lt__(self, other):
484
if not isinstance(other, DocTest):
485
return NotImplemented
486
return ((self.name, self.filename, self.lineno, id(self))
488
(other.name, other.filename, other.lineno, id(other)))
490
######################################################################
492
######################################################################
496
A class used to parse strings containing doctest examples.
498
# This regular expression is used to find doctest examples in a
499
# string. It defines three groups: `source` is the source code
500
# (including leading indentation and prompts); `indent` is the
501
# indentation of the first (PS1) line of the source code; and
502
# `want` is the expected output (including leading indentation).
503
_EXAMPLE_RE = re.compile(r'''
504
# Source consists of a PS1 line followed by zero or more PS2 lines.
506
(?:^(?P<indent> [ ]*) >>> .*) # PS1 line
507
(?:\n [ ]* \.\.\. .*)*) # PS2 lines
509
# Want consists of any non-blank lines that do not start with PS1.
510
(?P<want> (?:(?![ ]*$) # Not a blank line
511
(?![ ]*>>>) # Not a line starting with PS1
512
.*$\n? # But any other line
514
''', re.MULTILINE | re.VERBOSE)
516
# A regular expression for handling `want` strings that contain
517
# expected exceptions. It divides `want` into three pieces:
518
# - the traceback header line (`hdr`)
519
# - the traceback stack (`stack`)
520
# - the exception message (`msg`), as generated by
521
# traceback.format_exception_only()
522
# `msg` may have multiple lines. We assume/require that the
523
# exception message is the first non-indented line starting with a word
524
# character following the traceback header line.
525
_EXCEPTION_RE = re.compile(r"""
526
# Grab the traceback header. Different versions of Python have
527
# said different things on the first traceback line.
528
^(?P<hdr> Traceback\ \(
529
(?: most\ recent\ call\ last
533
\s* $ # toss trailing whitespace on the header.
534
(?P<stack> .*?) # don't blink: absorb stuff until...
535
^ (?P<msg> \w+ .*) # a line *starts* with alphanum.
536
""", re.VERBOSE | re.MULTILINE | re.DOTALL)
538
# A callable returning a true value iff its argument is a blank line
539
# or contains a single comment.
540
_IS_BLANK_OR_COMMENT = re.compile(r'^[ ]*(#.*)?$').match
542
def parse(self, string, name='<string>'):
544
Divide the given string into examples and intervening text,
545
and return them as a list of alternating Examples and strings.
546
Line numbers for the Examples are 0-based. The optional
547
argument `name` is a name identifying this string, and is only
548
used for error messages.
550
string = string.expandtabs()
551
# If all lines begin with the same indentation, then strip it.
552
min_indent = self._min_indent(string)
554
string = '\n'.join([l[min_indent:] for l in string.split('\n')])
557
charno, lineno = 0, 0
558
# Find all doctest examples in the string:
559
for m in self._EXAMPLE_RE.finditer(string):
560
# Add the pre-example text to `output`.
561
output.append(string[charno:m.start()])
562
# Update lineno (lines before this example)
563
lineno += string.count('\n', charno, m.start())
564
# Extract info from the regexp match.
565
(source, options, want, exc_msg) = \
566
self._parse_example(m, name, lineno)
567
# Create an Example, and add it to the list.
568
if not self._IS_BLANK_OR_COMMENT(source):
569
output.append( Example(source, want, exc_msg,
571
indent=min_indent+len(m.group('indent')),
573
# Update lineno (lines inside this example)
574
lineno += string.count('\n', m.start(), m.end())
577
# Add any remaining post-example text to `output`.
578
output.append(string[charno:])
581
def get_doctest(self, string, globs, name, filename, lineno):
583
Extract all doctest examples from the given string, and
584
collect them into a `DocTest` object.
586
`globs`, `name`, `filename`, and `lineno` are attributes for
587
the new `DocTest` object. See the documentation for `DocTest`
588
for more information.
590
return DocTest(self.get_examples(string, name), globs,
591
name, filename, lineno, string)
593
def get_examples(self, string, name='<string>'):
595
Extract all doctest examples from the given string, and return
596
them as a list of `Example` objects. Line numbers are
597
0-based, because it's most common in doctests that nothing
598
interesting appears on the same line as opening triple-quote,
599
and so the first interesting line is called \"line 1\" then.
601
The optional argument `name` is a name identifying this
602
string, and is only used for error messages.
604
return [x for x in self.parse(string, name)
605
if isinstance(x, Example)]
607
def _parse_example(self, m, name, lineno):
609
Given a regular expression match from `_EXAMPLE_RE` (`m`),
610
return a pair `(source, want)`, where `source` is the matched
611
example's source code (with prompts and indentation stripped);
612
and `want` is the example's expected output (with indentation
615
`name` is the string's name, and `lineno` is the line number
616
where the example starts; both are used for error messages.
618
# Get the example's indentation level.
619
indent = len(m.group('indent'))
621
# Divide source into lines; check that they're properly
622
# indented; and then strip their indentation & prompts.
623
source_lines = m.group('source').split('\n')
624
self._check_prompt_blank(source_lines, indent, name, lineno)
625
self._check_prefix(source_lines[1:], ' '*indent + '.', name, lineno)
626
source = '\n'.join([sl[indent+4:] for sl in source_lines])
628
# Divide want into lines; check that it's properly indented; and
629
# then strip the indentation. Spaces before the last newline should
630
# be preserved, so plain rstrip() isn't good enough.
631
want = m.group('want')
632
want_lines = want.split('\n')
633
if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]):
634
del want_lines[-1] # forget final newline & spaces after it
635
self._check_prefix(want_lines, ' '*indent, name,
636
lineno + len(source_lines))
637
want = '\n'.join([wl[indent:] for wl in want_lines])
639
# If `want` contains a traceback message, then extract it.
640
m = self._EXCEPTION_RE.match(want)
642
exc_msg = m.group('msg')
646
# Extract options from the source.
647
options = self._find_options(source, name, lineno)
649
return source, options, want, exc_msg
651
# This regular expression looks for option directives in the
652
# source code of an example. Option directives are comments
653
# starting with "doctest:". Warning: this may give false
654
# positives for string-literals that contain the string
655
# "#doctest:". Eliminating these false positives would require
656
# actually parsing the string; but we limit them by ignoring any
657
# line containing "#doctest:" that is *followed* by a quote mark.
658
_OPTION_DIRECTIVE_RE = re.compile(r'#\s*doctest:\s*([^\n\'"]*)$',
661
def _find_options(self, source, name, lineno):
663
Return a dictionary containing option overrides extracted from
664
option directives in the given source string.
666
`name` is the string's name, and `lineno` is the line number
667
where the example starts; both are used for error messages.
670
# (note: with the current regexp, this will match at most once:)
671
for m in self._OPTION_DIRECTIVE_RE.finditer(source):
672
option_strings = m.group(1).replace(',', ' ').split()
673
for option in option_strings:
674
if (option[0] not in '+-' or
675
option[1:] not in OPTIONFLAGS_BY_NAME):
676
raise ValueError('line %r of the doctest for %s '
677
'has an invalid option: %r' %
678
(lineno+1, name, option))
679
flag = OPTIONFLAGS_BY_NAME[option[1:]]
680
options[flag] = (option[0] == '+')
681
if options and self._IS_BLANK_OR_COMMENT(source):
682
raise ValueError('line %r of the doctest for %s has an option '
683
'directive on a line with no example: %r' %
684
(lineno, name, source))
687
# This regular expression finds the indentation of every non-blank
689
_INDENT_RE = re.compile('^([ ]*)(?=\S)', re.MULTILINE)
691
def _min_indent(self, s):
692
"Return the minimum indentation of any non-blank line in `s`"
693
indents = [len(indent) for indent in self._INDENT_RE.findall(s)]
699
def _check_prompt_blank(self, lines, indent, name, lineno):
701
Given the lines of a source string (including prompts and
702
leading indentation), check to make sure that every prompt is
703
followed by a space character. If any line is not followed by
704
a space character, then raise ValueError.
706
for i, line in enumerate(lines):
707
if len(line) >= indent+4 and line[indent+3] != ' ':
708
raise ValueError('line %r of the docstring for %s '
709
'lacks blank after %s: %r' %
711
line[indent:indent+3], line))
713
def _check_prefix(self, lines, prefix, name, lineno):
715
Check that every line in the given list starts with the given
716
prefix; if any line does not, then raise a ValueError.
718
for i, line in enumerate(lines):
719
if line and not line.startswith(prefix):
720
raise ValueError('line %r of the docstring for %s has '
721
'inconsistent leading whitespace: %r' %
722
(lineno+i+1, name, line))
725
######################################################################
727
######################################################################
731
A class used to extract the DocTests that are relevant to a given
732
object, from its docstring and the docstrings of its contained
733
objects. Doctests can currently be extracted from the following
734
object types: modules, functions, classes, methods, staticmethods,
735
classmethods, and properties.
738
def __init__(self, verbose=False, parser=DocTestParser(),
739
recurse=True, exclude_empty=True):
741
Create a new doctest finder.
743
The optional argument `parser` specifies a class or
744
function that should be used to create new DocTest objects (or
745
objects that implement the same interface as DocTest). The
746
signature for this factory function should match the signature
747
of the DocTest constructor.
749
If the optional argument `recurse` is false, then `find` will
750
only examine the given object, and not any contained objects.
752
If the optional argument `exclude_empty` is false, then `find`
753
will include tests for objects with empty docstrings.
755
self._parser = parser
756
self._verbose = verbose
757
self._recurse = recurse
758
self._exclude_empty = exclude_empty
760
def find(self, obj, name=None, module=None, globs=None, extraglobs=None):
762
Return a list of the DocTests that are defined by the given
763
object's docstring, or by any of its contained objects'
766
The optional parameter `module` is the module that contains
767
the given object. If the module is not specified or is None, then
768
the test finder will attempt to automatically determine the
769
correct module. The object's module is used:
771
- As a default namespace, if `globs` is not specified.
772
- To prevent the DocTestFinder from extracting DocTests
773
from objects that are imported from other modules.
774
- To find the name of the file containing the object.
775
- To help find the line number of the object within its
778
Contained objects whose module does not match `module` are ignored.
780
If `module` is False, no attempt to find the module will be made.
781
This is obscure, of use mostly in tests: if `module` is False, or
782
is None but cannot be found automatically, then all objects are
783
considered to belong to the (non-existent) module, so all contained
784
objects will (recursively) be searched for doctests.
786
The globals for each DocTest is formed by combining `globs`
787
and `extraglobs` (bindings in `extraglobs` override bindings
788
in `globs`). A new copy of the globals dictionary is created
789
for each DocTest. If `globs` is not specified, then it
790
defaults to the module's `__dict__`, if specified, or {}
791
otherwise. If `extraglobs` is not specified, then it defaults
795
# If name was not specified, then extract it from the object.
797
name = getattr(obj, '__name__', None)
799
raise ValueError("DocTestFinder.find: name must be given "
800
"when obj.__name__ doesn't exist: %r" %
803
# Find the module that contains the given object (if obj is
804
# a module, then module=obj.). Note: this may fail, in which
805
# case module will be None.
809
module = inspect.getmodule(obj)
811
# Read the module's source code. This is used by
812
# DocTestFinder._find_lineno to find the line number for a
813
# given object's docstring.
815
file = inspect.getsourcefile(obj) or inspect.getfile(obj)
816
if module is not None:
817
# Supply the module globals in case the module was
818
# originally loaded via a PEP 302 loader and
819
# file is not a valid filesystem path
820
source_lines = linecache.getlines(file, module.__dict__)
822
# No access to a loader, so assume it's a normal
824
source_lines = linecache.getlines(file)
830
# Initialize globals, and merge in extraglobs.
835
globs = module.__dict__.copy()
838
if extraglobs is not None:
839
globs.update(extraglobs)
840
if '__name__' not in globs:
841
globs['__name__'] = '__main__' # provide a default module name
843
# Recursively expore `obj`, extracting DocTests.
845
self._find(tests, obj, name, module, source_lines, globs, {})
846
# Sort the tests by alpha order of names, for consistency in
847
# verbose-mode output. This was a feature of doctest in Pythons
848
# <= 2.3 that got lost by accident in 2.4. It was repaired in
853
def _from_module(self, module, object):
855
Return true if the given object is defined in the given
860
elif inspect.getmodule(object) is not None:
861
return module is inspect.getmodule(object)
862
elif inspect.isfunction(object):
863
return module.__dict__ is object.__globals__
864
elif inspect.isclass(object):
865
return module.__name__ == object.__module__
866
elif hasattr(object, '__module__'):
867
return module.__name__ == object.__module__
868
elif isinstance(object, property):
869
return True # [XX] no way not be sure.
871
raise ValueError("object must be a class or function")
873
def _find(self, tests, obj, name, module, source_lines, globs, seen):
875
Find tests for the given object and any contained objects, and
879
print('Finding tests in %s' % name)
881
# If we've already processed this object, then ignore it.
886
# Find a test for this object, and add it to the list of tests.
887
test = self._get_test(obj, name, module, globs, source_lines)
891
# Look for tests in a module's contained objects.
892
if inspect.ismodule(obj) and self._recurse:
893
for valname, val in obj.__dict__.items():
894
valname = '%s.%s' % (name, valname)
895
# Recurse to functions & classes.
896
if ((inspect.isfunction(val) or inspect.isclass(val)) and
897
self._from_module(module, val)):
898
self._find(tests, val, valname, module, source_lines,
901
# Look for tests in a module's __test__ dictionary.
902
if inspect.ismodule(obj) and self._recurse:
903
for valname, val in getattr(obj, '__test__', {}).items():
904
if not isinstance(valname, str):
905
raise ValueError("DocTestFinder.find: __test__ keys "
906
"must be strings: %r" %
908
if not (inspect.isfunction(val) or inspect.isclass(val) or
909
inspect.ismethod(val) or inspect.ismodule(val) or
910
isinstance(val, str)):
911
raise ValueError("DocTestFinder.find: __test__ values "
912
"must be strings, functions, methods, "
913
"classes, or modules: %r" %
915
valname = '%s.__test__.%s' % (name, valname)
916
self._find(tests, val, valname, module, source_lines,
919
# Look for tests in a class's contained objects.
920
if inspect.isclass(obj) and self._recurse:
921
for valname, val in obj.__dict__.items():
922
# Special handling for staticmethod/classmethod.
923
if isinstance(val, staticmethod):
924
val = getattr(obj, valname)
925
if isinstance(val, classmethod):
926
val = getattr(obj, valname).__func__
928
# Recurse to methods, properties, and nested classes.
929
if ((inspect.isfunction(val) or inspect.isclass(val) or
930
isinstance(val, property)) and
931
self._from_module(module, val)):
932
valname = '%s.%s' % (name, valname)
933
self._find(tests, val, valname, module, source_lines,
936
def _get_test(self, obj, name, module, globs, source_lines):
938
Return a DocTest for the given object, if it defines a docstring;
939
otherwise, return None.
941
# Extract the object's docstring. If it doesn't have one,
942
# then return None (no test for this object).
943
if isinstance(obj, str):
947
if obj.__doc__ is None:
950
docstring = obj.__doc__
951
if not isinstance(docstring, str):
952
docstring = str(docstring)
953
except (TypeError, AttributeError):
956
# Find the docstring's location in the file.
957
lineno = self._find_lineno(obj, source_lines)
959
# Don't bother if the docstring is empty.
960
if self._exclude_empty and not docstring:
963
# Return a DocTest for this object.
967
filename = getattr(module, '__file__', module.__name__)
968
if filename[-4:] in (".pyc", ".pyo"):
969
filename = filename[:-1]
970
return self._parser.get_doctest(docstring, globs, name,
973
def _find_lineno(self, obj, source_lines):
975
Return a line number of the given object's docstring. Note:
976
this method assumes that the object has a docstring.
980
# Find the line number for modules.
981
if inspect.ismodule(obj):
984
# Find the line number for classes.
985
# Note: this could be fooled if a class is defined multiple
986
# times in a single file.
987
if inspect.isclass(obj):
988
if source_lines is None:
990
pat = re.compile(r'^\s*class\s*%s\b' %
991
getattr(obj, '__name__', '-'))
992
for i, line in enumerate(source_lines):
997
# Find the line number for functions & methods.
998
if inspect.ismethod(obj): obj = obj.__func__
999
if inspect.isfunction(obj): obj = obj.__code__
1000
if inspect.istraceback(obj): obj = obj.tb_frame
1001
if inspect.isframe(obj): obj = obj.f_code
1002
if inspect.iscode(obj):
1003
lineno = getattr(obj, 'co_firstlineno', None)-1
1005
# Find the line number where the docstring starts. Assume
1006
# that it's the first line that begins with a quote mark.
1007
# Note: this could be fooled by a multiline function
1008
# signature, where a continuation line begins with a quote
1010
if lineno is not None:
1011
if source_lines is None:
1013
pat = re.compile('(^|.*:)\s*\w*("|\')')
1014
for lineno in range(lineno, len(source_lines)):
1015
if pat.match(source_lines[lineno]):
1018
# We couldn't find the line number.
1021
######################################################################
1022
## 5. DocTest Runner
1023
######################################################################
1025
class DocTestRunner:
1027
A class used to run DocTest test cases, and accumulate statistics.
1028
The `run` method is used to process a single DocTest case. It
1029
returns a tuple `(f, t)`, where `t` is the number of test cases
1030
tried, and `f` is the number of test cases that failed.
1032
>>> tests = DocTestFinder().find(_TestClass)
1033
>>> runner = DocTestRunner(verbose=False)
1034
>>> tests.sort(key = lambda test: test.name)
1035
>>> for test in tests:
1036
... print(test.name, '->', runner.run(test))
1037
_TestClass -> TestResults(failed=0, attempted=2)
1038
_TestClass.__init__ -> TestResults(failed=0, attempted=2)
1039
_TestClass.get -> TestResults(failed=0, attempted=2)
1040
_TestClass.square -> TestResults(failed=0, attempted=1)
1042
The `summarize` method prints a summary of all the test cases that
1043
have been run by the runner, and returns an aggregated `(f, t)`
1046
>>> runner.summarize(verbose=1)
1047
4 items passed all tests:
1048
2 tests in _TestClass
1049
2 tests in _TestClass.__init__
1050
2 tests in _TestClass.get
1051
1 tests in _TestClass.square
1053
7 passed and 0 failed.
1055
TestResults(failed=0, attempted=7)
1057
The aggregated number of tried examples and failed examples is
1058
also available via the `tries` and `failures` attributes:
1065
The comparison between expected outputs and actual outputs is done
1066
by an `OutputChecker`. This comparison may be customized with a
1067
number of option flags; see the documentation for `testmod` for
1068
more information. If the option flags are insufficient, then the
1069
comparison may also be customized by passing a subclass of
1070
`OutputChecker` to the constructor.
1072
The test runner's display output can be controlled in two ways.
1073
First, an output function (`out) can be passed to
1074
`TestRunner.run`; this function will be called with strings that
1075
should be displayed. It defaults to `sys.stdout.write`. If
1076
capturing the output is not sufficient, then the display output
1077
can be also customized by subclassing DocTestRunner, and
1078
overriding the methods `report_start`, `report_success`,
1079
`report_unexpected_exception`, and `report_failure`.
1081
# This divider string is used to separate failure messages, and to
1082
# separate sections of the summary.
1085
def __init__(self, checker=None, verbose=None, optionflags=0):
1087
Create a new test runner.
1089
Optional keyword arg `checker` is the `OutputChecker` that
1090
should be used to compare the expected outputs and actual
1091
outputs of doctest examples.
1093
Optional keyword arg 'verbose' prints lots of stuff if true,
1094
only failures if false; by default, it's true iff '-v' is in
1097
Optional argument `optionflags` can be used to control how the
1098
test runner compares expected output to actual output, and how
1099
it displays failures. See the documentation for `testmod` for
1102
self._checker = checker or OutputChecker()
1104
verbose = '-v' in sys.argv
1105
self._verbose = verbose
1106
self.optionflags = optionflags
1107
self.original_optionflags = optionflags
1109
# Keep track of the examples we've run.
1114
# Create a fake output target for capturing doctest output.
1115
self._fakeout = _SpoofOut()
1117
#/////////////////////////////////////////////////////////////////
1119
#/////////////////////////////////////////////////////////////////
1121
def report_start(self, out, test, example):
1123
Report that the test runner is about to process the given
1124
example. (Only displays a message if verbose=True)
1128
out('Trying:\n' + _indent(example.source) +
1129
'Expecting:\n' + _indent(example.want))
1131
out('Trying:\n' + _indent(example.source) +
1132
'Expecting nothing\n')
1134
def report_success(self, out, test, example, got):
1136
Report that the given example ran successfully. (Only
1137
displays a message if verbose=True)
1142
def report_failure(self, out, test, example, got):
1144
Report that the given example failed.
1146
out(self._failure_header(test, example) +
1147
self._checker.output_difference(example, got, self.optionflags))
1149
def report_unexpected_exception(self, out, test, example, exc_info):
1151
Report that the given example raised an unexpected exception.
1153
out(self._failure_header(test, example) +
1154
'Exception raised:\n' + _indent(_exception_traceback(exc_info)))
1156
def _failure_header(self, test, example):
1157
out = [self.DIVIDER]
1159
if test.lineno is not None and example.lineno is not None:
1160
lineno = test.lineno + example.lineno + 1
1163
out.append('File "%s", line %s, in %s' %
1164
(test.filename, lineno, test.name))
1166
out.append('Line %s, in %s' % (example.lineno+1, test.name))
1167
out.append('Failed example:')
1168
source = example.source
1169
out.append(_indent(source))
1170
return '\n'.join(out)
1172
#/////////////////////////////////////////////////////////////////
1174
#/////////////////////////////////////////////////////////////////
1176
def __run(self, test, compileflags, out):
1178
Run the examples in `test`. Write the outcome of each example
1179
with one of the `DocTestRunner.report_*` methods, using the
1180
writer function `out`. `compileflags` is the set of compiler
1181
flags that should be used to execute examples. Return a tuple
1182
`(f, t)`, where `t` is the number of examples tried, and `f`
1183
is the number of examples that failed. The examples are run
1184
in the namespace `test.globs`.
1186
# Keep track of the number of failures and tries.
1187
failures = tries = 0
1189
# Save the option flags (since option directives can be used
1191
original_optionflags = self.optionflags
1193
SUCCESS, FAILURE, BOOM = range(3) # `outcome` state
1195
check = self._checker.check_output
1197
# Process each example.
1198
for examplenum, example in enumerate(test.examples):
1200
# If REPORT_ONLY_FIRST_FAILURE is set, then supress
1201
# reporting after the first failure.
1202
quiet = (self.optionflags & REPORT_ONLY_FIRST_FAILURE and
1205
# Merge in the example's options.
1206
self.optionflags = original_optionflags
1208
for (optionflag, val) in example.options.items():
1210
self.optionflags |= optionflag
1212
self.optionflags &= ~optionflag
1214
# If 'SKIP' is set, then skip this example.
1215
if self.optionflags & SKIP:
1218
# Record that we started this example.
1221
self.report_start(out, test, example)
1223
# Use a special filename for compile(), so we can retrieve
1224
# the source code during interactive debugging (see
1225
# __patched_linecache_getlines).
1226
filename = '<doctest %s[%d]>' % (test.name, examplenum)
1228
# Run the example in the given context (globs), and record
1229
# any exception that gets raised. (But don't intercept
1230
# keyboard interrupts.)
1232
# Don't blink! This is where the user's code gets run.
1233
exec(compile(example.source, filename, "single",
1234
compileflags, 1), test.globs)
1235
self.debugger.set_continue() # ==== Example Finished ====
1237
except KeyboardInterrupt:
1240
exception = sys.exc_info()
1241
self.debugger.set_continue() # ==== Example Finished ====
1243
got = self._fakeout.getvalue() # the actual output
1244
self._fakeout.truncate(0)
1245
outcome = FAILURE # guilty until proved innocent or insane
1247
# If the example executed without raising any exceptions,
1248
# verify its output.
1249
if exception is None:
1250
if check(example.want, got, self.optionflags):
1253
# The example raised an exception: check if it was expected.
1255
exc_msg = traceback.format_exception_only(*exception[:2])[-1]
1257
got += _exception_traceback(exception)
1259
# If `example.exc_msg` is None, then we weren't expecting
1261
if example.exc_msg is None:
1264
# We expected an exception: see whether it matches.
1265
elif check(example.exc_msg, exc_msg, self.optionflags):
1268
# Another chance if they didn't care about the detail.
1269
elif self.optionflags & IGNORE_EXCEPTION_DETAIL:
1270
m1 = re.match(r'[^:]*:', example.exc_msg)
1271
m2 = re.match(r'[^:]*:', exc_msg)
1272
if m1 and m2 and check(m1.group(0), m2.group(0),
1276
# Report the outcome.
1277
if outcome is SUCCESS:
1279
self.report_success(out, test, example, got)
1280
elif outcome is FAILURE:
1282
self.report_failure(out, test, example, got)
1284
elif outcome is BOOM:
1286
self.report_unexpected_exception(out, test, example,
1290
assert False, ("unknown outcome", outcome)
1292
# Restore the option flags (in case they were modified)
1293
self.optionflags = original_optionflags
1295
# Record and return the number of failures and tries.
1296
self.__record_outcome(test, failures, tries)
1297
return TestResults(failures, tries)
1299
def __record_outcome(self, test, f, t):
1301
Record the fact that the given DocTest (`test`) generated `f`
1302
failures out of `t` tried examples.
1304
f2, t2 = self._name2ft.get(test.name, (0,0))
1305
self._name2ft[test.name] = (f+f2, t+t2)
1309
__LINECACHE_FILENAME_RE = re.compile(r'<doctest '
1310
r'(?P<name>[\w\.]+)'
1311
r'\[(?P<examplenum>\d+)\]>$')
1312
def __patched_linecache_getlines(self, filename, module_globals=None):
1313
m = self.__LINECACHE_FILENAME_RE.match(filename)
1314
if m and m.group('name') == self.test.name:
1315
example = self.test.examples[int(m.group('examplenum'))]
1316
return example.source.splitlines(True)
1318
return self.save_linecache_getlines(filename, module_globals)
1320
def run(self, test, compileflags=None, out=None, clear_globs=True):
1322
Run the examples in `test`, and display the results using the
1323
writer function `out`.
1325
The examples are run in the namespace `test.globs`. If
1326
`clear_globs` is true (the default), then this namespace will
1327
be cleared after the test runs, to help with garbage
1328
collection. If you would like to examine the namespace after
1329
the test completes, then use `clear_globs=False`.
1331
`compileflags` gives the set of flags that should be used by
1332
the Python compiler when running the examples. If not
1333
specified, then it will default to the set of future-import
1334
flags that apply to `globs`.
1336
The output of each example is checked using
1337
`DocTestRunner.check_output`, and the results are formatted by
1338
the `DocTestRunner.report_*` methods.
1342
if compileflags is None:
1343
compileflags = _extract_future_flags(test.globs)
1345
save_stdout = sys.stdout
1347
out = save_stdout.write
1348
sys.stdout = self._fakeout
1350
# Patch pdb.set_trace to restore sys.stdout during interactive
1351
# debugging (so it's not still redirected to self._fakeout).
1352
# Note that the interactive output will go to *our*
1353
# save_stdout, even if that's not the real sys.stdout; this
1354
# allows us to write test cases for the set_trace behavior.
1355
save_set_trace = pdb.set_trace
1356
self.debugger = _OutputRedirectingPdb(save_stdout)
1357
self.debugger.reset()
1358
pdb.set_trace = self.debugger.set_trace
1360
# Patch linecache.getlines, so we can see the example's source
1361
# when we're inside the debugger.
1362
self.save_linecache_getlines = linecache.getlines
1363
linecache.getlines = self.__patched_linecache_getlines
1366
return self.__run(test, compileflags, out)
1368
sys.stdout = save_stdout
1369
pdb.set_trace = save_set_trace
1370
linecache.getlines = self.save_linecache_getlines
1376
#/////////////////////////////////////////////////////////////////
1378
#/////////////////////////////////////////////////////////////////
1379
def summarize(self, verbose=None):
1381
Print a summary of all the test cases that have been run by
1382
this DocTestRunner, and return a tuple `(f, t)`, where `f` is
1383
the total number of failed examples, and `t` is the total
1384
number of tried examples.
1386
The optional `verbose` argument controls how detailed the
1387
summary is. If the verbosity is not specified, then the
1388
DocTestRunner's verbosity is used.
1391
verbose = self._verbose
1396
for x in self._name2ft.items():
1402
notests.append(name)
1404
passed.append( (name, t) )
1409
print(len(notests), "items had no tests:")
1411
for thing in notests:
1414
print(len(passed), "items passed all tests:")
1416
for thing, count in passed:
1417
print(" %3d tests in %s" % (count, thing))
1420
print(len(failed), "items had failures:")
1422
for thing, (f, t) in failed:
1423
print(" %3d of %3d in %s" % (f, t, thing))
1425
print(totalt, "tests in", len(self._name2ft), "items.")
1426
print(totalt - totalf, "passed and", totalf, "failed.")
1428
print("***Test Failed***", totalf, "failures.")
1430
print("Test passed.")
1431
return TestResults(totalf, totalt)
1433
#/////////////////////////////////////////////////////////////////
1434
# Backward compatibility cruft to maintain doctest.master.
1435
#/////////////////////////////////////////////////////////////////
1436
def merge(self, other):
1438
for name, (f, t) in other._name2ft.items():
1440
# Don't print here by default, since doing
1441
# so breaks some of the buildbots
1442
#print("*** DocTestRunner.merge: '" + name + "' in both" \
1443
# " testers; summing outcomes.")
1449
class OutputChecker:
1451
A class used to check the whether the actual output from a doctest
1452
example matches the expected output. `OutputChecker` defines two
1453
methods: `check_output`, which compares a given pair of outputs,
1454
and returns true if they match; and `output_difference`, which
1455
returns a string describing the differences between two outputs.
1457
def _toAscii(self, s):
1459
Convert string to hex-escaped ASCII string.
1461
return str(s.encode('ASCII', 'backslashreplace'), "ASCII")
1463
def check_output(self, want, got, optionflags):
1465
Return True iff the actual output from an example (`got`)
1466
matches the expected output (`want`). These strings are
1467
always considered to match if they are identical; but
1468
depending on what option flags the test runner is using,
1469
several non-exact match types are also possible. See the
1470
documentation for `TestRunner` for more information about
1474
# If `want` contains hex-escaped character such as "\u1234",
1475
# then `want` is a string of six characters(e.g. [\,u,1,2,3,4]).
1476
# On the other hand, `got` could be an another sequence of
1477
# characters such as [\u1234], so `want` and `got` should
1478
# be folded to hex-escaped ASCII string to compare.
1479
got = self._toAscii(got)
1480
want = self._toAscii(want)
1482
# Handle the common case first, for efficiency:
1483
# if they're string-identical, always return true.
1487
# The values True and False replaced 1 and 0 as the return
1488
# value for boolean comparisons in Python 2.3.
1489
if not (optionflags & DONT_ACCEPT_TRUE_FOR_1):
1490
if (got,want) == ("True\n", "1\n"):
1492
if (got,want) == ("False\n", "0\n"):
1495
# <BLANKLINE> can be used as a special sequence to signify a
1496
# blank line, unless the DONT_ACCEPT_BLANKLINE flag is used.
1497
if not (optionflags & DONT_ACCEPT_BLANKLINE):
1498
# Replace <BLANKLINE> in want with a blank line.
1499
want = re.sub('(?m)^%s\s*?$' % re.escape(BLANKLINE_MARKER),
1501
# If a line in got contains only spaces, then remove the
1503
got = re.sub('(?m)^\s*?$', '', got)
1507
# This flag causes doctest to ignore any differences in the
1508
# contents of whitespace strings. Note that this can be used
1509
# in conjunction with the ELLIPSIS flag.
1510
if optionflags & NORMALIZE_WHITESPACE:
1511
got = ' '.join(got.split())
1512
want = ' '.join(want.split())
1516
# The ELLIPSIS flag says to let the sequence "..." in `want`
1517
# match any substring in `got`.
1518
if optionflags & ELLIPSIS:
1519
if _ellipsis_match(want, got):
1522
# We didn't find any match; return false.
1525
# Should we do a fancy diff?
1526
def _do_a_fancy_diff(self, want, got, optionflags):
1527
# Not unless they asked for a fancy diff.
1528
if not optionflags & (REPORT_UDIFF |
1533
# If expected output uses ellipsis, a meaningful fancy diff is
1534
# too hard ... or maybe not. In two real-life failures Tim saw,
1535
# a diff was a major help anyway, so this is commented out.
1536
# [todo] _ellipsis_match() knows which pieces do and don't match,
1537
# and could be the basis for a kick-ass diff in this case.
1538
##if optionflags & ELLIPSIS and ELLIPSIS_MARKER in want:
1541
# ndiff does intraline difference marking, so can be useful even
1542
# for 1-line differences.
1543
if optionflags & REPORT_NDIFF:
1546
# The other diff types need at least a few lines to be helpful.
1547
return want.count('\n') > 2 and got.count('\n') > 2
1549
def output_difference(self, example, got, optionflags):
1551
Return a string describing the differences between the
1552
expected output for a given example (`example`) and the actual
1553
output (`got`). `optionflags` is the set of option flags used
1554
to compare `want` and `got`.
1557
# If <BLANKLINE>s are being used, then replace blank lines
1558
# with <BLANKLINE> in the actual output string.
1559
if not (optionflags & DONT_ACCEPT_BLANKLINE):
1560
got = re.sub('(?m)^[ ]*(?=\n)', BLANKLINE_MARKER, got)
1562
# Check if we should use diff.
1563
if self._do_a_fancy_diff(want, got, optionflags):
1564
# Split want & got into lines.
1565
want_lines = want.splitlines(True) # True == keep line ends
1566
got_lines = got.splitlines(True)
1567
# Use difflib to find their differences.
1568
if optionflags & REPORT_UDIFF:
1569
diff = difflib.unified_diff(want_lines, got_lines, n=2)
1570
diff = list(diff)[2:] # strip the diff header
1571
kind = 'unified diff with -expected +actual'
1572
elif optionflags & REPORT_CDIFF:
1573
diff = difflib.context_diff(want_lines, got_lines, n=2)
1574
diff = list(diff)[2:] # strip the diff header
1575
kind = 'context diff with expected followed by actual'
1576
elif optionflags & REPORT_NDIFF:
1577
engine = difflib.Differ(charjunk=difflib.IS_CHARACTER_JUNK)
1578
diff = list(engine.compare(want_lines, got_lines))
1579
kind = 'ndiff with -expected +actual'
1581
assert 0, 'Bad diff option'
1582
# Remove trailing whitespace on diff output.
1583
diff = [line.rstrip() + '\n' for line in diff]
1584
return 'Differences (%s):\n' % kind + _indent(''.join(diff))
1586
# If we're not using diff, then simply list the expected
1587
# output followed by the actual output.
1589
return 'Expected:\n%sGot:\n%s' % (_indent(want), _indent(got))
1591
return 'Expected:\n%sGot nothing\n' % _indent(want)
1593
return 'Expected nothing\nGot:\n%s' % _indent(got)
1595
return 'Expected nothing\nGot nothing\n'
1597
class DocTestFailure(Exception):
1598
"""A DocTest example has failed in debugging mode.
1600
The exception instance has variables:
1602
- test: the DocTest object being run
1604
- example: the Example object that failed
1606
- got: the actual output
1608
def __init__(self, test, example, got):
1610
self.example = example
1614
return str(self.test)
1616
class UnexpectedException(Exception):
1617
"""A DocTest example has encountered an unexpected exception
1619
The exception instance has variables:
1621
- test: the DocTest object being run
1623
- example: the Example object that failed
1625
- exc_info: the exception info
1627
def __init__(self, test, example, exc_info):
1629
self.example = example
1630
self.exc_info = exc_info
1633
return str(self.test)
1635
class DebugRunner(DocTestRunner):
1636
r"""Run doc tests but raise an exception as soon as there is a failure.
1638
If an unexpected exception occurs, an UnexpectedException is raised.
1639
It contains the test, the example, and the original exception:
1641
>>> runner = DebugRunner(verbose=False)
1642
>>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
1643
... {}, 'foo', 'foo.py', 0)
1645
... runner.run(test)
1646
... except UnexpectedException as f:
1649
>>> failure.test is test
1652
>>> failure.example.want
1655
>>> exc_info = failure.exc_info
1656
>>> raise exc_info[1] # Already has the traceback
1657
Traceback (most recent call last):
1661
We wrap the original exception to give the calling application
1662
access to the test and example information.
1664
If the output doesn't match, then a DocTestFailure is raised:
1666
>>> test = DocTestParser().get_doctest('''
1670
... ''', {}, 'foo', 'foo.py', 0)
1673
... runner.run(test)
1674
... except DocTestFailure as f:
1677
DocTestFailure objects provide access to the test:
1679
>>> failure.test is test
1682
As well as to the example:
1684
>>> failure.example.want
1687
and the actual output:
1692
If a failure or error occurs, the globals are left intact:
1694
>>> del test.globs['__builtins__']
1698
>>> test = DocTestParser().get_doctest('''
1700
... >>> raise KeyError
1701
... ''', {}, 'foo', 'foo.py', 0)
1703
>>> runner.run(test)
1704
Traceback (most recent call last):
1706
doctest.UnexpectedException: <DocTest foo from foo.py:0 (2 examples)>
1708
>>> del test.globs['__builtins__']
1712
But the globals are cleared if there is no error:
1714
>>> test = DocTestParser().get_doctest('''
1716
... ''', {}, 'foo', 'foo.py', 0)
1718
>>> runner.run(test)
1719
TestResults(failed=0, attempted=1)
1726
def run(self, test, compileflags=None, out=None, clear_globs=True):
1727
r = DocTestRunner.run(self, test, compileflags, out, False)
1732
def report_unexpected_exception(self, out, test, example, exc_info):
1733
raise UnexpectedException(test, example, exc_info)
1735
def report_failure(self, out, test, example, got):
1736
raise DocTestFailure(test, example, got)
1738
######################################################################
1739
## 6. Test Functions
1740
######################################################################
1741
# These should be backwards compatible.
1743
# For backward compatibility, a global instance of a DocTestRunner
1744
# class, updated by testmod.
1747
def testmod(m=None, name=None, globs=None, verbose=None,
1748
report=True, optionflags=0, extraglobs=None,
1749
raise_on_error=False, exclude_empty=False):
1750
"""m=None, name=None, globs=None, verbose=None, report=True,
1751
optionflags=0, extraglobs=None, raise_on_error=False,
1754
Test examples in docstrings in functions and classes reachable
1755
from module m (or the current module if m is not supplied), starting
1758
Also test examples reachable from dict m.__test__ if it exists and is
1759
not None. m.__test__ maps names to functions, classes and strings;
1760
function and class docstrings are tested even if the name is private;
1761
strings are tested directly, as if they were docstrings.
1763
Return (#failures, #tests).
1765
See doctest.__doc__ for an overview.
1767
Optional keyword arg "name" gives the name of the module; by default
1770
Optional keyword arg "globs" gives a dict to be used as the globals
1771
when executing examples; by default, use m.__dict__. A copy of this
1772
dict is actually used for each docstring, so that each docstring's
1773
examples start with a clean slate.
1775
Optional keyword arg "extraglobs" gives a dictionary that should be
1776
merged into the globals that are used to execute examples. By
1777
default, no extra globals are used. This is new in 2.4.
1779
Optional keyword arg "verbose" prints lots of stuff if true, prints
1780
only failures if false; by default, it's true iff "-v" is in sys.argv.
1782
Optional keyword arg "report" prints a summary at the end when true,
1783
else prints nothing at the end. In verbose mode, the summary is
1784
detailed, else very brief (in fact, empty if all tests passed).
1786
Optional keyword arg "optionflags" or's together module constants,
1787
and defaults to 0. This is new in 2.3. Possible values (see the
1790
DONT_ACCEPT_TRUE_FOR_1
1791
DONT_ACCEPT_BLANKLINE
1792
NORMALIZE_WHITESPACE
1795
IGNORE_EXCEPTION_DETAIL
1799
REPORT_ONLY_FIRST_FAILURE
1801
Optional keyword arg "raise_on_error" raises an exception on the
1802
first unexpected exception or failure. This allows failures to be
1803
post-mortem debugged.
1805
Advanced tomfoolery: testmod runs methods of a local instance of
1806
class doctest.Tester, then merges the results into (or creates)
1807
global Tester instance doctest.master. Methods of doctest.master
1808
can be called directly too, if you want to do something unusual.
1809
Passing report=0 to testmod is especially useful then, to delay
1810
displaying a summary. Invoke doctest.master.summarize(verbose)
1811
when you're done fiddling.
1815
# If no module was given, then use __main__.
1817
# DWA - m will still be None if this wasn't invoked from the command
1818
# line, in which case the following TypeError is about as good an error
1819
# as we should expect
1820
m = sys.modules.get('__main__')
1822
# Check that we were actually given a module.
1823
if not inspect.ismodule(m):
1824
raise TypeError("testmod: module required; %r" % (m,))
1826
# If no name was given, then use the module's name.
1830
# Find, parse, and run all tests in the given module.
1831
finder = DocTestFinder(exclude_empty=exclude_empty)
1834
runner = DebugRunner(verbose=verbose, optionflags=optionflags)
1836
runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1838
for test in finder.find(m, name, globs=globs, extraglobs=extraglobs):
1847
master.merge(runner)
1849
return TestResults(runner.failures, runner.tries)
1851
def testfile(filename, module_relative=True, name=None, package=None,
1852
globs=None, verbose=None, report=True, optionflags=0,
1853
extraglobs=None, raise_on_error=False, parser=DocTestParser(),
1856
Test examples in the given file. Return (#failures, #tests).
1858
Optional keyword arg "module_relative" specifies how filenames
1859
should be interpreted:
1861
- If "module_relative" is True (the default), then "filename"
1862
specifies a module-relative path. By default, this path is
1863
relative to the calling module's directory; but if the
1864
"package" argument is specified, then it is relative to that
1865
package. To ensure os-independence, "filename" should use
1866
"/" characters to separate path segments, and should not
1867
be an absolute path (i.e., it may not begin with "/").
1869
- If "module_relative" is False, then "filename" specifies an
1870
os-specific path. The path may be absolute or relative (to
1871
the current working directory).
1873
Optional keyword arg "name" gives the name of the test; by default
1874
use the file's basename.
1876
Optional keyword argument "package" is a Python package or the
1877
name of a Python package whose directory should be used as the
1878
base directory for a module relative filename. If no package is
1879
specified, then the calling module's directory is used as the base
1880
directory for module relative filenames. It is an error to
1881
specify "package" if "module_relative" is False.
1883
Optional keyword arg "globs" gives a dict to be used as the globals
1884
when executing examples; by default, use {}. A copy of this dict
1885
is actually used for each docstring, so that each docstring's
1886
examples start with a clean slate.
1888
Optional keyword arg "extraglobs" gives a dictionary that should be
1889
merged into the globals that are used to execute examples. By
1890
default, no extra globals are used.
1892
Optional keyword arg "verbose" prints lots of stuff if true, prints
1893
only failures if false; by default, it's true iff "-v" is in sys.argv.
1895
Optional keyword arg "report" prints a summary at the end when true,
1896
else prints nothing at the end. In verbose mode, the summary is
1897
detailed, else very brief (in fact, empty if all tests passed).
1899
Optional keyword arg "optionflags" or's together module constants,
1900
and defaults to 0. Possible values (see the docs for details):
1902
DONT_ACCEPT_TRUE_FOR_1
1903
DONT_ACCEPT_BLANKLINE
1904
NORMALIZE_WHITESPACE
1907
IGNORE_EXCEPTION_DETAIL
1911
REPORT_ONLY_FIRST_FAILURE
1913
Optional keyword arg "raise_on_error" raises an exception on the
1914
first unexpected exception or failure. This allows failures to be
1915
post-mortem debugged.
1917
Optional keyword arg "parser" specifies a DocTestParser (or
1918
subclass) that should be used to extract tests from the files.
1920
Optional keyword arg "encoding" specifies an encoding that should
1921
be used to convert the file to unicode.
1923
Advanced tomfoolery: testmod runs methods of a local instance of
1924
class doctest.Tester, then merges the results into (or creates)
1925
global Tester instance doctest.master. Methods of doctest.master
1926
can be called directly too, if you want to do something unusual.
1927
Passing report=0 to testmod is especially useful then, to delay
1928
displaying a summary. Invoke doctest.master.summarize(verbose)
1929
when you're done fiddling.
1933
if package and not module_relative:
1934
raise ValueError("Package may only be specified for module-"
1937
# Relativize the path
1938
text, filename = _load_testfile(filename, package, module_relative,
1939
encoding or "utf-8")
1941
# If no name was given, then use the file's name.
1943
name = os.path.basename(filename)
1945
# Assemble the globals.
1949
globs = globs.copy()
1950
if extraglobs is not None:
1951
globs.update(extraglobs)
1952
if '__name__' not in globs:
1953
globs['__name__'] = '__main__'
1956
runner = DebugRunner(verbose=verbose, optionflags=optionflags)
1958
runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1960
# Read the file, convert it to a test, and run it.
1961
test = parser.get_doctest(text, globs, name, filename, 0)
1970
master.merge(runner)
1972
return TestResults(runner.failures, runner.tries)
1974
def run_docstring_examples(f, globs, verbose=False, name="NoName",
1975
compileflags=None, optionflags=0):
1977
Test examples in the given object's docstring (`f`), using `globs`
1978
as globals. Optional argument `name` is used in failure messages.
1979
If the optional argument `verbose` is true, then generate output
1980
even if there are no failures.
1982
`compileflags` gives the set of flags that should be used by the
1983
Python compiler when running the examples. If not specified, then
1984
it will default to the set of future-import flags that apply to
1987
Optional keyword arg `optionflags` specifies options for the
1988
testing and output. See the documentation for `testmod` for more
1991
# Find, parse, and run all tests in the given module.
1992
finder = DocTestFinder(verbose=verbose, recurse=False)
1993
runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1994
for test in finder.find(f, name, globs=globs):
1995
runner.run(test, compileflags=compileflags)
1997
######################################################################
1998
## 7. Unittest Support
1999
######################################################################
2001
_unittest_reportflags = 0
2003
def set_unittest_reportflags(flags):
2004
"""Sets the unittest option flags.
2006
The old flag is returned so that a runner could restore the old
2007
value if it wished to:
2010
>>> old = doctest._unittest_reportflags
2011
>>> doctest.set_unittest_reportflags(REPORT_NDIFF |
2012
... REPORT_ONLY_FIRST_FAILURE) == old
2015
>>> doctest._unittest_reportflags == (REPORT_NDIFF |
2016
... REPORT_ONLY_FIRST_FAILURE)
2019
Only reporting flags can be set:
2021
>>> doctest.set_unittest_reportflags(ELLIPSIS)
2022
Traceback (most recent call last):
2024
ValueError: ('Only reporting flags allowed', 8)
2026
>>> doctest.set_unittest_reportflags(old) == (REPORT_NDIFF |
2027
... REPORT_ONLY_FIRST_FAILURE)
2030
global _unittest_reportflags
2032
if (flags & REPORTING_FLAGS) != flags:
2033
raise ValueError("Only reporting flags allowed", flags)
2034
old = _unittest_reportflags
2035
_unittest_reportflags = flags
2039
class DocTestCase(unittest.TestCase):
2041
def __init__(self, test, optionflags=0, setUp=None, tearDown=None,
2044
unittest.TestCase.__init__(self)
2045
self._dt_optionflags = optionflags
2046
self._dt_checker = checker
2047
self._dt_test = test
2048
self._dt_setUp = setUp
2049
self._dt_tearDown = tearDown
2052
test = self._dt_test
2054
if self._dt_setUp is not None:
2055
self._dt_setUp(test)
2058
test = self._dt_test
2060
if self._dt_tearDown is not None:
2061
self._dt_tearDown(test)
2066
test = self._dt_test
2069
optionflags = self._dt_optionflags
2071
if not (optionflags & REPORTING_FLAGS):
2072
# The option flags don't include any reporting flags,
2073
# so add the default reporting flags
2074
optionflags |= _unittest_reportflags
2076
runner = DocTestRunner(optionflags=optionflags,
2077
checker=self._dt_checker, verbose=False)
2080
runner.DIVIDER = "-"*70
2081
failures, tries = runner.run(
2082
test, out=new.write, clear_globs=False)
2087
raise self.failureException(self.format_failure(new.getvalue()))
2089
def format_failure(self, err):
2090
test = self._dt_test
2091
if test.lineno is None:
2092
lineno = 'unknown line number'
2094
lineno = '%s' % test.lineno
2095
lname = '.'.join(test.name.split('.')[-1:])
2096
return ('Failed doctest test for %s\n'
2097
' File "%s", line %s, in %s\n\n%s'
2098
% (test.name, test.filename, lineno, lname, err)
2102
r"""Run the test case without results and without catching exceptions
2104
The unit test framework includes a debug method on test cases
2105
and test suites to support post-mortem debugging. The test code
2106
is run in such a way that errors are not caught. This way a
2107
caller can catch the errors and initiate post-mortem debugging.
2109
The DocTestCase provides a debug method that raises
2110
UnexpectedException errors if there is an unexepcted
2113
>>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
2114
... {}, 'foo', 'foo.py', 0)
2115
>>> case = DocTestCase(test)
2118
... except UnexpectedException as f:
2121
The UnexpectedException contains the test, the example, and
2122
the original exception:
2124
>>> failure.test is test
2127
>>> failure.example.want
2130
>>> exc_info = failure.exc_info
2131
>>> raise exc_info[1] # Already has the traceback
2132
Traceback (most recent call last):
2136
If the output doesn't match, then a DocTestFailure is raised:
2138
>>> test = DocTestParser().get_doctest('''
2142
... ''', {}, 'foo', 'foo.py', 0)
2143
>>> case = DocTestCase(test)
2147
... except DocTestFailure as f:
2150
DocTestFailure objects provide access to the test:
2152
>>> failure.test is test
2155
As well as to the example:
2157
>>> failure.example.want
2160
and the actual output:
2168
runner = DebugRunner(optionflags=self._dt_optionflags,
2169
checker=self._dt_checker, verbose=False)
2170
runner.run(self._dt_test, clear_globs=False)
2174
return self._dt_test.name
2177
name = self._dt_test.name.split('.')
2178
return "%s (%s)" % (name[-1], '.'.join(name[:-1]))
2182
def shortDescription(self):
2183
return "Doctest: " + self._dt_test.name
2185
def DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None,
2188
Convert doctest tests for a module to a unittest test suite.
2190
This converts each documentation string in a module that
2191
contains doctest tests to a unittest test case. If any of the
2192
tests in a doc string fail, then the test case fails. An exception
2193
is raised showing the name of the file containing the test and a
2194
(sometimes approximate) line number.
2196
The `module` argument provides the module to be tested. The argument
2197
can be either a module or a module name.
2199
If no argument is given, the calling module is used.
2201
A number of options may be provided as keyword arguments:
2204
A set-up function. This is called before running the
2205
tests in each file. The setUp function will be passed a DocTest
2206
object. The setUp function can access the test globals as the
2207
globs attribute of the test passed.
2210
A tear-down function. This is called after running the
2211
tests in each file. The tearDown function will be passed a DocTest
2212
object. The tearDown function can access the test globals as the
2213
globs attribute of the test passed.
2216
A dictionary containing initial global variables for the tests.
2219
A set of doctest option flags expressed as an integer.
2222
if test_finder is None:
2223
test_finder = DocTestFinder()
2225
module = _normalize_module(module)
2226
tests = test_finder.find(module, globs=globs, extraglobs=extraglobs)
2228
# Why do we want to do this? Because it reveals a bug that might
2229
# otherwise be hidden.
2230
raise ValueError(module, "has no tests")
2233
suite = unittest.TestSuite()
2235
if len(test.examples) == 0:
2237
if not test.filename:
2238
filename = module.__file__
2239
if filename[-4:] in (".pyc", ".pyo"):
2240
filename = filename[:-1]
2241
test.filename = filename
2242
suite.addTest(DocTestCase(test, **options))
2246
class DocFileCase(DocTestCase):
2249
return '_'.join(self._dt_test.name.split('.'))
2252
return self._dt_test.filename
2255
def format_failure(self, err):
2256
return ('Failed doctest test for %s\n File "%s", line 0\n\n%s'
2257
% (self._dt_test.name, self._dt_test.filename, err)
2260
def DocFileTest(path, module_relative=True, package=None,
2261
globs=None, parser=DocTestParser(),
2262
encoding=None, **options):
2266
globs = globs.copy()
2268
if package and not module_relative:
2269
raise ValueError("Package may only be specified for module-"
2272
# Relativize the path.
2273
doc, path = _load_testfile(path, package, module_relative,
2274
encoding or "utf-8")
2276
if "__file__" not in globs:
2277
globs["__file__"] = path
2279
# Find the file and read it.
2280
name = os.path.basename(path)
2282
# Convert it to a test, and wrap it in a DocFileCase.
2283
test = parser.get_doctest(doc, globs, name, path, 0)
2284
return DocFileCase(test, **options)
2286
def DocFileSuite(*paths, **kw):
2287
"""A unittest suite for one or more doctest files.
2289
The path to each doctest file is given as a string; the
2290
interpretation of that string depends on the keyword argument
2293
A number of options may be provided as keyword arguments:
2296
If "module_relative" is True, then the given file paths are
2297
interpreted as os-independent module-relative paths. By
2298
default, these paths are relative to the calling module's
2299
directory; but if the "package" argument is specified, then
2300
they are relative to that package. To ensure os-independence,
2301
"filename" should use "/" characters to separate path
2302
segments, and may not be an absolute path (i.e., it may not
2305
If "module_relative" is False, then the given file paths are
2306
interpreted as os-specific paths. These paths may be absolute
2307
or relative (to the current working directory).
2310
A Python package or the name of a Python package whose directory
2311
should be used as the base directory for module relative paths.
2312
If "package" is not specified, then the calling module's
2313
directory is used as the base directory for module relative
2314
filenames. It is an error to specify "package" if
2315
"module_relative" is False.
2318
A set-up function. This is called before running the
2319
tests in each file. The setUp function will be passed a DocTest
2320
object. The setUp function can access the test globals as the
2321
globs attribute of the test passed.
2324
A tear-down function. This is called after running the
2325
tests in each file. The tearDown function will be passed a DocTest
2326
object. The tearDown function can access the test globals as the
2327
globs attribute of the test passed.
2330
A dictionary containing initial global variables for the tests.
2333
A set of doctest option flags expressed as an integer.
2336
A DocTestParser (or subclass) that should be used to extract
2337
tests from the files.
2340
An encoding that will be used to convert the files to unicode.
2342
suite = unittest.TestSuite()
2344
# We do this here so that _normalize_module is called at the right
2345
# level. If it were called in DocFileTest, then this function
2346
# would be the caller and we might guess the package incorrectly.
2347
if kw.get('module_relative', True):
2348
kw['package'] = _normalize_module(kw.get('package'))
2351
suite.addTest(DocFileTest(path, **kw))
2355
######################################################################
2356
## 8. Debugging Support
2357
######################################################################
2359
def script_from_examples(s):
2360
r"""Extract script from text with examples.
2362
Converts text with examples to a Python script. Example input is
2363
converted to regular code. Example output and all other words
2364
are converted to comments:
2367
... Here are examples of simple math.
2369
... Python has super accurate integer addition
2374
... And very friendly error messages:
2381
... You can use logic if you want:
2391
>>> print(script_from_examples(text))
2392
# Here are examples of simple math.
2394
# Python has super accurate integer addition
2400
# And very friendly error messages:
2408
# You can use logic if you want:
2418
for piece in DocTestParser().parse(s):
2419
if isinstance(piece, Example):
2420
# Add the example's source code (strip trailing NL)
2421
output.append(piece.source[:-1])
2422
# Add the expected output:
2425
output.append('# Expected:')
2426
output += ['## '+l for l in want.split('\n')[:-1]]
2428
# Add non-example text.
2429
output += [_comment_line(l)
2430
for l in piece.split('\n')[:-1]]
2432
# Trim junk on both ends.
2433
while output and output[-1] == '#':
2435
while output and output[0] == '#':
2437
# Combine the output, and return it.
2438
# Add a courtesy newline to prevent exec from choking (see bug #1172785)
2439
return '\n'.join(output) + '\n'
2441
def testsource(module, name):
2442
"""Extract the test sources from a doctest docstring as a script.
2444
Provide the module (or dotted name of the module) containing the
2445
test to be debugged and the name (within the module) of the object
2446
with the doc string with tests to be debugged.
2448
module = _normalize_module(module)
2449
tests = DocTestFinder().find(module)
2450
test = [t for t in tests if t.name == name]
2452
raise ValueError(name, "not found in tests")
2454
testsrc = script_from_examples(test.docstring)
2457
def debug_src(src, pm=False, globs=None):
2458
"""Debug a single doctest docstring, in argument `src`'"""
2459
testsrc = script_from_examples(src)
2460
debug_script(testsrc, pm, globs)
2462
def debug_script(src, pm=False, globs=None):
2463
"Debug a test script. `src` is the script, as a string."
2466
# Note that tempfile.NameTemporaryFile() cannot be used. As the
2467
# docs say, a file so created cannot be opened by name a second time
2468
# on modern Windows boxes, and exec() needs to open and read it.
2469
srcfilename = tempfile.mktemp(".py", "doctestdebug")
2470
f = open(srcfilename, 'w')
2476
globs = globs.copy()
2482
exec(open(srcfilename).read(), globs, globs)
2484
print(sys.exc_info()[1])
2485
pdb.post_mortem(sys.exc_info()[2])
2487
fp = open(srcfilename)
2492
pdb.run("exec(%r)" % script, globs, globs)
2495
os.remove(srcfilename)
2497
def debug(module, name, pm=False):
2498
"""Debug a single doctest docstring.
2500
Provide the module (or dotted name of the module) containing the
2501
test to be debugged and the name (within the module) of the object
2502
with the docstring with tests to be debugged.
2504
module = _normalize_module(module)
2505
testsrc = testsource(module, name)
2506
debug_script(testsrc, pm, module.__dict__)
2508
######################################################################
2510
######################################################################
2513
A pointless class, for sanity-checking of docstring testing.
2519
>>> _TestClass(13).get() + _TestClass(-12).get()
2521
>>> hex(_TestClass(13).square().get())
2525
def __init__(self, val):
2526
"""val -> _TestClass object with associated value val.
2528
>>> t = _TestClass(123)
2536
"""square() -> square TestClass's associated value
2538
>>> _TestClass(13).square().get()
2542
self.val = self.val ** 2
2546
"""get() -> return TestClass's associated value.
2548
>>> x = _TestClass(-42)
2555
__test__ = {"_TestClass": _TestClass,
2557
Example of a string object, searched as-is.
2563
"bool-int equivalence": r"""
2564
In 2.2, boolean expressions displayed
2565
0 or 1. By default, we still accept
2566
them. This can be disabled by passing
2567
DONT_ACCEPT_TRUE_FOR_1 to the new
2568
optionflags argument.
2580
Blank lines can be marked with <BLANKLINE>:
2581
>>> print('foo\n\nbar\n')
2589
If the ellipsis flag is used, then '...' can be used to
2590
elide substrings in the desired output:
2591
>>> print(list(range(1000))) #doctest: +ELLIPSIS
2595
"whitespace normalization": r"""
2596
If the whitespace normalization flag is used, then
2597
differences in whitespace are ignored.
2598
>>> print(list(range(30))) #doctest: +NORMALIZE_WHITESPACE
2599
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
2600
15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,
2606
testfiles = [arg for arg in sys.argv[1:] if arg and arg[0] != '-']
2608
for filename in testfiles:
2609
if filename.endswith(".py"):
2610
# It is a module -- insert its dir into sys.path and try to
2611
# import it. If it is part of a package, that possibly won't work
2612
# because of package imports.
2613
dirname, filename = os.path.split(filename)
2614
sys.path.insert(0, dirname)
2615
m = __import__(filename[:-3])
2617
failures, _ = testmod(m)
2619
failures, _ = testfile(filename, module_relative=False)
2623
r = unittest.TextTestRunner()
2624
r.run(DocTestSuite())
2627
if __name__ == "__main__":
added
removed
Lib/doctest.py
