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',
57
'IGNORE_EXCEPTION_DETAIL',
62
'REPORT_ONLY_FIRST_FAILURE',
64
# 1. Utility Functions
66
# 2. Example & DocTest
77
'UnexpectedException',
82
'run_docstring_examples',
88
'set_unittest_reportflags',
89
# 9. Debugging Support
90
'script_from_examples',
98
import sys, traceback, inspect, linecache, os, re, types
99
import unittest, difflib, pdb, tempfile
101
from StringIO import StringIO
103
# Don't whine about the deprecated is_private function in this
105
warnings.filterwarnings("ignore", "is_private", DeprecationWarning,
108
# There are 4 basic classes:
109
# - Example: a <source, want> pair, plus an intra-docstring line number.
110
# - DocTest: a collection of examples, parsed from a docstring, plus
111
# info about where the docstring came from (name, filename, lineno).
112
# - DocTestFinder: extracts DocTests from a given object's docstring and
113
# its contained objects' docstrings.
114
# - DocTestRunner: runs DocTest cases, and accumulates statistics.
116
# So the basic picture is:
119
# +------+ +---------+ +-------+
120
# |object| --DocTestFinder-> | DocTest | --DocTestRunner-> |results|
121
# +------+ +---------+ +-------+
129
OPTIONFLAGS_BY_NAME = {}
130
def register_optionflag(name):
131
flag = 1 << len(OPTIONFLAGS_BY_NAME)
132
OPTIONFLAGS_BY_NAME[name] = flag
135
DONT_ACCEPT_TRUE_FOR_1 = register_optionflag('DONT_ACCEPT_TRUE_FOR_1')
136
DONT_ACCEPT_BLANKLINE = register_optionflag('DONT_ACCEPT_BLANKLINE')
137
NORMALIZE_WHITESPACE = register_optionflag('NORMALIZE_WHITESPACE')
138
ELLIPSIS = register_optionflag('ELLIPSIS')
139
IGNORE_EXCEPTION_DETAIL = register_optionflag('IGNORE_EXCEPTION_DETAIL')
141
COMPARISON_FLAGS = (DONT_ACCEPT_TRUE_FOR_1 |
142
DONT_ACCEPT_BLANKLINE |
143
NORMALIZE_WHITESPACE |
145
IGNORE_EXCEPTION_DETAIL)
147
REPORT_UDIFF = register_optionflag('REPORT_UDIFF')
148
REPORT_CDIFF = register_optionflag('REPORT_CDIFF')
149
REPORT_NDIFF = register_optionflag('REPORT_NDIFF')
150
REPORT_ONLY_FIRST_FAILURE = register_optionflag('REPORT_ONLY_FIRST_FAILURE')
152
REPORTING_FLAGS = (REPORT_UDIFF |
155
REPORT_ONLY_FIRST_FAILURE)
157
# Special string markers for use in `want` strings:
158
BLANKLINE_MARKER = '<BLANKLINE>'
159
ELLIPSIS_MARKER = '...'
161
######################################################################
163
######################################################################
164
# 1. Utility Functions
165
# 2. Example & DocTest -- store test cases
166
# 3. DocTest Parser -- extracts examples from strings
167
# 4. DocTest Finder -- extracts test cases from objects
168
# 5. DocTest Runner -- runs test cases
169
# 6. Test Functions -- convenient wrappers for testing
170
# 7. Tester Class -- for backwards compatibility
171
# 8. Unittest Support
172
# 9. Debugging Support
175
######################################################################
176
## 1. Utility Functions
177
######################################################################
179
def is_private(prefix, base):
180
"""prefix, base -> true iff name prefix + "." + base is "private".
182
Prefix may be an empty string, and base does not contain a period.
183
Prefix is ignored (although functions you write conforming to this
184
protocol may make use of it).
185
Return true iff base begins with an (at least one) underscore, but
186
does not both begin and end with (at least) two underscores.
188
>>> is_private("a.b", "my_func")
190
>>> is_private("____", "_my_func")
192
>>> is_private("someclass", "__init__")
194
>>> is_private("sometypo", "__init_")
196
>>> is_private("x.y.z", "_")
198
>>> is_private("_x.y.z", "__")
200
>>> is_private("", "") # senseless but consistent
203
warnings.warn("is_private is deprecated; it wasn't useful; "
204
"examine DocTestFinder.find() lists instead",
205
DeprecationWarning, stacklevel=2)
206
return base[:1] == "_" and not base[:2] == "__" == base[-2:]
208
def _extract_future_flags(globs):
210
Return the compiler-flags associated with the future features that
211
have been imported into the given namespace (globs).
214
for fname in __future__.all_feature_names:
215
feature = globs.get(fname, None)
216
if feature is getattr(__future__, fname):
217
flags |= feature.compiler_flag
220
def _normalize_module(module, depth=2):
222
Return the module specified by `module`. In particular:
223
- If `module` is a module, then return module.
224
- If `module` is a string, then import and return the
225
module with that name.
226
- If `module` is None, then return the calling module.
227
The calling module is assumed to be the module of
228
the stack frame at the given depth in the call stack.
230
if inspect.ismodule(module):
232
elif isinstance(module, (str, unicode)):
233
return __import__(module, globals(), locals(), ["*"])
235
return sys.modules[sys._getframe(depth).f_globals['__name__']]
237
raise TypeError("Expected a module, string, or None")
239
def _indent(s, indent=4):
241
Add the given number of space characters to the beginning every
242
non-blank line in `s`, and return the result.
244
# This regexp matches the start of non-blank lines:
245
return re.sub('(?m)^(?!$)', indent*' ', s)
247
def _exception_traceback(exc_info):
249
Return a string containing a traceback message for the given
250
exc_info tuple (as returned by sys.exc_info()).
252
# Get a traceback message.
254
exc_type, exc_val, exc_tb = exc_info
255
traceback.print_exception(exc_type, exc_val, exc_tb, file=excout)
256
return excout.getvalue()
258
# Override some StringIO methods.
259
class _SpoofOut(StringIO):
261
result = StringIO.getvalue(self)
262
# If anything at all was written, make sure there's a trailing
263
# newline. There's no way for the expected output to indicate
264
# that a trailing newline is missing.
265
if result and not result.endswith("\n"):
267
# Prevent softspace from screwing up the next test case, in
268
# case they used print with a trailing comma in an example.
269
if hasattr(self, "softspace"):
273
def truncate(self, size=None):
274
StringIO.truncate(self, size)
275
if hasattr(self, "softspace"):
278
# Worst-case linear-time ellipsis matching.
279
def _ellipsis_match(want, got):
281
Essentially the only subtle case:
282
>>> _ellipsis_match('aa...aa', 'aaa')
285
if ELLIPSIS_MARKER not in want:
288
# Find "the real" strings.
289
ws = want.split(ELLIPSIS_MARKER)
292
# Deal with exact matches possibly needed at one or both ends.
293
startpos, endpos = 0, len(got)
295
if w: # starts with exact match
296
if got.startswith(w):
302
if w: # ends with exact match
309
if startpos > endpos:
310
# Exact end matches required more characters than we have, as in
311
# _ellipsis_match('aa...aa', 'aaa')
314
# For the rest, we only need to find the leftmost non-overlapping
315
# match for each piece. If there's no overall match that way alone,
316
# there's no overall match period.
318
# w may be '' at times, if there are consecutive ellipses, or
319
# due to an ellipsis at the start or end of `want`. That's OK.
320
# Search for an empty string succeeds, and doesn't change startpos.
321
startpos = got.find(w, startpos, endpos)
328
def _comment_line(line):
329
"Return a commented form of the given line"
336
class _OutputRedirectingPdb(pdb.Pdb):
338
A specialized version of the python debugger that redirects stdout
339
to a given stream when interacting with the user. Stdout is *not*
340
redirected when traced code is executed.
342
def __init__(self, out):
344
pdb.Pdb.__init__(self)
346
def trace_dispatch(self, *args):
347
# Redirect stdout to the given stream.
348
save_stdout = sys.stdout
349
sys.stdout = self.__out
350
# Call Pdb's trace dispatch method.
352
return pdb.Pdb.trace_dispatch(self, *args)
354
sys.stdout = save_stdout
356
# [XX] Normalize with respect to os.path.pardir?
357
def _module_relative_path(module, path):
358
if not inspect.ismodule(module):
359
raise TypeError, 'Expected a module: %r' % module
360
if path.startswith('/'):
361
raise ValueError, 'Module-relative files may not have absolute paths'
363
# Find the base directory for the path.
364
if hasattr(module, '__file__'):
365
# A normal module/package
366
basedir = os.path.split(module.__file__)[0]
367
elif module.__name__ == '__main__':
368
# An interactive session.
369
if len(sys.argv)>0 and sys.argv[0] != '':
370
basedir = os.path.split(sys.argv[0])[0]
374
# A module w/o __file__ (this includes builtins)
375
raise ValueError("Can't resolve paths relative to the module " +
376
module + " (it has no __file__)")
378
# Combine the base directory and the path.
379
return os.path.join(basedir, *(path.split('/')))
381
######################################################################
382
## 2. Example & DocTest
383
######################################################################
384
## - An "example" is a <source, want> pair, where "source" is a
385
## fragment of source code, and "want" is the expected output for
386
## "source." The Example class also includes information about
387
## where the example was extracted from.
389
## - A "doctest" is a collection of examples, typically extracted from
390
## a string (such as an object's docstring). The DocTest class also
391
## includes information about where the string was extracted from.
395
A single doctest example, consisting of source code and expected
396
output. `Example` defines the following attributes:
398
- source: A single Python statement, always ending with a newline.
399
The constructor adds a newline if needed.
401
- want: The expected output from running the source code (either
402
from stdout, or a traceback in case of exception). `want` ends
403
with a newline unless it's empty, in which case it's an empty
404
string. The constructor adds a newline if needed.
406
- exc_msg: The exception message generated by the example, if
407
the example is expected to generate an exception; or `None` if
408
it is not expected to generate an exception. This exception
409
message is compared against the return value of
410
`traceback.format_exception_only()`. `exc_msg` ends with a
411
newline unless it's `None`. The constructor adds a newline
414
- lineno: The line number within the DocTest string containing
415
this Example where the Example begins. This line number is
416
zero-based, with respect to the beginning of the DocTest.
418
- indent: The example's indentation in the DocTest string.
419
I.e., the number of space characters that preceed the
420
example's first prompt.
422
- options: A dictionary mapping from option flags to True or
423
False, which is used to override default options for this
424
example. Any option flags not contained in this dictionary
425
are left at their default value (as specified by the
426
DocTestRunner's optionflags). By default, no options are set.
428
def __init__(self, source, want, exc_msg=None, lineno=0, indent=0,
431
if not source.endswith('\n'):
433
if want and not want.endswith('\n'):
435
if exc_msg is not None and not exc_msg.endswith('\n'):
442
if options is None: options = {}
443
self.options = options
444
self.exc_msg = exc_msg
448
A collection of doctest examples that should be run in a single
449
namespace. Each `DocTest` defines the following attributes:
451
- examples: the list of examples.
453
- globs: The namespace (aka globals) that the examples should
456
- name: A name identifying the DocTest (typically, the name of
457
the object whose docstring this DocTest was extracted from).
459
- filename: The name of the file that this DocTest was extracted
460
from, or `None` if the filename is unknown.
462
- lineno: The line number within filename where this DocTest
463
begins, or `None` if the line number is unavailable. This
464
line number is zero-based, with respect to the beginning of
467
- docstring: The string that the examples were extracted from,
468
or `None` if the string is unavailable.
470
def __init__(self, examples, globs, name, filename, lineno, docstring):
472
Create a new DocTest containing the given examples. The
473
DocTest's globals are initialized with a copy of `globs`.
475
assert not isinstance(examples, basestring), \
476
"DocTest no longer accepts str; use DocTestParser instead"
477
self.examples = examples
478
self.docstring = docstring
479
self.globs = globs.copy()
481
self.filename = filename
485
if len(self.examples) == 0:
486
examples = 'no examples'
487
elif len(self.examples) == 1:
488
examples = '1 example'
490
examples = '%d examples' % len(self.examples)
491
return ('<DocTest %s from %s:%s (%s)>' %
492
(self.name, self.filename, self.lineno, examples))
495
# This lets us sort tests by name:
496
def __cmp__(self, other):
497
if not isinstance(other, DocTest):
499
return cmp((self.name, self.filename, self.lineno, id(self)),
500
(other.name, other.filename, other.lineno, id(other)))
502
######################################################################
504
######################################################################
508
A class used to parse strings containing doctest examples.
510
# This regular expression is used to find doctest examples in a
511
# string. It defines three groups: `source` is the source code
512
# (including leading indentation and prompts); `indent` is the
513
# indentation of the first (PS1) line of the source code; and
514
# `want` is the expected output (including leading indentation).
515
_EXAMPLE_RE = re.compile(r'''
516
# Source consists of a PS1 line followed by zero or more PS2 lines.
518
(?:^(?P<indent> [ ]*) >>> .*) # PS1 line
519
(?:\n [ ]* \.\.\. .*)*) # PS2 lines
521
# Want consists of any non-blank lines that do not start with PS1.
522
(?P<want> (?:(?![ ]*$) # Not a blank line
523
(?![ ]*>>>) # Not a line starting with PS1
524
.*$\n? # But any other line
526
''', re.MULTILINE | re.VERBOSE)
528
# A regular expression for handling `want` strings that contain
529
# expected exceptions. It divides `want` into three pieces:
530
# - the traceback header line (`hdr`)
531
# - the traceback stack (`stack`)
532
# - the exception message (`msg`), as generated by
533
# traceback.format_exception_only()
534
# `msg` may have multiple lines. We assume/require that the
535
# exception message is the first non-indented line starting with a word
536
# character following the traceback header line.
537
_EXCEPTION_RE = re.compile(r"""
538
# Grab the traceback header. Different versions of Python have
539
# said different things on the first traceback line.
540
^(?P<hdr> Traceback\ \(
541
(?: most\ recent\ call\ last
545
\s* $ # toss trailing whitespace on the header.
546
(?P<stack> .*?) # don't blink: absorb stuff until...
547
^ (?P<msg> \w+ .*) # a line *starts* with alphanum.
548
""", re.VERBOSE | re.MULTILINE | re.DOTALL)
550
# A callable returning a true value iff its argument is a blank line
551
# or contains a single comment.
552
_IS_BLANK_OR_COMMENT = re.compile(r'^[ ]*(#.*)?$').match
554
def parse(self, string, name='<string>'):
556
Divide the given string into examples and intervening text,
557
and return them as a list of alternating Examples and strings.
558
Line numbers for the Examples are 0-based. The optional
559
argument `name` is a name identifying this string, and is only
560
used for error messages.
562
string = string.expandtabs()
563
# If all lines begin with the same indentation, then strip it.
564
min_indent = self._min_indent(string)
566
string = '\n'.join([l[min_indent:] for l in string.split('\n')])
569
charno, lineno = 0, 0
570
# Find all doctest examples in the string:
571
for m in self._EXAMPLE_RE.finditer(string):
572
# Add the pre-example text to `output`.
573
output.append(string[charno:m.start()])
574
# Update lineno (lines before this example)
575
lineno += string.count('\n', charno, m.start())
576
# Extract info from the regexp match.
577
(source, options, want, exc_msg) = \
578
self._parse_example(m, name, lineno)
579
# Create an Example, and add it to the list.
580
if not self._IS_BLANK_OR_COMMENT(source):
581
output.append( Example(source, want, exc_msg,
583
indent=min_indent+len(m.group('indent')),
585
# Update lineno (lines inside this example)
586
lineno += string.count('\n', m.start(), m.end())
589
# Add any remaining post-example text to `output`.
590
output.append(string[charno:])
593
def get_doctest(self, string, globs, name, filename, lineno):
595
Extract all doctest examples from the given string, and
596
collect them into a `DocTest` object.
598
`globs`, `name`, `filename`, and `lineno` are attributes for
599
the new `DocTest` object. See the documentation for `DocTest`
600
for more information.
602
return DocTest(self.get_examples(string, name), globs,
603
name, filename, lineno, string)
605
def get_examples(self, string, name='<string>'):
607
Extract all doctest examples from the given string, and return
608
them as a list of `Example` objects. Line numbers are
609
0-based, because it's most common in doctests that nothing
610
interesting appears on the same line as opening triple-quote,
611
and so the first interesting line is called \"line 1\" then.
613
The optional argument `name` is a name identifying this
614
string, and is only used for error messages.
616
return [x for x in self.parse(string, name)
617
if isinstance(x, Example)]
619
def _parse_example(self, m, name, lineno):
621
Given a regular expression match from `_EXAMPLE_RE` (`m`),
622
return a pair `(source, want)`, where `source` is the matched
623
example's source code (with prompts and indentation stripped);
624
and `want` is the example's expected output (with indentation
627
`name` is the string's name, and `lineno` is the line number
628
where the example starts; both are used for error messages.
630
# Get the example's indentation level.
631
indent = len(m.group('indent'))
633
# Divide source into lines; check that they're properly
634
# indented; and then strip their indentation & prompts.
635
source_lines = m.group('source').split('\n')
636
self._check_prompt_blank(source_lines, indent, name, lineno)
637
self._check_prefix(source_lines[1:], ' '*indent + '.', name, lineno)
638
source = '\n'.join([sl[indent+4:] for sl in source_lines])
640
# Divide want into lines; check that it's properly indented; and
641
# then strip the indentation. Spaces before the last newline should
642
# be preserved, so plain rstrip() isn't good enough.
643
want = m.group('want')
644
want_lines = want.split('\n')
645
if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]):
646
del want_lines[-1] # forget final newline & spaces after it
647
self._check_prefix(want_lines, ' '*indent, name,
648
lineno + len(source_lines))
649
want = '\n'.join([wl[indent:] for wl in want_lines])
651
# If `want` contains a traceback message, then extract it.
652
m = self._EXCEPTION_RE.match(want)
654
exc_msg = m.group('msg')
658
# Extract options from the source.
659
options = self._find_options(source, name, lineno)
661
return source, options, want, exc_msg
663
# This regular expression looks for option directives in the
664
# source code of an example. Option directives are comments
665
# starting with "doctest:". Warning: this may give false
666
# positives for string-literals that contain the string
667
# "#doctest:". Eliminating these false positives would require
668
# actually parsing the string; but we limit them by ignoring any
669
# line containing "#doctest:" that is *followed* by a quote mark.
670
_OPTION_DIRECTIVE_RE = re.compile(r'#\s*doctest:\s*([^\n\'"]*)$',
673
def _find_options(self, source, name, lineno):
675
Return a dictionary containing option overrides extracted from
676
option directives in the given source string.
678
`name` is the string's name, and `lineno` is the line number
679
where the example starts; both are used for error messages.
682
# (note: with the current regexp, this will match at most once:)
683
for m in self._OPTION_DIRECTIVE_RE.finditer(source):
684
option_strings = m.group(1).replace(',', ' ').split()
685
for option in option_strings:
686
if (option[0] not in '+-' or
687
option[1:] not in OPTIONFLAGS_BY_NAME):
688
raise ValueError('line %r of the doctest for %s '
689
'has an invalid option: %r' %
690
(lineno+1, name, option))
691
flag = OPTIONFLAGS_BY_NAME[option[1:]]
692
options[flag] = (option[0] == '+')
693
if options and self._IS_BLANK_OR_COMMENT(source):
694
raise ValueError('line %r of the doctest for %s has an option '
695
'directive on a line with no example: %r' %
696
(lineno, name, source))
699
# This regular expression finds the indentation of every non-blank
701
_INDENT_RE = re.compile('^([ ]*)(?=\S)', re.MULTILINE)
703
def _min_indent(self, s):
704
"Return the minimum indentation of any non-blank line in `s`"
705
indents = [len(indent) for indent in self._INDENT_RE.findall(s)]
711
def _check_prompt_blank(self, lines, indent, name, lineno):
713
Given the lines of a source string (including prompts and
714
leading indentation), check to make sure that every prompt is
715
followed by a space character. If any line is not followed by
716
a space character, then raise ValueError.
718
for i, line in enumerate(lines):
719
if len(line) >= indent+4 and line[indent+3] != ' ':
720
raise ValueError('line %r of the docstring for %s '
721
'lacks blank after %s: %r' %
723
line[indent:indent+3], line))
725
def _check_prefix(self, lines, prefix, name, lineno):
727
Check that every line in the given list starts with the given
728
prefix; if any line does not, then raise a ValueError.
730
for i, line in enumerate(lines):
731
if line and not line.startswith(prefix):
732
raise ValueError('line %r of the docstring for %s has '
733
'inconsistent leading whitespace: %r' %
734
(lineno+i+1, name, line))
737
######################################################################
739
######################################################################
743
A class used to extract the DocTests that are relevant to a given
744
object, from its docstring and the docstrings of its contained
745
objects. Doctests can currently be extracted from the following
746
object types: modules, functions, classes, methods, staticmethods,
747
classmethods, and properties.
750
def __init__(self, verbose=False, parser=DocTestParser(),
751
recurse=True, _namefilter=None, exclude_empty=True):
753
Create a new doctest finder.
755
The optional argument `parser` specifies a class or
756
function that should be used to create new DocTest objects (or
757
objects that implement the same interface as DocTest). The
758
signature for this factory function should match the signature
759
of the DocTest constructor.
761
If the optional argument `recurse` is false, then `find` will
762
only examine the given object, and not any contained objects.
764
If the optional argument `exclude_empty` is false, then `find`
765
will include tests for objects with empty docstrings.
767
self._parser = parser
768
self._verbose = verbose
769
self._recurse = recurse
770
self._exclude_empty = exclude_empty
771
# _namefilter is undocumented, and exists only for temporary backward-
772
# compatibility support of testmod's deprecated isprivate mess.
773
self._namefilter = _namefilter
775
def find(self, obj, name=None, module=None, globs=None,
778
Return a list of the DocTests that are defined by the given
779
object's docstring, or by any of its contained objects'
782
The optional parameter `module` is the module that contains
783
the given object. If the module is not specified or is None, then
784
the test finder will attempt to automatically determine the
785
correct module. The object's module is used:
787
- As a default namespace, if `globs` is not specified.
788
- To prevent the DocTestFinder from extracting DocTests
789
from objects that are imported from other modules.
790
- To find the name of the file containing the object.
791
- To help find the line number of the object within its
794
Contained objects whose module does not match `module` are ignored.
796
If `module` is False, no attempt to find the module will be made.
797
This is obscure, of use mostly in tests: if `module` is False, or
798
is None but cannot be found automatically, then all objects are
799
considered to belong to the (non-existent) module, so all contained
800
objects will (recursively) be searched for doctests.
802
The globals for each DocTest is formed by combining `globs`
803
and `extraglobs` (bindings in `extraglobs` override bindings
804
in `globs`). A new copy of the globals dictionary is created
805
for each DocTest. If `globs` is not specified, then it
806
defaults to the module's `__dict__`, if specified, or {}
807
otherwise. If `extraglobs` is not specified, then it defaults
811
# If name was not specified, then extract it from the object.
813
name = getattr(obj, '__name__', None)
815
raise ValueError("DocTestFinder.find: name must be given "
816
"when obj.__name__ doesn't exist: %r" %
819
# Find the module that contains the given object (if obj is
820
# a module, then module=obj.). Note: this may fail, in which
821
# case module will be None.
825
module = inspect.getmodule(obj)
827
# Read the module's source code. This is used by
828
# DocTestFinder._find_lineno to find the line number for a
829
# given object's docstring.
831
file = inspect.getsourcefile(obj) or inspect.getfile(obj)
832
source_lines = linecache.getlines(file)
838
# Initialize globals, and merge in extraglobs.
843
globs = module.__dict__.copy()
846
if extraglobs is not None:
847
globs.update(extraglobs)
849
# Recursively explore `obj`, extracting DocTests.
851
self._find(tests, obj, name, module, source_lines, globs, {})
854
def _filter(self, obj, prefix, base):
856
Return true if the given object should not be examined.
858
return (self._namefilter is not None and
859
self._namefilter(prefix, base))
861
def _from_module(self, module, object):
863
Return true if the given object is defined in the given
868
elif inspect.isfunction(object):
869
return module.__dict__ is object.func_globals
870
elif inspect.isclass(object):
871
return module.__name__ == object.__module__
872
elif inspect.getmodule(object) is not None:
873
return module is inspect.getmodule(object)
874
elif hasattr(object, '__module__'):
875
return module.__name__ == object.__module__
876
elif isinstance(object, property):
877
return True # [XX] no way not be sure.
879
raise ValueError("object must be a class or function")
881
def _find(self, tests, obj, name, module, source_lines, globs, seen):
883
Find tests for the given object and any contained objects, and
887
print 'Finding tests in %s' % name
889
# If we've already processed this object, then ignore it.
894
# Find a test for this object, and add it to the list of tests.
895
test = self._get_test(obj, name, module, globs, source_lines)
899
# Look for tests in a module's contained objects.
900
if inspect.ismodule(obj) and self._recurse:
901
for valname, val in obj.__dict__.items():
902
# Check if this contained object should be ignored.
903
if self._filter(val, name, valname):
905
valname = '%s.%s' % (name, valname)
906
# Recurse to functions & classes.
907
if ((inspect.isfunction(val) or inspect.isclass(val)) and
908
self._from_module(module, val)):
909
self._find(tests, val, valname, module, source_lines,
912
# Look for tests in a module's __test__ dictionary.
913
if inspect.ismodule(obj) and self._recurse:
914
for valname, val in getattr(obj, '__test__', {}).items():
915
if not isinstance(valname, basestring):
916
raise ValueError("DocTestFinder.find: __test__ keys "
917
"must be strings: %r" %
919
if not (inspect.isfunction(val) or inspect.isclass(val) or
920
inspect.ismethod(val) or inspect.ismodule(val) or
921
isinstance(val, basestring)):
922
raise ValueError("DocTestFinder.find: __test__ values "
923
"must be strings, functions, methods, "
924
"classes, or modules: %r" %
926
valname = '%s.__test__.%s' % (name, valname)
927
self._find(tests, val, valname, module, source_lines,
930
# Look for tests in a class's contained objects.
931
if inspect.isclass(obj) and self._recurse:
932
for valname, val in obj.__dict__.items():
933
# Check if this contained object should be ignored.
934
if self._filter(val, name, valname):
936
# Special handling for staticmethod/classmethod.
937
if isinstance(val, staticmethod):
938
val = getattr(obj, valname)
939
if isinstance(val, classmethod):
940
val = getattr(obj, valname).im_func
942
# Recurse to methods, properties, and nested classes.
943
if ((inspect.isfunction(val) or inspect.isclass(val) or
944
isinstance(val, property)) and
945
self._from_module(module, val)):
946
valname = '%s.%s' % (name, valname)
947
self._find(tests, val, valname, module, source_lines,
950
def _get_test(self, obj, name, module, globs, source_lines):
952
Return a DocTest for the given object, if it defines a docstring;
953
otherwise, return None.
955
# Extract the object's docstring. If it doesn't have one,
956
# then return None (no test for this object).
957
if isinstance(obj, basestring):
961
if obj.__doc__ is None:
964
docstring = obj.__doc__
965
if not isinstance(docstring, basestring):
966
docstring = str(docstring)
967
except (TypeError, AttributeError):
970
# Find the docstring's location in the file.
971
lineno = self._find_lineno(obj, source_lines)
973
# Don't bother if the docstring is empty.
974
if self._exclude_empty and not docstring:
977
# Return a DocTest for this object.
981
filename = getattr(module, '__file__', module.__name__)
982
if filename[-4:] in (".pyc", ".pyo"):
983
filename = filename[:-1]
984
return self._parser.get_doctest(docstring, globs, name,
987
def _find_lineno(self, obj, source_lines):
989
Return a line number of the given object's docstring. Note:
990
this method assumes that the object has a docstring.
994
# Find the line number for modules.
995
if inspect.ismodule(obj):
998
# Find the line number for classes.
999
# Note: this could be fooled if a class is defined multiple
1000
# times in a single file.
1001
if inspect.isclass(obj):
1002
if source_lines is None:
1004
pat = re.compile(r'^\s*class\s*%s\b' %
1005
getattr(obj, '__name__', '-'))
1006
for i, line in enumerate(source_lines):
1011
# Find the line number for functions & methods.
1012
if inspect.ismethod(obj): obj = obj.im_func
1013
if inspect.isfunction(obj): obj = obj.func_code
1014
if inspect.istraceback(obj): obj = obj.tb_frame
1015
if inspect.isframe(obj): obj = obj.f_code
1016
if inspect.iscode(obj):
1017
lineno = getattr(obj, 'co_firstlineno', None)-1
1019
# Find the line number where the docstring starts. Assume
1020
# that it's the first line that begins with a quote mark.
1021
# Note: this could be fooled by a multiline function
1022
# signature, where a continuation line begins with a quote
1024
if lineno is not None:
1025
if source_lines is None:
1027
pat = re.compile('(^|.*:)\s*\w*("|\')')
1028
for lineno in range(lineno, len(source_lines)):
1029
if pat.match(source_lines[lineno]):
1032
# We couldn't find the line number.
1035
######################################################################
1036
## 5. DocTest Runner
1037
######################################################################
1039
class DocTestRunner:
1041
A class used to run DocTest test cases, and accumulate statistics.
1042
The `run` method is used to process a single DocTest case. It
1043
returns a tuple `(f, t)`, where `t` is the number of test cases
1044
tried, and `f` is the number of test cases that failed.
1046
>>> tests = DocTestFinder().find(_TestClass)
1047
>>> runner = DocTestRunner(verbose=False)
1048
>>> for test in tests:
1049
... print runner.run(test)
1055
The `summarize` method prints a summary of all the test cases that
1056
have been run by the runner, and returns an aggregated `(f, t)`
1059
>>> runner.summarize(verbose=1)
1060
4 items passed all tests:
1061
2 tests in _TestClass
1062
2 tests in _TestClass.__init__
1063
2 tests in _TestClass.get
1064
1 tests in _TestClass.square
1066
7 passed and 0 failed.
1070
The aggregated number of tried examples and failed examples is
1071
also available via the `tries` and `failures` attributes:
1078
The comparison between expected outputs and actual outputs is done
1079
by an `OutputChecker`. This comparison may be customized with a
1080
number of option flags; see the documentation for `testmod` for
1081
more information. If the option flags are insufficient, then the
1082
comparison may also be customized by passing a subclass of
1083
`OutputChecker` to the constructor.
1085
The test runner's display output can be controlled in two ways.
1086
First, an output function (`out) can be passed to
1087
`TestRunner.run`; this function will be called with strings that
1088
should be displayed. It defaults to `sys.stdout.write`. If
1089
capturing the output is not sufficient, then the display output
1090
can be also customized by subclassing DocTestRunner, and
1091
overriding the methods `report_start`, `report_success`,
1092
`report_unexpected_exception`, and `report_failure`.
1094
# This divider string is used to separate failure messages, and to
1095
# separate sections of the summary.
1098
def __init__(self, checker=None, verbose=None, optionflags=0):
1100
Create a new test runner.
1102
Optional keyword arg `checker` is the `OutputChecker` that
1103
should be used to compare the expected outputs and actual
1104
outputs of doctest examples.
1106
Optional keyword arg 'verbose' prints lots of stuff if true,
1107
only failures if false; by default, it's true iff '-v' is in
1110
Optional argument `optionflags` can be used to control how the
1111
test runner compares expected output to actual output, and how
1112
it displays failures. See the documentation for `testmod` for
1115
self._checker = checker or OutputChecker()
1117
verbose = '-v' in sys.argv
1118
self._verbose = verbose
1119
self.optionflags = optionflags
1120
self.original_optionflags = optionflags
1122
# Keep track of the examples we've run.
1127
# Create a fake output target for capturing doctest output.
1128
self._fakeout = _SpoofOut()
1130
#/////////////////////////////////////////////////////////////////
1132
#/////////////////////////////////////////////////////////////////
1134
def report_start(self, out, test, example):
1136
Report that the test runner is about to process the given
1137
example. (Only displays a message if verbose=True)
1141
out('Trying:\n' + _indent(example.source) +
1142
'Expecting:\n' + _indent(example.want))
1144
out('Trying:\n' + _indent(example.source) +
1145
'Expecting nothing\n')
1147
def report_success(self, out, test, example, got):
1149
Report that the given example ran successfully. (Only
1150
displays a message if verbose=True)
1155
def report_failure(self, out, test, example, got):
1157
Report that the given example failed.
1159
out(self._failure_header(test, example) +
1160
self._checker.output_difference(example, got, self.optionflags))
1162
def report_unexpected_exception(self, out, test, example, exc_info):
1164
Report that the given example raised an unexpected exception.
1166
out(self._failure_header(test, example) +
1167
'Exception raised:\n' + _indent(_exception_traceback(exc_info)))
1169
def _failure_header(self, test, example):
1170
out = [self.DIVIDER]
1172
if test.lineno is not None and example.lineno is not None:
1173
lineno = test.lineno + example.lineno + 1
1176
out.append('File "%s", line %s, in %s' %
1177
(test.filename, lineno, test.name))
1179
out.append('Line %s, in %s' % (example.lineno+1, test.name))
1180
out.append('Failed example:')
1181
source = example.source
1182
out.append(_indent(source))
1183
return '\n'.join(out)
1185
#/////////////////////////////////////////////////////////////////
1187
#/////////////////////////////////////////////////////////////////
1189
def __run(self, test, compileflags, out):
1191
Run the examples in `test`. Write the outcome of each example
1192
with one of the `DocTestRunner.report_*` methods, using the
1193
writer function `out`. `compileflags` is the set of compiler
1194
flags that should be used to execute examples. Return a tuple
1195
`(f, t)`, where `t` is the number of examples tried, and `f`
1196
is the number of examples that failed. The examples are run
1197
in the namespace `test.globs`.
1199
# Keep track of the number of failures and tries.
1200
failures = tries = 0
1202
# Save the option flags (since option directives can be used
1204
original_optionflags = self.optionflags
1206
SUCCESS, FAILURE, BOOM = range(3) # `outcome` state
1208
check = self._checker.check_output
1210
# Process each example.
1211
for examplenum, example in enumerate(test.examples):
1213
# If REPORT_ONLY_FIRST_FAILURE is set, then suppress
1214
# reporting after the first failure.
1215
quiet = (self.optionflags & REPORT_ONLY_FIRST_FAILURE and
1218
# Merge in the example's options.
1219
self.optionflags = original_optionflags
1221
for (optionflag, val) in example.options.items():
1223
self.optionflags |= optionflag
1225
self.optionflags &= ~optionflag
1227
# Record that we started this example.
1230
self.report_start(out, test, example)
1232
# Use a special filename for compile(), so we can retrieve
1233
# the source code during interactive debugging (see
1234
# __patched_linecache_getlines).
1235
filename = '<doctest %s[%d]>' % (test.name, examplenum)
1237
# Run the example in the given context (globs), and record
1238
# any exception that gets raised. (But don't intercept
1239
# keyboard interrupts.)
1241
# Don't blink! This is where the user's code gets run.
1242
exec compile(example.source, filename, "single",
1243
compileflags, 1) in test.globs
1244
self.debugger.set_continue() # ==== Example Finished ====
1246
except KeyboardInterrupt:
1249
exception = sys.exc_info()
1250
self.debugger.set_continue() # ==== Example Finished ====
1252
got = self._fakeout.getvalue() # the actual output
1253
self._fakeout.truncate(0)
1254
outcome = FAILURE # guilty until proved innocent or insane
1256
# If the example executed without raising any exceptions,
1257
# verify its output.
1258
if exception is None:
1259
if check(example.want, got, self.optionflags):
1262
# The example raised an exception: check if it was expected.
1264
exc_info = sys.exc_info()
1265
exc_msg = traceback.format_exception_only(*exc_info[:2])[-1]
1267
got += _exception_traceback(exc_info)
1269
# If `example.exc_msg` is None, then we weren't expecting
1271
if example.exc_msg is None:
1274
# We expected an exception: see whether it matches.
1275
elif check(example.exc_msg, exc_msg, self.optionflags):
1278
# Another chance if they didn't care about the detail.
1279
elif self.optionflags & IGNORE_EXCEPTION_DETAIL:
1280
m1 = re.match(r'[^:]*:', example.exc_msg)
1281
m2 = re.match(r'[^:]*:', exc_msg)
1282
if m1 and m2 and check(m1.group(0), m2.group(0),
1286
# Report the outcome.
1287
if outcome is SUCCESS:
1289
self.report_success(out, test, example, got)
1290
elif outcome is FAILURE:
1292
self.report_failure(out, test, example, got)
1294
elif outcome is BOOM:
1296
self.report_unexpected_exception(out, test, example,
1300
assert False, ("unknown outcome", outcome)
1302
# Restore the option flags (in case they were modified)
1303
self.optionflags = original_optionflags
1305
# Record and return the number of failures and tries.
1306
self.__record_outcome(test, failures, tries)
1307
return failures, tries
1309
def __record_outcome(self, test, f, t):
1311
Record the fact that the given DocTest (`test`) generated `f`
1312
failures out of `t` tried examples.
1314
f2, t2 = self._name2ft.get(test.name, (0,0))
1315
self._name2ft[test.name] = (f+f2, t+t2)
1319
__LINECACHE_FILENAME_RE = re.compile(r'<doctest '
1320
r'(?P<name>[\w\.]+)'
1321
r'\[(?P<examplenum>\d+)\]>$')
1322
def __patched_linecache_getlines(self, filename, module_globals=None):
1323
m = self.__LINECACHE_FILENAME_RE.match(filename)
1324
if m and m.group('name') == self.test.name:
1325
example = self.test.examples[int(m.group('examplenum'))]
1326
return example.source.splitlines(True)
1328
if sys.version_info < (2, 5, 0):
1329
return self.save_linecache_getlines(filename)
1331
return self.save_linecache_getlines(filename, module_globals)
1333
def run(self, test, compileflags=None, out=None, clear_globs=True):
1335
Run the examples in `test`, and display the results using the
1336
writer function `out`.
1338
The examples are run in the namespace `test.globs`. If
1339
`clear_globs` is true (the default), then this namespace will
1340
be cleared after the test runs, to help with garbage
1341
collection. If you would like to examine the namespace after
1342
the test completes, then use `clear_globs=False`.
1344
`compileflags` gives the set of flags that should be used by
1345
the Python compiler when running the examples. If not
1346
specified, then it will default to the set of future-import
1347
flags that apply to `globs`.
1349
The output of each example is checked using
1350
`DocTestRunner.check_output`, and the results are formatted by
1351
the `DocTestRunner.report_*` methods.
1355
if compileflags is None:
1356
compileflags = _extract_future_flags(test.globs)
1358
save_stdout = sys.stdout
1360
out = save_stdout.write
1361
sys.stdout = self._fakeout
1363
# Patch pdb.set_trace to restore sys.stdout during interactive
1364
# debugging (so it's not still redirected to self._fakeout).
1365
# Note that the interactive output will go to *our*
1366
# save_stdout, even if that's not the real sys.stdout; this
1367
# allows us to write test cases for the set_trace behavior.
1368
save_set_trace = pdb.set_trace
1369
self.debugger = _OutputRedirectingPdb(save_stdout)
1370
self.debugger.reset()
1371
pdb.set_trace = self.debugger.set_trace
1373
# Patch linecache.getlines, so we can see the example's source
1374
# when we're inside the debugger.
1375
self.save_linecache_getlines = linecache.getlines
1376
linecache.getlines = self.__patched_linecache_getlines
1379
return self.__run(test, compileflags, out)
1381
sys.stdout = save_stdout
1382
pdb.set_trace = save_set_trace
1383
linecache.getlines = self.save_linecache_getlines
1387
#/////////////////////////////////////////////////////////////////
1389
#/////////////////////////////////////////////////////////////////
1390
def summarize(self, verbose=None):
1392
Print a summary of all the test cases that have been run by
1393
this DocTestRunner, and return a tuple `(f, t)`, where `f` is
1394
the total number of failed examples, and `t` is the total
1395
number of tried examples.
1397
The optional `verbose` argument controls how detailed the
1398
summary is. If the verbosity is not specified, then the
1399
DocTestRunner's verbosity is used.
1402
verbose = self._verbose
1407
for x in self._name2ft.items():
1413
notests.append(name)
1415
passed.append( (name, t) )
1420
print len(notests), "items had no tests:"
1422
for thing in notests:
1425
print len(passed), "items passed all tests:"
1427
for thing, count in passed:
1428
print " %3d tests in %s" % (count, thing)
1431
print len(failed), "items had failures:"
1433
for thing, (f, t) in failed:
1434
print " %3d of %3d in %s" % (f, t, thing)
1436
print totalt, "tests in", len(self._name2ft), "items."
1437
print totalt - totalf, "passed and", totalf, "failed."
1439
print "***Test Failed***", totalf, "failures."
1441
print "Test passed."
1442
return totalf, totalt
1444
#/////////////////////////////////////////////////////////////////
1445
# Backward compatibility cruft to maintain doctest.master.
1446
#/////////////////////////////////////////////////////////////////
1447
def merge(self, other):
1449
for name, (f, t) in other._name2ft.items():
1451
print "*** DocTestRunner.merge: '" + name + "' in both" \
1452
" testers; summing outcomes."
1458
class OutputChecker:
1460
A class used to check the whether the actual output from a doctest
1461
example matches the expected output. `OutputChecker` defines two
1462
methods: `check_output`, which compares a given pair of outputs,
1463
and returns true if they match; and `output_difference`, which
1464
returns a string describing the differences between two outputs.
1466
def check_output(self, want, got, optionflags):
1468
Return True iff the actual output from an example (`got`)
1469
matches the expected output (`want`). These strings are
1470
always considered to match if they are identical; but
1471
depending on what option flags the test runner is using,
1472
several non-exact match types are also possible. See the
1473
documentation for `TestRunner` for more information about
1476
# Handle the common case first, for efficiency:
1477
# if they're string-identical, always return true.
1481
# The values True and False replaced 1 and 0 as the return
1482
# value for boolean comparisons in Python 2.3.
1483
if not (optionflags & DONT_ACCEPT_TRUE_FOR_1):
1484
if (got,want) == ("True\n", "1\n"):
1486
if (got,want) == ("False\n", "0\n"):
1489
# <BLANKLINE> can be used as a special sequence to signify a
1490
# blank line, unless the DONT_ACCEPT_BLANKLINE flag is used.
1491
if not (optionflags & DONT_ACCEPT_BLANKLINE):
1492
# Replace <BLANKLINE> in want with a blank line.
1493
want = re.sub('(?m)^%s\s*?$' % re.escape(BLANKLINE_MARKER),
1495
# If a line in got contains only spaces, then remove the
1497
got = re.sub('(?m)^\s*?$', '', got)
1501
# This flag causes doctest to ignore any differences in the
1502
# contents of whitespace strings. Note that this can be used
1503
# in conjunction with the ELLIPSIS flag.
1504
if optionflags & NORMALIZE_WHITESPACE:
1505
got = ' '.join(got.split())
1506
want = ' '.join(want.split())
1510
# The ELLIPSIS flag says to let the sequence "..." in `want`
1511
# match any substring in `got`.
1512
if optionflags & ELLIPSIS:
1513
if _ellipsis_match(want, got):
1516
# We didn't find any match; return false.
1519
# Should we do a fancy diff?
1520
def _do_a_fancy_diff(self, want, got, optionflags):
1521
# Not unless they asked for a fancy diff.
1522
if not optionflags & (REPORT_UDIFF |
1527
# If expected output uses ellipsis, a meaningful fancy diff is
1528
# too hard ... or maybe not. In two real-life failures Tim saw,
1529
# a diff was a major help anyway, so this is commented out.
1530
# [todo] _ellipsis_match() knows which pieces do and don't match,
1531
# and could be the basis for a kick-ass diff in this case.
1532
##if optionflags & ELLIPSIS and ELLIPSIS_MARKER in want:
1535
# ndiff does intraline difference marking, so can be useful even
1536
# for 1-line differences.
1537
if optionflags & REPORT_NDIFF:
1540
# The other diff types need at least a few lines to be helpful.
1541
return want.count('\n') > 2 and got.count('\n') > 2
1543
def output_difference(self, example, got, optionflags):
1545
Return a string describing the differences between the
1546
expected output for a given example (`example`) and the actual
1547
output (`got`). `optionflags` is the set of option flags used
1548
to compare `want` and `got`.
1551
# If <BLANKLINE>s are being used, then replace blank lines
1552
# with <BLANKLINE> in the actual output string.
1553
if not (optionflags & DONT_ACCEPT_BLANKLINE):
1554
got = re.sub('(?m)^[ ]*(?=\n)', BLANKLINE_MARKER, got)
1556
# Check if we should use diff.
1557
if self._do_a_fancy_diff(want, got, optionflags):
1558
# Split want & got into lines.
1559
want_lines = want.splitlines(True) # True == keep line ends
1560
got_lines = got.splitlines(True)
1561
# Use difflib to find their differences.
1562
if optionflags & REPORT_UDIFF:
1563
diff = difflib.unified_diff(want_lines, got_lines, n=2)
1564
diff = list(diff)[2:] # strip the diff header
1565
kind = 'unified diff with -expected +actual'
1566
elif optionflags & REPORT_CDIFF:
1567
diff = difflib.context_diff(want_lines, got_lines, n=2)
1568
diff = list(diff)[2:] # strip the diff header
1569
kind = 'context diff with expected followed by actual'
1570
elif optionflags & REPORT_NDIFF:
1571
engine = difflib.Differ(charjunk=difflib.IS_CHARACTER_JUNK)
1572
diff = list(engine.compare(want_lines, got_lines))
1573
kind = 'ndiff with -expected +actual'
1575
assert 0, 'Bad diff option'
1576
# Remove trailing whitespace on diff output.
1577
diff = [line.rstrip() + '\n' for line in diff]
1578
return 'Differences (%s):\n' % kind + _indent(''.join(diff))
1580
# If we're not using diff, then simply list the expected
1581
# output followed by the actual output.
1583
return 'Expected:\n%sGot:\n%s' % (_indent(want), _indent(got))
1585
return 'Expected:\n%sGot nothing\n' % _indent(want)
1587
return 'Expected nothing\nGot:\n%s' % _indent(got)
1589
return 'Expected nothing\nGot nothing\n'
1591
class DocTestFailure(Exception):
1592
"""A DocTest example has failed in debugging mode.
1594
The exception instance has variables:
1596
- test: the DocTest object being run
1598
- excample: the Example object that failed
1600
- got: the actual output
1602
def __init__(self, test, example, got):
1604
self.example = example
1608
return str(self.test)
1610
class UnexpectedException(Exception):
1611
"""A DocTest example has encountered an unexpected exception
1613
The exception instance has variables:
1615
- test: the DocTest object being run
1617
- excample: the Example object that failed
1619
- exc_info: the exception info
1621
def __init__(self, test, example, exc_info):
1623
self.example = example
1624
self.exc_info = exc_info
1627
return str(self.test)
1629
class DebugRunner(DocTestRunner):
1630
r"""Run doc tests but raise an exception as soon as there is a failure.
1632
If an unexpected exception occurs, an UnexpectedException is raised.
1633
It contains the test, the example, and the original exception:
1635
>>> runner = DebugRunner(verbose=False)
1636
>>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
1637
... {}, 'foo', 'foo.py', 0)
1639
... runner.run(test)
1640
... except UnexpectedException, failure:
1643
>>> failure.test is test
1646
>>> failure.example.want
1649
>>> exc_info = failure.exc_info
1650
>>> raise exc_info[0], exc_info[1], exc_info[2]
1651
Traceback (most recent call last):
1655
We wrap the original exception to give the calling application
1656
access to the test and example information.
1658
If the output doesn't match, then a DocTestFailure is raised:
1660
>>> test = DocTestParser().get_doctest('''
1664
... ''', {}, 'foo', 'foo.py', 0)
1667
... runner.run(test)
1668
... except DocTestFailure, failure:
1671
DocTestFailure objects provide access to the test:
1673
>>> failure.test is test
1676
As well as to the example:
1678
>>> failure.example.want
1681
and the actual output:
1686
If a failure or error occurs, the globals are left intact:
1688
>>> del test.globs['__builtins__']
1692
>>> test = DocTestParser().get_doctest('''
1694
... >>> raise KeyError
1695
... ''', {}, 'foo', 'foo.py', 0)
1697
>>> runner.run(test)
1698
Traceback (most recent call last):
1700
UnexpectedException: <DocTest foo from foo.py:0 (2 examples)>
1702
>>> del test.globs['__builtins__']
1706
But the globals are cleared if there is no error:
1708
>>> test = DocTestParser().get_doctest('''
1710
... ''', {}, 'foo', 'foo.py', 0)
1712
>>> runner.run(test)
1720
def run(self, test, compileflags=None, out=None, clear_globs=True):
1721
r = DocTestRunner.run(self, test, compileflags, out, False)
1726
def report_unexpected_exception(self, out, test, example, exc_info):
1727
raise UnexpectedException(test, example, exc_info)
1729
def report_failure(self, out, test, example, got):
1730
raise DocTestFailure(test, example, got)
1732
######################################################################
1733
## 6. Test Functions
1734
######################################################################
1735
# These should be backwards compatible.
1737
# For backward compatibility, a global instance of a DocTestRunner
1738
# class, updated by testmod.
1741
def testmod(m=None, name=None, globs=None, verbose=None, isprivate=None,
1742
report=True, optionflags=0, extraglobs=None,
1743
raise_on_error=False, exclude_empty=False):
1744
"""m=None, name=None, globs=None, verbose=None, isprivate=None,
1745
report=True, optionflags=0, extraglobs=None, raise_on_error=False,
1748
Test examples in docstrings in functions and classes reachable
1749
from module m (or the current module if m is not supplied), starting
1750
with m.__doc__. Unless isprivate is specified, private names
1753
Also test examples reachable from dict m.__test__ if it exists and is
1754
not None. m.__test__ maps names to functions, classes and strings;
1755
function and class docstrings are tested even if the name is private;
1756
strings are tested directly, as if they were docstrings.
1758
Return (#failures, #tests).
1760
See doctest.__doc__ for an overview.
1762
Optional keyword arg "name" gives the name of the module; by default
1765
Optional keyword arg "globs" gives a dict to be used as the globals
1766
when executing examples; by default, use m.__dict__. A copy of this
1767
dict is actually used for each docstring, so that each docstring's
1768
examples start with a clean slate.
1770
Optional keyword arg "extraglobs" gives a dictionary that should be
1771
merged into the globals that are used to execute examples. By
1772
default, no extra globals are used. This is new in 2.4.
1774
Optional keyword arg "verbose" prints lots of stuff if true, prints
1775
only failures if false; by default, it's true iff "-v" is in sys.argv.
1777
Optional keyword arg "report" prints a summary at the end when true,
1778
else prints nothing at the end. In verbose mode, the summary is
1779
detailed, else very brief (in fact, empty if all tests passed).
1781
Optional keyword arg "optionflags" or's together module constants,
1782
and defaults to 0. This is new in 2.3. Possible values (see the
1785
DONT_ACCEPT_TRUE_FOR_1
1786
DONT_ACCEPT_BLANKLINE
1787
NORMALIZE_WHITESPACE
1789
IGNORE_EXCEPTION_DETAIL
1793
REPORT_ONLY_FIRST_FAILURE
1795
Optional keyword arg "raise_on_error" raises an exception on the
1796
first unexpected exception or failure. This allows failures to be
1797
post-mortem debugged.
1799
Deprecated in Python 2.4:
1800
Optional keyword arg "isprivate" specifies a function used to
1801
determine whether a name is private. The default function is
1802
treat all functions as public. Optionally, "isprivate" can be
1803
set to doctest.is_private to skip over functions marked as private
1804
using the underscore naming convention; see its docs for details.
1806
Advanced tomfoolery: testmod runs methods of a local instance of
1807
class doctest.Tester, then merges the results into (or creates)
1808
global Tester instance doctest.master. Methods of doctest.master
1809
can be called directly too, if you want to do something unusual.
1810
Passing report=0 to testmod is especially useful then, to delay
1811
displaying a summary. Invoke doctest.master.summarize(verbose)
1812
when you're done fiddling.
1816
if isprivate is not None:
1817
warnings.warn("the isprivate argument is deprecated; "
1818
"examine DocTestFinder.find() lists instead",
1821
# If no module was given, then use __main__.
1823
# DWA - m will still be None if this wasn't invoked from the command
1824
# line, in which case the following TypeError is about as good an error
1825
# as we should expect
1826
m = sys.modules.get('__main__')
1828
# Check that we were actually given a module.
1829
if not inspect.ismodule(m):
1830
raise TypeError("testmod: module required; %r" % (m,))
1832
# If no name was given, then use the module's name.
1836
# Find, parse, and run all tests in the given module.
1837
finder = DocTestFinder(_namefilter=isprivate, exclude_empty=exclude_empty)
1840
runner = DebugRunner(verbose=verbose, optionflags=optionflags)
1842
runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1844
for test in finder.find(m, name, globs=globs, extraglobs=extraglobs):
1853
master.merge(runner)
1855
return runner.failures, runner.tries
1857
def testfile(filename, module_relative=True, name=None, package=None,
1858
globs=None, verbose=None, report=True, optionflags=0,
1859
extraglobs=None, raise_on_error=False, parser=DocTestParser()):
1861
Test examples in the given file. Return (#failures, #tests).
1863
Optional keyword arg "module_relative" specifies how filenames
1864
should be interpreted:
1866
- If "module_relative" is True (the default), then "filename"
1867
specifies a module-relative path. By default, this path is
1868
relative to the calling module's directory; but if the
1869
"package" argument is specified, then it is relative to that
1870
package. To ensure os-independence, "filename" should use
1871
"/" characters to separate path segments, and should not
1872
be an absolute path (i.e., it may not begin with "/").
1874
- If "module_relative" is False, then "filename" specifies an
1875
os-specific path. The path may be absolute or relative (to
1876
the current working directory).
1878
Optional keyword arg "name" gives the name of the test; by default
1879
use the file's basename.
1881
Optional keyword argument "package" is a Python package or the
1882
name of a Python package whose directory should be used as the
1883
base directory for a module relative filename. If no package is
1884
specified, then the calling module's directory is used as the base
1885
directory for module relative filenames. It is an error to
1886
specify "package" if "module_relative" is False.
1888
Optional keyword arg "globs" gives a dict to be used as the globals
1889
when executing examples; by default, use {}. A copy of this dict
1890
is actually used for each docstring, so that each docstring's
1891
examples start with a clean slate.
1893
Optional keyword arg "extraglobs" gives a dictionary that should be
1894
merged into the globals that are used to execute examples. By
1895
default, no extra globals are used.
1897
Optional keyword arg "verbose" prints lots of stuff if true, prints
1898
only failures if false; by default, it's true iff "-v" is in sys.argv.
1900
Optional keyword arg "report" prints a summary at the end when true,
1901
else prints nothing at the end. In verbose mode, the summary is
1902
detailed, else very brief (in fact, empty if all tests passed).
1904
Optional keyword arg "optionflags" or's together module constants,
1905
and defaults to 0. Possible values (see the docs for details):
1907
DONT_ACCEPT_TRUE_FOR_1
1908
DONT_ACCEPT_BLANKLINE
1909
NORMALIZE_WHITESPACE
1911
IGNORE_EXCEPTION_DETAIL
1915
REPORT_ONLY_FIRST_FAILURE
1917
Optional keyword arg "raise_on_error" raises an exception on the
1918
first unexpected exception or failure. This allows failures to be
1919
post-mortem debugged.
1921
Optional keyword arg "parser" specifies a DocTestParser (or
1922
subclass) that should be used to extract tests from the files.
1924
Advanced tomfoolery: testmod runs methods of a local instance of
1925
class doctest.Tester, then merges the results into (or creates)
1926
global Tester instance doctest.master. Methods of doctest.master
1927
can be called directly too, if you want to do something unusual.
1928
Passing report=0 to testmod is especially useful then, to delay
1929
displaying a summary. Invoke doctest.master.summarize(verbose)
1930
when you're done fiddling.
1934
if package and not module_relative:
1935
raise ValueError("Package may only be specified for module-"
1938
# Relativize the path
1940
package = _normalize_module(package)
1941
filename = _module_relative_path(package, filename)
1943
# If no name was given, then use the file's name.
1945
name = os.path.basename(filename)
1947
# Assemble the globals.
1951
globs = globs.copy()
1952
if extraglobs is not None:
1953
globs.update(extraglobs)
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
s = open(filename).read()
1962
test = parser.get_doctest(s, globs, name, filename, 0)
1971
master.merge(runner)
1973
return runner.failures, runner.tries
1975
def run_docstring_examples(f, globs, verbose=False, name="NoName",
1976
compileflags=None, optionflags=0):
1978
Test examples in the given object's docstring (`f`), using `globs`
1979
as globals. Optional argument `name` is used in failure messages.
1980
If the optional argument `verbose` is true, then generate output
1981
even if there are no failures.
1983
`compileflags` gives the set of flags that should be used by the
1984
Python compiler when running the examples. If not specified, then
1985
it will default to the set of future-import flags that apply to
1988
Optional keyword arg `optionflags` specifies options for the
1989
testing and output. See the documentation for `testmod` for more
1992
# Find, parse, and run all tests in the given module.
1993
finder = DocTestFinder(verbose=verbose, recurse=False)
1994
runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1995
for test in finder.find(f, name, globs=globs):
1996
runner.run(test, compileflags=compileflags)
1998
######################################################################
2000
######################################################################
2001
# This is provided only for backwards compatibility. It's not
2002
# actually used in any way.
2005
def __init__(self, mod=None, globs=None, verbose=None,
2006
isprivate=None, optionflags=0):
2008
warnings.warn("class Tester is deprecated; "
2009
"use class doctest.DocTestRunner instead",
2010
DeprecationWarning, stacklevel=2)
2011
if mod is None and globs is None:
2012
raise TypeError("Tester.__init__: must specify mod or globs")
2013
if mod is not None and not inspect.ismodule(mod):
2014
raise TypeError("Tester.__init__: mod must be a module; %r" %
2017
globs = mod.__dict__
2020
self.verbose = verbose
2021
self.isprivate = isprivate
2022
self.optionflags = optionflags
2023
self.testfinder = DocTestFinder(_namefilter=isprivate)
2024
self.testrunner = DocTestRunner(verbose=verbose,
2025
optionflags=optionflags)
2027
def runstring(self, s, name):
2028
test = DocTestParser().get_doctest(s, self.globs, name, None, None)
2030
print "Running string", name
2031
(f,t) = self.testrunner.run(test)
2033
print f, "of", t, "examples failed in string", name
2036
def rundoc(self, object, name=None, module=None):
2038
tests = self.testfinder.find(object, name, module=module,
2041
(f2, t2) = self.testrunner.run(test)
2042
(f,t) = (f+f2, t+t2)
2045
def rundict(self, d, name, module=None):
2047
m = new.module(name)
2048
m.__dict__.update(d)
2051
return self.rundoc(m, name, module)
2053
def run__test__(self, d, name):
2055
m = new.module(name)
2057
return self.rundoc(m, name)
2059
def summarize(self, verbose=None):
2060
return self.testrunner.summarize(verbose)
2062
def merge(self, other):
2063
self.testrunner.merge(other.testrunner)
2065
######################################################################
2066
## 8. Unittest Support
2067
######################################################################
2069
_unittest_reportflags = 0
2071
def set_unittest_reportflags(flags):
2072
"""Sets the unittest option flags.
2074
The old flag is returned so that a runner could restore the old
2075
value if it wished to:
2077
>>> old = _unittest_reportflags
2078
>>> set_unittest_reportflags(REPORT_NDIFF |
2079
... REPORT_ONLY_FIRST_FAILURE) == old
2083
>>> doctest._unittest_reportflags == (REPORT_NDIFF |
2084
... REPORT_ONLY_FIRST_FAILURE)
2087
Only reporting flags can be set:
2089
>>> set_unittest_reportflags(ELLIPSIS)
2090
Traceback (most recent call last):
2092
ValueError: ('Only reporting flags allowed', 8)
2094
>>> set_unittest_reportflags(old) == (REPORT_NDIFF |
2095
... REPORT_ONLY_FIRST_FAILURE)
2098
global _unittest_reportflags
2100
if (flags & REPORTING_FLAGS) != flags:
2101
raise ValueError("Only reporting flags allowed", flags)
2102
old = _unittest_reportflags
2103
_unittest_reportflags = flags
2107
class DocTestCase(unittest.TestCase):
2109
def __init__(self, test, optionflags=0, setUp=None, tearDown=None,
2110
checker=None, runner=DocTestRunner):
2112
unittest.TestCase.__init__(self)
2113
self._dt_optionflags = optionflags
2114
self._dt_checker = checker
2115
self._dt_test = test
2116
self._dt_setUp = setUp
2117
self._dt_tearDown = tearDown
2118
self._dt_runner = runner
2121
test = self._dt_test
2123
if self._dt_setUp is not None:
2124
self._dt_setUp(test)
2127
test = self._dt_test
2129
if self._dt_tearDown is not None:
2130
self._dt_tearDown(test)
2135
test = self._dt_test
2138
optionflags = self._dt_optionflags
2140
if not (optionflags & REPORTING_FLAGS):
2141
# The option flags don't include any reporting flags,
2142
# so add the default reporting flags
2143
optionflags |= _unittest_reportflags
2145
runner = self._dt_runner(optionflags=optionflags,
2146
checker=self._dt_checker, verbose=False)
2149
runner.DIVIDER = "-"*70
2150
failures, tries = runner.run(
2151
test, out=new.write, clear_globs=False)
2156
raise self.failureException(self.format_failure(new.getvalue()))
2158
def format_failure(self, err):
2159
test = self._dt_test
2160
if test.lineno is None:
2161
lineno = 'unknown line number'
2163
lineno = '%s' % test.lineno
2164
lname = '.'.join(test.name.split('.')[-1:])
2165
return ('Failed doctest test for %s\n'
2166
' File "%s", line %s, in %s\n\n%s'
2167
% (test.name, test.filename, lineno, lname, err)
2171
r"""Run the test case without results and without catching exceptions
2173
The unit test framework includes a debug method on test cases
2174
and test suites to support post-mortem debugging. The test code
2175
is run in such a way that errors are not caught. This way a
2176
caller can catch the errors and initiate post-mortem debugging.
2178
The DocTestCase provides a debug method that raises
2179
UnexpectedException errors if there is an unexepcted
2182
>>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
2183
... {}, 'foo', 'foo.py', 0)
2184
>>> case = DocTestCase(test)
2187
... except UnexpectedException, failure:
2190
The UnexpectedException contains the test, the example, and
2191
the original exception:
2193
>>> failure.test is test
2196
>>> failure.example.want
2199
>>> exc_info = failure.exc_info
2200
>>> raise exc_info[0], exc_info[1], exc_info[2]
2201
Traceback (most recent call last):
2205
If the output doesn't match, then a DocTestFailure is raised:
2207
>>> test = DocTestParser().get_doctest('''
2211
... ''', {}, 'foo', 'foo.py', 0)
2212
>>> case = DocTestCase(test)
2216
... except DocTestFailure, failure:
2219
DocTestFailure objects provide access to the test:
2221
>>> failure.test is test
2224
As well as to the example:
2226
>>> failure.example.want
2229
and the actual output:
2237
runner = DebugRunner(optionflags=self._dt_optionflags,
2238
checker=self._dt_checker, verbose=False)
2239
runner.run(self._dt_test)
2243
return self._dt_test.name
2246
name = self._dt_test.name.split('.')
2247
return "%s (%s)" % (name[-1], '.'.join(name[:-1]))
2251
def shortDescription(self):
2252
return "Doctest: " + self._dt_test.name
2254
def DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None,
2255
test_class=DocTestCase, **options):
2257
Convert doctest tests for a module to a unittest test suite.
2259
This converts each documentation string in a module that
2260
contains doctest tests to a unittest test case. If any of the
2261
tests in a doc string fail, then the test case fails. An exception
2262
is raised showing the name of the file containing the test and a
2263
(sometimes approximate) line number.
2265
The `module` argument provides the module to be tested. The argument
2266
can be either a module or a module name.
2268
If no argument is given, the calling module is used.
2270
A number of options may be provided as keyword arguments:
2273
A set-up function. This is called before running the
2274
tests in each file. The setUp function will be passed a DocTest
2275
object. The setUp function can access the test globals as the
2276
globs attribute of the test passed.
2279
A tear-down function. This is called after running the
2280
tests in each file. The tearDown function will be passed a DocTest
2281
object. The tearDown function can access the test globals as the
2282
globs attribute of the test passed.
2285
A dictionary containing initial global variables for the tests.
2288
A set of doctest option flags expressed as an integer.
2291
if test_finder is None:
2292
test_finder = DocTestFinder()
2294
module = _normalize_module(module)
2295
tests = test_finder.find(module, globs=globs, extraglobs=extraglobs)
2297
globs = module.__dict__
2299
# Why do we want to do this? Because it reveals a bug that might
2300
# otherwise be hidden.
2301
raise ValueError(module, "has no tests")
2304
suite = unittest.TestSuite()
2306
if len(test.examples) == 0:
2308
if not test.filename:
2309
filename = module.__file__
2310
if filename[-4:] in (".pyc", ".pyo"):
2311
filename = filename[:-1]
2312
test.filename = filename
2313
suite.addTest(test_class(test, **options))
2317
class DocFileCase(DocTestCase):
2320
return '_'.join(self._dt_test.name.split('.'))
2323
return self._dt_test.filename
2326
def format_failure(self, err):
2327
return ('Failed doctest test for %s\n File "%s", line 0\n\n%s'
2328
% (self._dt_test.name, self._dt_test.filename, err)
2331
def DocFileTest(path, module_relative=True, package=None,
2332
globs=None, parser=DocTestParser(), **options):
2336
if package and not module_relative:
2337
raise ValueError("Package may only be specified for module-"
2340
# Relativize the path.
2342
package = _normalize_module(package)
2343
path = _module_relative_path(package, path)
2345
# Find the file and read it.
2346
name = os.path.basename(path)
2347
doc = open(path).read()
2349
# Convert it to a test, and wrap it in a DocFileCase.
2350
test = parser.get_doctest(doc, globs, name, path, 0)
2351
return DocFileCase(test, **options)
2353
def DocFileSuite(*paths, **kw):
2354
"""A unittest suite for one or more doctest files.
2356
The path to each doctest file is given as a string; the
2357
interpretation of that string depends on the keyword argument
2360
A number of options may be provided as keyword arguments:
2363
If "module_relative" is True, then the given file paths are
2364
interpreted as os-independent module-relative paths. By
2365
default, these paths are relative to the calling module's
2366
directory; but if the "package" argument is specified, then
2367
they are relative to that package. To ensure os-independence,
2368
"filename" should use "/" characters to separate path
2369
segments, and may not be an absolute path (i.e., it may not
2372
If "module_relative" is False, then the given file paths are
2373
interpreted as os-specific paths. These paths may be absolute
2374
or relative (to the current working directory).
2377
A Python package or the name of a Python package whose directory
2378
should be used as the base directory for module relative paths.
2379
If "package" is not specified, then the calling module's
2380
directory is used as the base directory for module relative
2381
filenames. It is an error to specify "package" if
2382
"module_relative" is False.
2385
A set-up function. This is called before running the
2386
tests in each file. The setUp function will be passed a DocTest
2387
object. The setUp function can access the test globals as the
2388
globs attribute of the test passed.
2391
A tear-down function. This is called after running the
2392
tests in each file. The tearDown function will be passed a DocTest
2393
object. The tearDown function can access the test globals as the
2394
globs attribute of the test passed.
2397
A dictionary containing initial global variables for the tests.
2400
A set of doctest option flags expressed as an integer.
2403
A DocTestParser (or subclass) that should be used to extract
2404
tests from the files.
2406
suite = unittest.TestSuite()
2408
# We do this here so that _normalize_module is called at the right
2409
# level. If it were called in DocFileTest, then this function
2410
# would be the caller and we might guess the package incorrectly.
2411
if kw.get('module_relative', True):
2412
kw['package'] = _normalize_module(kw.get('package'))
2415
suite.addTest(DocFileTest(path, **kw))
2419
######################################################################
2420
## 9. Debugging Support
2421
######################################################################
2423
def script_from_examples(s):
2424
r"""Extract script from text with examples.
2426
Converts text with examples to a Python script. Example input is
2427
converted to regular code. Example output and all other words
2428
are converted to comments:
2431
... Here are examples of simple math.
2433
... Python has super accurate integer addition
2438
... And very friendly error messages:
2445
... You can use logic if you want:
2455
>>> print script_from_examples(text)
2456
# Here are examples of simple math.
2458
# Python has super accurate integer addition
2464
# And very friendly error messages:
2472
# You can use logic if you want:
2481
for piece in DocTestParser().parse(s):
2482
if isinstance(piece, Example):
2483
# Add the example's source code (strip trailing NL)
2484
output.append(piece.source[:-1])
2485
# Add the expected output:
2488
output.append('# Expected:')
2489
output += ['## '+l for l in want.split('\n')[:-1]]
2491
# Add non-example text.
2492
output += [_comment_line(l)
2493
for l in piece.split('\n')[:-1]]
2495
# Trim junk on both ends.
2496
while output and output[-1] == '#':
2498
while output and output[0] == '#':
2500
# Combine the output, and return it.
2501
return '\n'.join(output)
2503
def testsource(module, name):
2504
"""Extract the test sources from a doctest docstring as a script.
2506
Provide the module (or dotted name of the module) containing the
2507
test to be debugged and the name (within the module) of the object
2508
with the doc string with tests to be debugged.
2510
module = _normalize_module(module)
2511
tests = DocTestFinder().find(module)
2512
test = [t for t in tests if t.name == name]
2514
raise ValueError(name, "not found in tests")
2516
testsrc = script_from_examples(test.docstring)
2519
def debug_src(src, pm=False, globs=None):
2520
"""Debug a single doctest docstring, in argument `src`'"""
2521
testsrc = script_from_examples(src)
2522
debug_script(testsrc, pm, globs)
2524
def debug_script(src, pm=False, globs=None):
2525
"Debug a test script. `src` is the script, as a string."
2528
# Note that tempfile.NameTemporaryFile() cannot be used. As the
2529
# docs say, a file so created cannot be opened by name a second time
2530
# on modern Windows boxes, and execfile() needs to open it.
2531
srcfilename = tempfile.mktemp(".py", "doctestdebug")
2532
f = open(srcfilename, 'w')
2538
globs = globs.copy()
2544
execfile(srcfilename, globs, globs)
2546
print sys.exc_info()[1]
2547
pdb.post_mortem(sys.exc_info()[2])
2549
# Note that %r is vital here. '%s' instead can, e.g., cause
2550
# backslashes to get treated as metacharacters on Windows.
2551
pdb.run("execfile(%r)" % srcfilename, globs, globs)
2554
os.remove(srcfilename)
2556
def debug(module, name, pm=False):
2557
"""Debug a single doctest docstring.
2559
Provide the module (or dotted name of the module) containing the
2560
test to be debugged and the name (within the module) of the object
2561
with the docstring with tests to be debugged.
2563
module = _normalize_module(module)
2564
testsrc = testsource(module, name)
2565
debug_script(testsrc, pm, module.__dict__)
2567
######################################################################
2568
## 10. Example Usage
2569
######################################################################
2572
A pointless class, for sanity-checking of docstring testing.
2578
>>> _TestClass(13).get() + _TestClass(-12).get()
2580
>>> hex(_TestClass(13).square().get())
2584
def __init__(self, val):
2585
"""val -> _TestClass object with associated value val.
2587
>>> t = _TestClass(123)
2595
"""square() -> square TestClass's associated value
2597
>>> _TestClass(13).square().get()
2601
self.val = self.val ** 2
2605
"""get() -> return TestClass's associated value.
2607
>>> x = _TestClass(-42)
2614
__test__ = {"_TestClass": _TestClass,
2616
Example of a string object, searched as-is.
2622
"bool-int equivalence": r"""
2623
In 2.2, boolean expressions displayed
2624
0 or 1. By default, we still accept
2625
them. This can be disabled by passing
2626
DONT_ACCEPT_TRUE_FOR_1 to the new
2627
optionflags argument.
2639
Blank lines can be marked with <BLANKLINE>:
2640
>>> print 'foo\n\nbar\n'
2648
If the ellipsis flag is used, then '...' can be used to
2649
elide substrings in the desired output:
2650
>>> print range(1000) #doctest: +ELLIPSIS
2654
"whitespace normalization": r"""
2655
If the whitespace normalization flag is used, then
2656
differences in whitespace are ignored.
2657
>>> print range(30) #doctest: +NORMALIZE_WHITESPACE
2658
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
2659
15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,
2665
r = unittest.TextTestRunner()
2666
r.run(DocTestSuite())
2668
if __name__ == "__main__":
added
removed
django/test/doctest.py
