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',
88 'set_unittest_reportflags',
89 # 9. Debugging Support
90 'script_from_examples',
98 import sys
, traceback
, inspect
, linecache
, os
, re
99 import unittest
, difflib
, pdb
, tempfile
101 from StringIO
import StringIO
102 from collections
import namedtuple
104 TestResults
= namedtuple('TestResults', 'failed attempted')
106 # There are 4 basic classes:
107 # - Example: a <source, want> pair, plus an intra-docstring line number.
108 # - DocTest: a collection of examples, parsed from a docstring, plus
109 # info about where the docstring came from (name, filename, lineno).
110 # - DocTestFinder: extracts DocTests from a given object's docstring and
111 # its contained objects' docstrings.
112 # - DocTestRunner: runs DocTest cases, and accumulates statistics.
114 # So the basic picture is:
117 # +------+ +---------+ +-------+
118 # |object| --DocTestFinder-> | DocTest | --DocTestRunner-> |results|
119 # +------+ +---------+ +-------+
127 OPTIONFLAGS_BY_NAME
= {}
128 def register_optionflag(name
):
129 # Create a new flag unless `name` is already known.
130 return OPTIONFLAGS_BY_NAME
.setdefault(name
, 1 << len(OPTIONFLAGS_BY_NAME
))
132 DONT_ACCEPT_TRUE_FOR_1
= register_optionflag('DONT_ACCEPT_TRUE_FOR_1')
133 DONT_ACCEPT_BLANKLINE
= register_optionflag('DONT_ACCEPT_BLANKLINE')
134 NORMALIZE_WHITESPACE
= register_optionflag('NORMALIZE_WHITESPACE')
135 ELLIPSIS
= register_optionflag('ELLIPSIS')
136 SKIP
= register_optionflag('SKIP')
137 IGNORE_EXCEPTION_DETAIL
= register_optionflag('IGNORE_EXCEPTION_DETAIL')
139 COMPARISON_FLAGS
= (DONT_ACCEPT_TRUE_FOR_1 |
140 DONT_ACCEPT_BLANKLINE |
141 NORMALIZE_WHITESPACE |
144 IGNORE_EXCEPTION_DETAIL
)
146 REPORT_UDIFF
= register_optionflag('REPORT_UDIFF')
147 REPORT_CDIFF
= register_optionflag('REPORT_CDIFF')
148 REPORT_NDIFF
= register_optionflag('REPORT_NDIFF')
149 REPORT_ONLY_FIRST_FAILURE
= register_optionflag('REPORT_ONLY_FIRST_FAILURE')
151 REPORTING_FLAGS
= (REPORT_UDIFF |
154 REPORT_ONLY_FIRST_FAILURE
)
156 # Special string markers for use in `want` strings:
157 BLANKLINE_MARKER
= '<BLANKLINE>'
158 ELLIPSIS_MARKER
= '...'
160 ######################################################################
162 ######################################################################
163 # 1. Utility Functions
164 # 2. Example & DocTest -- store test cases
165 # 3. DocTest Parser -- extracts examples from strings
166 # 4. DocTest Finder -- extracts test cases from objects
167 # 5. DocTest Runner -- runs test cases
168 # 6. Test Functions -- convenient wrappers for testing
169 # 7. Tester Class -- for backwards compatibility
170 # 8. Unittest Support
171 # 9. Debugging Support
174 ######################################################################
175 ## 1. Utility Functions
176 ######################################################################
178 def _extract_future_flags(globs
):
180 Return the compiler-flags associated with the future features that
181 have been imported into the given namespace (globs).
184 for fname
in __future__
.all_feature_names
:
185 feature
= globs
.get(fname
, None)
186 if feature
is getattr(__future__
, fname
):
187 flags |
= feature
.compiler_flag
190 def _normalize_module(module
, depth
=2):
192 Return the module specified by `module`. In particular:
193 - If `module` is a module, then return module.
194 - If `module` is a string, then import and return the
195 module with that name.
196 - If `module` is None, then return the calling module.
197 The calling module is assumed to be the module of
198 the stack frame at the given depth in the call stack.
200 if inspect
.ismodule(module
):
202 elif isinstance(module
, (str, unicode)):
203 return __import__(module
, globals(), locals(), ["*"])
205 return sys
.modules
[sys
._getframe
(depth
).f_globals
['__name__']]
207 raise TypeError("Expected a module, string, or None")
209 def _load_testfile(filename
, package
, module_relative
):
211 package
= _normalize_module(package
, 3)
212 filename
= _module_relative_path(package
, filename
)
213 if hasattr(package
, '__loader__'):
214 if hasattr(package
.__loader
__, 'get_data'):
215 file_contents
= package
.__loader
__.get_data(filename
)
216 # get_data() opens files as 'rb', so one must do the equivalent
217 # conversion as universal newlines would do.
218 return file_contents
.replace(os
.linesep
, '\n'), filename
219 return open(filename
).read(), filename
221 # Use sys.stdout encoding for ouput.
222 _encoding
= getattr(sys
.__stdout
__, 'encoding', None) or 'utf-8'
224 def _indent(s
, indent
=4):
226 Add the given number of space characters to the beginning of
227 every non-blank line in `s`, and return the result.
228 If the string `s` is Unicode, it is encoded using the stdout
229 encoding and the `backslashreplace` error handler.
231 if isinstance(s
, unicode):
232 s
= s
.encode(_encoding
, 'backslashreplace')
233 # This regexp matches the start of non-blank lines:
234 return re
.sub('(?m)^(?!$)', indent
*' ', s
)
236 def _exception_traceback(exc_info
):
238 Return a string containing a traceback message for the given
239 exc_info tuple (as returned by sys.exc_info()).
241 # Get a traceback message.
243 exc_type
, exc_val
, exc_tb
= exc_info
244 traceback
.print_exception(exc_type
, exc_val
, exc_tb
, file=excout
)
245 return excout
.getvalue()
247 # Override some StringIO methods.
248 class _SpoofOut(StringIO
):
250 result
= StringIO
.getvalue(self
)
251 # If anything at all was written, make sure there's a trailing
252 # newline. There's no way for the expected output to indicate
253 # that a trailing newline is missing.
254 if result
and not result
.endswith("\n"):
256 # Prevent softspace from screwing up the next test case, in
257 # case they used print with a trailing comma in an example.
258 if hasattr(self
, "softspace"):
262 def truncate(self
, size
=None):
263 StringIO
.truncate(self
, size
)
264 if hasattr(self
, "softspace"):
267 # Worst-case linear-time ellipsis matching.
268 def _ellipsis_match(want
, got
):
270 Essentially the only subtle case:
271 >>> _ellipsis_match('aa...aa', 'aaa')
274 if ELLIPSIS_MARKER
not in want
:
277 # Find "the real" strings.
278 ws
= want
.split(ELLIPSIS_MARKER
)
281 # Deal with exact matches possibly needed at one or both ends.
282 startpos
, endpos
= 0, len(got
)
284 if w
: # starts with exact match
285 if got
.startswith(w
):
291 if w
: # ends with exact match
298 if startpos
> endpos
:
299 # Exact end matches required more characters than we have, as in
300 # _ellipsis_match('aa...aa', 'aaa')
303 # For the rest, we only need to find the leftmost non-overlapping
304 # match for each piece. If there's no overall match that way alone,
305 # there's no overall match period.
307 # w may be '' at times, if there are consecutive ellipses, or
308 # due to an ellipsis at the start or end of `want`. That's OK.
309 # Search for an empty string succeeds, and doesn't change startpos.
310 startpos
= got
.find(w
, startpos
, endpos
)
317 def _comment_line(line
):
318 "Return a commented form of the given line"
325 class _OutputRedirectingPdb(pdb
.Pdb
):
327 A specialized version of the python debugger that redirects stdout
328 to a given stream when interacting with the user. Stdout is *not*
329 redirected when traced code is executed.
331 def __init__(self
, out
):
333 self
.__debugger
_used
= False
334 pdb
.Pdb
.__init
__(self
, stdout
=out
)
336 def set_trace(self
, frame
=None):
337 self
.__debugger
_used
= True
339 frame
= sys
._getframe
().f_back
340 pdb
.Pdb
.set_trace(self
, frame
)
342 def set_continue(self
):
343 # Calling set_continue unconditionally would break unit test
344 # coverage reporting, as Bdb.set_continue calls sys.settrace(None).
345 if self
.__debugger
_used
:
346 pdb
.Pdb
.set_continue(self
)
348 def trace_dispatch(self
, *args
):
349 # Redirect stdout to the given stream.
350 save_stdout
= sys
.stdout
351 sys
.stdout
= self
.__out
352 # Call Pdb's trace dispatch method.
354 return pdb
.Pdb
.trace_dispatch(self
, *args
)
356 sys
.stdout
= save_stdout
358 # [XX] Normalize with respect to os.path.pardir?
359 def _module_relative_path(module
, path
):
360 if not inspect
.ismodule(module
):
361 raise TypeError, 'Expected a module: %r' % module
362 if path
.startswith('/'):
363 raise ValueError, 'Module-relative files may not have absolute paths'
365 # Find the base directory for the path.
366 if hasattr(module
, '__file__'):
367 # A normal module/package
368 basedir
= os
.path
.split(module
.__file
__)[0]
369 elif module
.__name
__ == '__main__':
370 # An interactive session.
371 if len(sys
.argv
)>0 and sys
.argv
[0] != '':
372 basedir
= os
.path
.split(sys
.argv
[0])[0]
376 # A module w/o __file__ (this includes builtins)
377 raise ValueError("Can't resolve paths relative to the module " +
378 module
+ " (it has no __file__)")
380 # Combine the base directory and the path.
381 return os
.path
.join(basedir
, *(path
.split('/')))
383 ######################################################################
384 ## 2. Example & DocTest
385 ######################################################################
386 ## - An "example" is a <source, want> pair, where "source" is a
387 ## fragment of source code, and "want" is the expected output for
388 ## "source." The Example class also includes information about
389 ## where the example was extracted from.
391 ## - A "doctest" is a collection of examples, typically extracted from
392 ## a string (such as an object's docstring). The DocTest class also
393 ## includes information about where the string was extracted from.
397 A single doctest example, consisting of source code and expected
398 output. `Example` defines the following attributes:
400 - source: A single Python statement, always ending with a newline.
401 The constructor adds a newline if needed.
403 - want: The expected output from running the source code (either
404 from stdout, or a traceback in case of exception). `want` ends
405 with a newline unless it's empty, in which case it's an empty
406 string. The constructor adds a newline if needed.
408 - exc_msg: The exception message generated by the example, if
409 the example is expected to generate an exception; or `None` if
410 it is not expected to generate an exception. This exception
411 message is compared against the return value of
412 `traceback.format_exception_only()`. `exc_msg` ends with a
413 newline unless it's `None`. The constructor adds a newline
416 - lineno: The line number within the DocTest string containing
417 this Example where the Example begins. This line number is
418 zero-based, with respect to the beginning of the DocTest.
420 - indent: The example's indentation in the DocTest string.
421 I.e., the number of space characters that preceed the
422 example's first prompt.
424 - options: A dictionary mapping from option flags to True or
425 False, which is used to override default options for this
426 example. Any option flags not contained in this dictionary
427 are left at their default value (as specified by the
428 DocTestRunner's optionflags). By default, no options are set.
430 def __init__(self
, source
, want
, exc_msg
=None, lineno
=0, indent
=0,
433 if not source
.endswith('\n'):
435 if want
and not want
.endswith('\n'):
437 if exc_msg
is not None and not exc_msg
.endswith('\n'):
444 if options
is None: options
= {}
445 self
.options
= options
446 self
.exc_msg
= exc_msg
450 A collection of doctest examples that should be run in a single
451 namespace. Each `DocTest` defines the following attributes:
453 - examples: the list of examples.
455 - globs: The namespace (aka globals) that the examples should
458 - name: A name identifying the DocTest (typically, the name of
459 the object whose docstring this DocTest was extracted from).
461 - filename: The name of the file that this DocTest was extracted
462 from, or `None` if the filename is unknown.
464 - lineno: The line number within filename where this DocTest
465 begins, or `None` if the line number is unavailable. This
466 line number is zero-based, with respect to the beginning of
469 - docstring: The string that the examples were extracted from,
470 or `None` if the string is unavailable.
472 def __init__(self
, examples
, globs
, name
, filename
, lineno
, docstring
):
474 Create a new DocTest containing the given examples. The
475 DocTest's globals are initialized with a copy of `globs`.
477 assert not isinstance(examples
, basestring
), \
478 "DocTest no longer accepts str; use DocTestParser instead"
479 self
.examples
= examples
480 self
.docstring
= docstring
481 self
.globs
= globs
.copy()
483 self
.filename
= filename
487 if len(self
.examples
) == 0:
488 examples
= 'no examples'
489 elif len(self
.examples
) == 1:
490 examples
= '1 example'
492 examples
= '%d examples' % len(self
.examples
)
493 return ('<DocTest %s from %s:%s (%s)>' %
494 (self
.name
, self
.filename
, self
.lineno
, examples
))
497 # This lets us sort tests by name:
498 def __cmp__(self
, other
):
499 if not isinstance(other
, DocTest
):
501 return cmp((self
.name
, self
.filename
, self
.lineno
, id(self
)),
502 (other
.name
, other
.filename
, other
.lineno
, id(other
)))
504 ######################################################################
506 ######################################################################
510 A class used to parse strings containing doctest examples.
512 # This regular expression is used to find doctest examples in a
513 # string. It defines three groups: `source` is the source code
514 # (including leading indentation and prompts); `indent` is the
515 # indentation of the first (PS1) line of the source code; and
516 # `want` is the expected output (including leading indentation).
517 _EXAMPLE_RE
= re
.compile(r
'''
518 # Source consists of a PS1 line followed by zero or more PS2 lines.
520 (?:^(?P<indent> [ ]*) >>> .*) # PS1 line
521 (?:\n [ ]* \.\.\. .*)*) # PS2 lines
523 # Want consists of any non-blank lines that do not start with PS1.
524 (?P<want> (?:(?![ ]*$) # Not a blank line
525 (?![ ]*>>>) # Not a line starting with PS1
526 .*$\n? # But any other line
528 ''', re
.MULTILINE | re
.VERBOSE
)
530 # A regular expression for handling `want` strings that contain
531 # expected exceptions. It divides `want` into three pieces:
532 # - the traceback header line (`hdr`)
533 # - the traceback stack (`stack`)
534 # - the exception message (`msg`), as generated by
535 # traceback.format_exception_only()
536 # `msg` may have multiple lines. We assume/require that the
537 # exception message is the first non-indented line starting with a word
538 # character following the traceback header line.
539 _EXCEPTION_RE
= re
.compile(r
"""
540 # Grab the traceback header. Different versions of Python have
541 # said different things on the first traceback line.
542 ^(?P<hdr> Traceback\ \(
543 (?: most\ recent\ call\ last
547 \s* $ # toss trailing whitespace on the header.
548 (?P<stack> .*?) # don't blink: absorb stuff until...
549 ^ (?P<msg> \w+ .*) # a line *starts* with alphanum.
550 """, re
.VERBOSE | re
.MULTILINE | re
.DOTALL
)
552 # A callable returning a true value iff its argument is a blank line
553 # or contains a single comment.
554 _IS_BLANK_OR_COMMENT
= re
.compile(r
'^[ ]*(#.*)?$').match
556 def parse(self
, string
, name
='<string>'):
558 Divide the given string into examples and intervening text,
559 and return them as a list of alternating Examples and strings.
560 Line numbers for the Examples are 0-based. The optional
561 argument `name` is a name identifying this string, and is only
562 used for error messages.
564 string
= string
.expandtabs()
565 # If all lines begin with the same indentation, then strip it.
566 min_indent
= self
._min
_indent
(string
)
568 string
= '\n'.join([l
[min_indent
:] for l
in string
.split('\n')])
571 charno
, lineno
= 0, 0
572 # Find all doctest examples in the string:
573 for m
in self
._EXAMPLE
_RE
.finditer(string
):
574 # Add the pre-example text to `output`.
575 output
.append(string
[charno
:m
.start()])
576 # Update lineno (lines before this example)
577 lineno
+= string
.count('\n', charno
, m
.start())
578 # Extract info from the regexp match.
579 (source
, options
, want
, exc_msg
) = \
580 self
._parse
_example
(m
, name
, lineno
)
581 # Create an Example, and add it to the list.
582 if not self
._IS
_BLANK
_OR
_COMMENT
(source
):
583 output
.append( Example(source
, want
, exc_msg
,
585 indent
=min_indent
+len(m
.group('indent')),
587 # Update lineno (lines inside this example)
588 lineno
+= string
.count('\n', m
.start(), m
.end())
591 # Add any remaining post-example text to `output`.
592 output
.append(string
[charno
:])
595 def get_doctest(self
, string
, globs
, name
, filename
, lineno
):
597 Extract all doctest examples from the given string, and
598 collect them into a `DocTest` object.
600 `globs`, `name`, `filename`, and `lineno` are attributes for
601 the new `DocTest` object. See the documentation for `DocTest`
602 for more information.
604 return DocTest(self
.get_examples(string
, name
), globs
,
605 name
, filename
, lineno
, string
)
607 def get_examples(self
, string
, name
='<string>'):
609 Extract all doctest examples from the given string, and return
610 them as a list of `Example` objects. Line numbers are
611 0-based, because it's most common in doctests that nothing
612 interesting appears on the same line as opening triple-quote,
613 and so the first interesting line is called \"line 1\" then.
615 The optional argument `name` is a name identifying this
616 string, and is only used for error messages.
618 return [x
for x
in self
.parse(string
, name
)
619 if isinstance(x
, Example
)]
621 def _parse_example(self
, m
, name
, lineno
):
623 Given a regular expression match from `_EXAMPLE_RE` (`m`),
624 return a pair `(source, want)`, where `source` is the matched
625 example's source code (with prompts and indentation stripped);
626 and `want` is the example's expected output (with indentation
629 `name` is the string's name, and `lineno` is the line number
630 where the example starts; both are used for error messages.
632 # Get the example's indentation level.
633 indent
= len(m
.group('indent'))
635 # Divide source into lines; check that they're properly
636 # indented; and then strip their indentation & prompts.
637 source_lines
= m
.group('source').split('\n')
638 self
._check
_prompt
_blank
(source_lines
, indent
, name
, lineno
)
639 self
._check
_prefix
(source_lines
[1:], ' '*indent
+ '.', name
, lineno
)
640 source
= '\n'.join([sl
[indent
+4:] for sl
in source_lines
])
642 # Divide want into lines; check that it's properly indented; and
643 # then strip the indentation. Spaces before the last newline should
644 # be preserved, so plain rstrip() isn't good enough.
645 want
= m
.group('want')
646 want_lines
= want
.split('\n')
647 if len(want_lines
) > 1 and re
.match(r
' *$', want_lines
[-1]):
648 del want_lines
[-1] # forget final newline & spaces after it
649 self
._check
_prefix
(want_lines
, ' '*indent
, name
,
650 lineno
+ len(source_lines
))
651 want
= '\n'.join([wl
[indent
:] for wl
in want_lines
])
653 # If `want` contains a traceback message, then extract it.
654 m
= self
._EXCEPTION
_RE
.match(want
)
656 exc_msg
= m
.group('msg')
660 # Extract options from the source.
661 options
= self
._find
_options
(source
, name
, lineno
)
663 return source
, options
, want
, exc_msg
665 # This regular expression looks for option directives in the
666 # source code of an example. Option directives are comments
667 # starting with "doctest:". Warning: this may give false
668 # positives for string-literals that contain the string
669 # "#doctest:". Eliminating these false positives would require
670 # actually parsing the string; but we limit them by ignoring any
671 # line containing "#doctest:" that is *followed* by a quote mark.
672 _OPTION_DIRECTIVE_RE
= re
.compile(r
'#\s*doctest:\s*([^\n\'"]*)$',
675 def _find_options(self, source, name, lineno):
677 Return a dictionary containing option overrides extracted from
678 option directives in the given source string.
680 `name` is the string's name, and `lineno` is the line number
681 where the example starts; both are used for error messages.
684 # (note: with the current regexp, this will match at most once:)
685 for m in self._OPTION_DIRECTIVE_RE.finditer(source):
686 option_strings = m.group(1).replace(',', ' ').split()
687 for option in option_strings:
688 if (option[0] not in '+-' or
689 option[1:] not in OPTIONFLAGS_BY_NAME):
690 raise ValueError('line %r of the doctest for %s '
691 'has an invalid option: %r' %
692 (lineno+1, name, option))
693 flag = OPTIONFLAGS_BY_NAME[option[1:]]
694 options[flag] = (option[0] == '+')
695 if options and self._IS_BLANK_OR_COMMENT(source):
696 raise ValueError('line %r of the doctest for %s has an option '
697 'directive on a line with no example: %r' %
698 (lineno, name, source))
701 # This regular expression finds the indentation of every non-blank
703 _INDENT_RE = re.compile('^([ ]*)(?=\S)', re.MULTILINE)
705 def _min_indent(self, s):
706 "Return the minimum indentation of any non
-blank line
in `s`
"
707 indents = [len(indent) for indent in self._INDENT_RE.findall(s)]
713 def _check_prompt_blank(self, lines, indent, name, lineno):
715 Given the lines of a source string (including prompts and
716 leading indentation), check to make sure that every prompt is
717 followed by a space character. If any line is not followed by
718 a space character, then raise ValueError.
720 for i, line in enumerate(lines):
721 if len(line) >= indent+4 and line[indent+3] != ' ':
722 raise ValueError('line %r of the docstring for %s '
723 'lacks blank after %s: %r' %
725 line[indent:indent+3], line))
727 def _check_prefix(self, lines, prefix, name, lineno):
729 Check that every line in the given list starts with the given
730 prefix; if any line does not, then raise a ValueError.
732 for i, line in enumerate(lines):
733 if line and not line.startswith(prefix):
734 raise ValueError('line %r of the docstring for %s has '
735 'inconsistent leading whitespace: %r' %
736 (lineno+i+1, name, line))
739 ######################################################################
741 ######################################################################
745 A class used to extract the DocTests that are relevant to a given
746 object, from its docstring and the docstrings of its contained
747 objects. Doctests can currently be extracted from the following
748 object types: modules, functions, classes, methods, staticmethods,
749 classmethods, and properties.
752 def __init__(self, verbose=False, parser=DocTestParser(),
753 recurse=True, exclude_empty=True):
755 Create a new doctest finder.
757 The optional argument `parser` specifies a class or
758 function that should be used to create new DocTest objects (or
759 objects that implement the same interface as DocTest). The
760 signature for this factory function should match the signature
761 of the DocTest constructor.
763 If the optional argument `recurse` is false, then `find` will
764 only examine the given object, and not any contained objects.
766 If the optional argument `exclude_empty` is false, then `find`
767 will include tests for objects with empty docstrings.
769 self._parser = parser
770 self._verbose = verbose
771 self._recurse = recurse
772 self._exclude_empty = exclude_empty
774 def find(self, obj, name=None, module=None, globs=None, extraglobs=None):
776 Return a list of the DocTests that are defined by the given
777 object's docstring, or by any of its contained objects'
780 The optional parameter `module` is the module that contains
781 the given object. If the module is not specified or is None, then
782 the test finder will attempt to automatically determine the
783 correct module. The object's module is used:
785 - As a default namespace, if `globs` is not specified.
786 - To prevent the DocTestFinder from extracting DocTests
787 from objects that are imported from other modules.
788 - To find the name of the file containing the object.
789 - To help find the line number of the object within its
792 Contained objects whose module does not match `module` are ignored.
794 If `module` is False, no attempt to find the module will be made.
795 This is obscure, of use mostly in tests: if `module` is False, or
796 is None but cannot be found automatically, then all objects are
797 considered to belong to the (non-existent) module, so all contained
798 objects will (recursively) be searched for doctests.
800 The globals for each DocTest is formed by combining `globs`
801 and `extraglobs` (bindings in `extraglobs` override bindings
802 in `globs`). A new copy of the globals dictionary is created
803 for each DocTest. If `globs` is not specified, then it
804 defaults to the module's `__dict__`, if specified, or {}
805 otherwise. If `extraglobs` is not specified, then it defaults
809 # If name was not specified, then extract it from the object.
811 name = getattr(obj, '__name__', None)
813 raise ValueError("DocTestFinder
.find
: name must be given
"
814 "when obj
.__name
__ doesn
't exist: %r" %
817 # Find the module that contains the given object (if obj is
818 # a module, then module=obj.). Note: this may fail, in which
819 # case module will be None.
823 module = inspect.getmodule(obj)
825 # Read the module's source code
. This
is used by
826 # DocTestFinder._find_lineno to find the line number for a
827 # given object's docstring.
829 file = inspect
.getsourcefile(obj
) or inspect
.getfile(obj
)
830 if module
is not None:
831 # Supply the module globals in case the module was
832 # originally loaded via a PEP 302 loader and
833 # file is not a valid filesystem path
834 source_lines
= linecache
.getlines(file, module
.__dict
__)
836 # No access to a loader, so assume it's a normal
838 source_lines
= linecache
.getlines(file)
844 # Initialize globals, and merge in extraglobs.
849 globs
= module
.__dict
__.copy()
852 if extraglobs
is not None:
853 globs
.update(extraglobs
)
854 if '__name__' not in globs
:
855 globs
['__name__'] = '__main__' # provide a default module name
857 # Recursively expore `obj`, extracting DocTests.
859 self
._find
(tests
, obj
, name
, module
, source_lines
, globs
, {})
860 # Sort the tests by alpha order of names, for consistency in
861 # verbose-mode output. This was a feature of doctest in Pythons
862 # <= 2.3 that got lost by accident in 2.4. It was repaired in
867 def _from_module(self
, module
, object):
869 Return true if the given object is defined in the given
874 elif inspect
.getmodule(object) is not None:
875 return module
is inspect
.getmodule(object)
876 elif inspect
.isfunction(object):
877 return module
.__dict
__ is object.func_globals
878 elif inspect
.isclass(object):
879 return module
.__name
__ == object.__module
__
880 elif hasattr(object, '__module__'):
881 return module
.__name
__ == object.__module
__
882 elif isinstance(object, property):
883 return True # [XX] no way not be sure.
885 raise ValueError("object must be a class or function")
887 def _find(self
, tests
, obj
, name
, module
, source_lines
, globs
, seen
):
889 Find tests for the given object and any contained objects, and
893 print 'Finding tests in %s' % name
895 # If we've already processed this object, then ignore it.
900 # Find a test for this object, and add it to the list of tests.
901 test
= self
._get
_test
(obj
, name
, module
, globs
, source_lines
)
905 # Look for tests in a module's contained objects.
906 if inspect
.ismodule(obj
) and self
._recurse
:
907 for valname
, val
in obj
.__dict
__.items():
908 valname
= '%s.%s' % (name
, valname
)
909 # Recurse to functions & classes.
910 if ((inspect
.isfunction(val
) or inspect
.isclass(val
)) and
911 self
._from
_module
(module
, val
)):
912 self
._find
(tests
, val
, valname
, module
, source_lines
,
915 # Look for tests in a module's __test__ dictionary.
916 if inspect
.ismodule(obj
) and self
._recurse
:
917 for valname
, val
in getattr(obj
, '__test__', {}).items():
918 if not isinstance(valname
, basestring
):
919 raise ValueError("DocTestFinder.find: __test__ keys "
920 "must be strings: %r" %
922 if not (inspect
.isfunction(val
) or inspect
.isclass(val
) or
923 inspect
.ismethod(val
) or inspect
.ismodule(val
) or
924 isinstance(val
, basestring
)):
925 raise ValueError("DocTestFinder.find: __test__ values "
926 "must be strings, functions, methods, "
927 "classes, or modules: %r" %
929 valname
= '%s.__test__.%s' % (name
, valname
)
930 self
._find
(tests
, val
, valname
, module
, source_lines
,
933 # Look for tests in a class's contained objects.
934 if inspect
.isclass(obj
) and self
._recurse
:
935 for valname
, val
in obj
.__dict
__.items():
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 >>> tests.sort(key = lambda test: test.name)
1049 >>> for test in tests:
1050 ... print test.name, '->', runner.run(test)
1051 _TestClass -> TestResults(failed=0, attempted=2)
1052 _TestClass.__init__ -> TestResults(failed=0, attempted=2)
1053 _TestClass.get -> TestResults(failed=0, attempted=2)
1054 _TestClass.square -> TestResults(failed=0, attempted=1)
1056 The `summarize` method prints a summary of all the test cases that
1057 have been run by the runner, and returns an aggregated `(f, t)`
1060 >>> runner.summarize(verbose=1)
1061 4 items passed all tests:
1062 2 tests in _TestClass
1063 2 tests in _TestClass.__init__
1064 2 tests in _TestClass.get
1065 1 tests in _TestClass.square
1067 7 passed and 0 failed.
1069 TestResults(failed=0, attempted=7)
1071 The aggregated number of tried examples and failed examples is
1072 also available via the `tries` and `failures` attributes:
1079 The comparison between expected outputs and actual outputs is done
1080 by an `OutputChecker`. This comparison may be customized with a
1081 number of option flags; see the documentation for `testmod` for
1082 more information. If the option flags are insufficient, then the
1083 comparison may also be customized by passing a subclass of
1084 `OutputChecker` to the constructor.
1086 The test runner's display output can be controlled in two ways.
1087 First, an output function (`out) can be passed to
1088 `TestRunner.run`; this function will be called with strings that
1089 should be displayed. It defaults to `sys.stdout.write`. If
1090 capturing the output is not sufficient, then the display output
1091 can be also customized by subclassing DocTestRunner, and
1092 overriding the methods `report_start`, `report_success`,
1093 `report_unexpected_exception`, and `report_failure`.
1095 # This divider string is used to separate failure messages, and to
1096 # separate sections of the summary.
1099 def __init__(self
, checker
=None, verbose
=None, optionflags
=0):
1101 Create a new test runner.
1103 Optional keyword arg `checker` is the `OutputChecker` that
1104 should be used to compare the expected outputs and actual
1105 outputs of doctest examples.
1107 Optional keyword arg 'verbose' prints lots of stuff if true,
1108 only failures if false; by default, it's true iff '-v' is in
1111 Optional argument `optionflags` can be used to control how the
1112 test runner compares expected output to actual output, and how
1113 it displays failures. See the documentation for `testmod` for
1116 self
._checker
= checker
or OutputChecker()
1118 verbose
= '-v' in sys
.argv
1119 self
._verbose
= verbose
1120 self
.optionflags
= optionflags
1121 self
.original_optionflags
= optionflags
1123 # Keep track of the examples we've run.
1128 # Create a fake output target for capturing doctest output.
1129 self
._fakeout
= _SpoofOut()
1131 #/////////////////////////////////////////////////////////////////
1133 #/////////////////////////////////////////////////////////////////
1135 def report_start(self
, out
, test
, example
):
1137 Report that the test runner is about to process the given
1138 example. (Only displays a message if verbose=True)
1142 out('Trying:\n' + _indent(example
.source
) +
1143 'Expecting:\n' + _indent(example
.want
))
1145 out('Trying:\n' + _indent(example
.source
) +
1146 'Expecting nothing\n')
1148 def report_success(self
, out
, test
, example
, got
):
1150 Report that the given example ran successfully. (Only
1151 displays a message if verbose=True)
1156 def report_failure(self
, out
, test
, example
, got
):
1158 Report that the given example failed.
1160 out(self
._failure
_header
(test
, example
) +
1161 self
._checker
.output_difference(example
, got
, self
.optionflags
))
1163 def report_unexpected_exception(self
, out
, test
, example
, exc_info
):
1165 Report that the given example raised an unexpected exception.
1167 out(self
._failure
_header
(test
, example
) +
1168 'Exception raised:\n' + _indent(_exception_traceback(exc_info
)))
1170 def _failure_header(self
, test
, example
):
1171 out
= [self
.DIVIDER
]
1173 if test
.lineno
is not None and example
.lineno
is not None:
1174 lineno
= test
.lineno
+ example
.lineno
+ 1
1177 out
.append('File "%s", line %s, in %s' %
1178 (test
.filename
, lineno
, test
.name
))
1180 out
.append('Line %s, in %s' % (example
.lineno
+1, test
.name
))
1181 out
.append('Failed example:')
1182 source
= example
.source
1183 out
.append(_indent(source
))
1184 return '\n'.join(out
)
1186 #/////////////////////////////////////////////////////////////////
1188 #/////////////////////////////////////////////////////////////////
1190 def __run(self
, test
, compileflags
, out
):
1192 Run the examples in `test`. Write the outcome of each example
1193 with one of the `DocTestRunner.report_*` methods, using the
1194 writer function `out`. `compileflags` is the set of compiler
1195 flags that should be used to execute examples. Return a tuple
1196 `(f, t)`, where `t` is the number of examples tried, and `f`
1197 is the number of examples that failed. The examples are run
1198 in the namespace `test.globs`.
1200 # Keep track of the number of failures and tries.
1201 failures
= tries
= 0
1203 # Save the option flags (since option directives can be used
1205 original_optionflags
= self
.optionflags
1207 SUCCESS
, FAILURE
, BOOM
= range(3) # `outcome` state
1209 check
= self
._checker
.check_output
1211 # Process each example.
1212 for examplenum
, example
in enumerate(test
.examples
):
1214 # If REPORT_ONLY_FIRST_FAILURE is set, then supress
1215 # reporting after the first failure.
1216 quiet
= (self
.optionflags
& REPORT_ONLY_FIRST_FAILURE
and
1219 # Merge in the example's options.
1220 self
.optionflags
= original_optionflags
1222 for (optionflag
, val
) in example
.options
.items():
1224 self
.optionflags |
= optionflag
1226 self
.optionflags
&= ~optionflag
1228 # If 'SKIP' is set, then skip this example.
1229 if self
.optionflags
& SKIP
:
1232 # Record that we started this example.
1235 self
.report_start(out
, test
, example
)
1237 # Use a special filename for compile(), so we can retrieve
1238 # the source code during interactive debugging (see
1239 # __patched_linecache_getlines).
1240 filename
= '<doctest %s[%d]>' % (test
.name
, examplenum
)
1242 # Run the example in the given context (globs), and record
1243 # any exception that gets raised. (But don't intercept
1244 # keyboard interrupts.)
1246 # Don't blink! This is where the user's code gets run.
1247 exec compile(example
.source
, filename
, "single",
1248 compileflags
, 1) in test
.globs
1249 self
.debugger
.set_continue() # ==== Example Finished ====
1251 except KeyboardInterrupt:
1254 exception
= sys
.exc_info()
1255 self
.debugger
.set_continue() # ==== Example Finished ====
1257 got
= self
._fakeout
.getvalue() # the actual output
1258 self
._fakeout
.truncate(0)
1259 outcome
= FAILURE
# guilty until proved innocent or insane
1261 # If the example executed without raising any exceptions,
1262 # verify its output.
1263 if exception
is None:
1264 if check(example
.want
, got
, self
.optionflags
):
1267 # The example raised an exception: check if it was expected.
1269 exc_info
= sys
.exc_info()
1270 exc_msg
= traceback
.format_exception_only(*exc_info
[:2])[-1]
1272 got
+= _exception_traceback(exc_info
)
1274 # If `example.exc_msg` is None, then we weren't expecting
1276 if example
.exc_msg
is None:
1279 # We expected an exception: see whether it matches.
1280 elif check(example
.exc_msg
, exc_msg
, self
.optionflags
):
1283 # Another chance if they didn't care about the detail.
1284 elif self
.optionflags
& IGNORE_EXCEPTION_DETAIL
:
1285 m1
= re
.match(r
'(?:[^:]*\.)?([^:]*:)', example
.exc_msg
)
1286 m2
= re
.match(r
'(?:[^:]*\.)?([^:]*:)', exc_msg
)
1287 if m1
and m2
and check(m1
.group(1), m2
.group(1),
1291 # Report the outcome.
1292 if outcome
is SUCCESS
:
1294 self
.report_success(out
, test
, example
, got
)
1295 elif outcome
is FAILURE
:
1297 self
.report_failure(out
, test
, example
, got
)
1299 elif outcome
is BOOM
:
1301 self
.report_unexpected_exception(out
, test
, example
,
1305 assert False, ("unknown outcome", outcome
)
1307 # Restore the option flags (in case they were modified)
1308 self
.optionflags
= original_optionflags
1310 # Record and return the number of failures and tries.
1311 self
.__record
_outcome
(test
, failures
, tries
)
1312 return TestResults(failures
, tries
)
1314 def __record_outcome(self
, test
, f
, t
):
1316 Record the fact that the given DocTest (`test`) generated `f`
1317 failures out of `t` tried examples.
1319 f2
, t2
= self
._name
2ft
.get(test
.name
, (0,0))
1320 self
._name
2ft
[test
.name
] = (f
+f2
, t
+t2
)
1324 __LINECACHE_FILENAME_RE
= re
.compile(r
'<doctest '
1325 r
'(?P<name>[\w\.]+)'
1326 r
'\[(?P<examplenum>\d+)\]>$')
1327 def __patched_linecache_getlines(self
, filename
, module_globals
=None):
1328 m
= self
.__LINECACHE
_FILENAME
_RE
.match(filename
)
1329 if m
and m
.group('name') == self
.test
.name
:
1330 example
= self
.test
.examples
[int(m
.group('examplenum'))]
1331 source
= example
.source
.encode('ascii', 'backslashreplace')
1332 return source
.splitlines(True)
1334 return self
.save_linecache_getlines(filename
, module_globals
)
1336 def run(self
, test
, compileflags
=None, out
=None, clear_globs
=True):
1338 Run the examples in `test`, and display the results using the
1339 writer function `out`.
1341 The examples are run in the namespace `test.globs`. If
1342 `clear_globs` is true (the default), then this namespace will
1343 be cleared after the test runs, to help with garbage
1344 collection. If you would like to examine the namespace after
1345 the test completes, then use `clear_globs=False`.
1347 `compileflags` gives the set of flags that should be used by
1348 the Python compiler when running the examples. If not
1349 specified, then it will default to the set of future-import
1350 flags that apply to `globs`.
1352 The output of each example is checked using
1353 `DocTestRunner.check_output`, and the results are formatted by
1354 the `DocTestRunner.report_*` methods.
1358 if compileflags
is None:
1359 compileflags
= _extract_future_flags(test
.globs
)
1361 save_stdout
= sys
.stdout
1363 out
= save_stdout
.write
1364 sys
.stdout
= self
._fakeout
1366 # Patch pdb.set_trace to restore sys.stdout during interactive
1367 # debugging (so it's not still redirected to self._fakeout).
1368 # Note that the interactive output will go to *our*
1369 # save_stdout, even if that's not the real sys.stdout; this
1370 # allows us to write test cases for the set_trace behavior.
1371 save_set_trace
= pdb
.set_trace
1372 self
.debugger
= _OutputRedirectingPdb(save_stdout
)
1373 self
.debugger
.reset()
1374 pdb
.set_trace
= self
.debugger
.set_trace
1376 # Patch linecache.getlines, so we can see the example's source
1377 # when we're inside the debugger.
1378 self
.save_linecache_getlines
= linecache
.getlines
1379 linecache
.getlines
= self
.__patched
_linecache
_getlines
1382 return self
.__run
(test
, compileflags
, out
)
1384 sys
.stdout
= save_stdout
1385 pdb
.set_trace
= save_set_trace
1386 linecache
.getlines
= self
.save_linecache_getlines
1390 #/////////////////////////////////////////////////////////////////
1392 #/////////////////////////////////////////////////////////////////
1393 def summarize(self
, verbose
=None):
1395 Print a summary of all the test cases that have been run by
1396 this DocTestRunner, and return a tuple `(f, t)`, where `f` is
1397 the total number of failed examples, and `t` is the total
1398 number of tried examples.
1400 The optional `verbose` argument controls how detailed the
1401 summary is. If the verbosity is not specified, then the
1402 DocTestRunner's verbosity is used.
1405 verbose
= self
._verbose
1410 for x
in self
._name
2ft
.items():
1416 notests
.append(name
)
1418 passed
.append( (name
, t
) )
1423 print len(notests
), "items had no tests:"
1425 for thing
in notests
:
1428 print len(passed
), "items passed all tests:"
1430 for thing
, count
in passed
:
1431 print " %3d tests in %s" % (count
, thing
)
1434 print len(failed
), "items had failures:"
1436 for thing
, (f
, t
) in failed
:
1437 print " %3d of %3d in %s" % (f
, t
, thing
)
1439 print totalt
, "tests in", len(self
._name
2ft
), "items."
1440 print totalt
- totalf
, "passed and", totalf
, "failed."
1442 print "***Test Failed***", totalf
, "failures."
1444 print "Test passed."
1445 return TestResults(totalf
, totalt
)
1447 #/////////////////////////////////////////////////////////////////
1448 # Backward compatibility cruft to maintain doctest.master.
1449 #/////////////////////////////////////////////////////////////////
1450 def merge(self
, other
):
1452 for name
, (f
, t
) in other
._name
2ft
.items():
1454 # Don't print here by default, since doing
1455 # so breaks some of the buildbots
1456 #print "*** DocTestRunner.merge: '" + name + "' in both" \
1457 # " testers; summing outcomes."
1463 class OutputChecker
:
1465 A class used to check the whether the actual output from a doctest
1466 example matches the expected output. `OutputChecker` defines two
1467 methods: `check_output`, which compares a given pair of outputs,
1468 and returns true if they match; and `output_difference`, which
1469 returns a string describing the differences between two outputs.
1471 def check_output(self
, want
, got
, optionflags
):
1473 Return True iff the actual output from an example (`got`)
1474 matches the expected output (`want`). These strings are
1475 always considered to match if they are identical; but
1476 depending on what option flags the test runner is using,
1477 several non-exact match types are also possible. See the
1478 documentation for `TestRunner` for more information about
1481 # Handle the common case first, for efficiency:
1482 # if they're string-identical, always return true.
1486 # The values True and False replaced 1 and 0 as the return
1487 # value for boolean comparisons in Python 2.3.
1488 if not (optionflags
& DONT_ACCEPT_TRUE_FOR_1
):
1489 if (got
,want
) == ("True\n", "1\n"):
1491 if (got
,want
) == ("False\n", "0\n"):
1494 # <BLANKLINE> can be used as a special sequence to signify a
1495 # blank line, unless the DONT_ACCEPT_BLANKLINE flag is used.
1496 if not (optionflags
& DONT_ACCEPT_BLANKLINE
):
1497 # Replace <BLANKLINE> in want with a blank line.
1498 want
= re
.sub('(?m)^%s\s*?$' % re
.escape(BLANKLINE_MARKER
),
1500 # If a line in got contains only spaces, then remove the
1502 got
= re
.sub('(?m)^\s*?$', '', got
)
1506 # This flag causes doctest to ignore any differences in the
1507 # contents of whitespace strings. Note that this can be used
1508 # in conjunction with the ELLIPSIS flag.
1509 if optionflags
& NORMALIZE_WHITESPACE
:
1510 got
= ' '.join(got
.split())
1511 want
= ' '.join(want
.split())
1515 # The ELLIPSIS flag says to let the sequence "..." in `want`
1516 # match any substring in `got`.
1517 if optionflags
& ELLIPSIS
:
1518 if _ellipsis_match(want
, got
):
1521 # We didn't find any match; return false.
1524 # Should we do a fancy diff?
1525 def _do_a_fancy_diff(self
, want
, got
, optionflags
):
1526 # Not unless they asked for a fancy diff.
1527 if not optionflags
& (REPORT_UDIFF |
1532 # If expected output uses ellipsis, a meaningful fancy diff is
1533 # too hard ... or maybe not. In two real-life failures Tim saw,
1534 # a diff was a major help anyway, so this is commented out.
1535 # [todo] _ellipsis_match() knows which pieces do and don't match,
1536 # and could be the basis for a kick-ass diff in this case.
1537 ##if optionflags & ELLIPSIS and ELLIPSIS_MARKER in want:
1540 # ndiff does intraline difference marking, so can be useful even
1541 # for 1-line differences.
1542 if optionflags
& REPORT_NDIFF
:
1545 # The other diff types need at least a few lines to be helpful.
1546 return want
.count('\n') > 2 and got
.count('\n') > 2
1548 def output_difference(self
, example
, got
, optionflags
):
1550 Return a string describing the differences between the
1551 expected output for a given example (`example`) and the actual
1552 output (`got`). `optionflags` is the set of option flags used
1553 to compare `want` and `got`.
1556 # If <BLANKLINE>s are being used, then replace blank lines
1557 # with <BLANKLINE> in the actual output string.
1558 if not (optionflags
& DONT_ACCEPT_BLANKLINE
):
1559 got
= re
.sub('(?m)^[ ]*(?=\n)', BLANKLINE_MARKER
, got
)
1561 # Check if we should use diff.
1562 if self
._do
_a
_fancy
_diff
(want
, got
, optionflags
):
1563 # Split want & got into lines.
1564 want_lines
= want
.splitlines(True) # True == keep line ends
1565 got_lines
= got
.splitlines(True)
1566 # Use difflib to find their differences.
1567 if optionflags
& REPORT_UDIFF
:
1568 diff
= difflib
.unified_diff(want_lines
, got_lines
, n
=2)
1569 diff
= list(diff
)[2:] # strip the diff header
1570 kind
= 'unified diff with -expected +actual'
1571 elif optionflags
& REPORT_CDIFF
:
1572 diff
= difflib
.context_diff(want_lines
, got_lines
, n
=2)
1573 diff
= list(diff
)[2:] # strip the diff header
1574 kind
= 'context diff with expected followed by actual'
1575 elif optionflags
& REPORT_NDIFF
:
1576 engine
= difflib
.Differ(charjunk
=difflib
.IS_CHARACTER_JUNK
)
1577 diff
= list(engine
.compare(want_lines
, got_lines
))
1578 kind
= 'ndiff with -expected +actual'
1580 assert 0, 'Bad diff option'
1581 # Remove trailing whitespace on diff output.
1582 diff
= [line
.rstrip() + '\n' for line
in diff
]
1583 return 'Differences (%s):\n' % kind
+ _indent(''.join(diff
))
1585 # If we're not using diff, then simply list the expected
1586 # output followed by the actual output.
1588 return 'Expected:\n%sGot:\n%s' % (_indent(want
), _indent(got
))
1590 return 'Expected:\n%sGot nothing\n' % _indent(want
)
1592 return 'Expected nothing\nGot:\n%s' % _indent(got
)
1594 return 'Expected nothing\nGot nothing\n'
1596 class DocTestFailure(Exception):
1597 """A DocTest example has failed in debugging mode.
1599 The exception instance has variables:
1601 - test: the DocTest object being run
1603 - example: the Example object that failed
1605 - got: the actual output
1607 def __init__(self
, test
, example
, got
):
1609 self
.example
= example
1613 return str(self
.test
)
1615 class UnexpectedException(Exception):
1616 """A DocTest example has encountered an unexpected exception
1618 The exception instance has variables:
1620 - test: the DocTest object being run
1622 - example: the Example object that failed
1624 - exc_info: the exception info
1626 def __init__(self
, test
, example
, exc_info
):
1628 self
.example
= example
1629 self
.exc_info
= exc_info
1632 return str(self
.test
)
1634 class DebugRunner(DocTestRunner
):
1635 r
"""Run doc tests but raise an exception as soon as there is a failure.
1637 If an unexpected exception occurs, an UnexpectedException is raised.
1638 It contains the test, the example, and the original exception:
1640 >>> runner = DebugRunner(verbose=False)
1641 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
1642 ... {}, 'foo', 'foo.py', 0)
1644 ... runner.run(test)
1645 ... except UnexpectedException, failure:
1648 >>> failure.test is test
1651 >>> failure.example.want
1654 >>> exc_info = failure.exc_info
1655 >>> raise exc_info[0], exc_info[1], exc_info[2]
1656 Traceback (most recent call last):
1660 We wrap the original exception to give the calling application
1661 access to the test and example information.
1663 If the output doesn't match, then a DocTestFailure is raised:
1665 >>> test = DocTestParser().get_doctest('''
1669 ... ''', {}, 'foo', 'foo.py', 0)
1672 ... runner.run(test)
1673 ... except DocTestFailure, failure:
1676 DocTestFailure objects provide access to the test:
1678 >>> failure.test is test
1681 As well as to the example:
1683 >>> failure.example.want
1686 and the actual output:
1691 If a failure or error occurs, the globals are left intact:
1693 >>> del test.globs['__builtins__']
1697 >>> test = DocTestParser().get_doctest('''
1699 ... >>> raise KeyError
1700 ... ''', {}, 'foo', 'foo.py', 0)
1702 >>> runner.run(test)
1703 Traceback (most recent call last):
1705 UnexpectedException: <DocTest foo from foo.py:0 (2 examples)>
1707 >>> del test.globs['__builtins__']
1711 But the globals are cleared if there is no error:
1713 >>> test = DocTestParser().get_doctest('''
1715 ... ''', {}, 'foo', 'foo.py', 0)
1717 >>> runner.run(test)
1718 TestResults(failed=0, attempted=1)
1725 def run(self
, test
, compileflags
=None, out
=None, clear_globs
=True):
1726 r
= DocTestRunner
.run(self
, test
, compileflags
, out
, False)
1731 def report_unexpected_exception(self
, out
, test
, example
, exc_info
):
1732 raise UnexpectedException(test
, example
, exc_info
)
1734 def report_failure(self
, out
, test
, example
, got
):
1735 raise DocTestFailure(test
, example
, got
)
1737 ######################################################################
1738 ## 6. Test Functions
1739 ######################################################################
1740 # These should be backwards compatible.
1742 # For backward compatibility, a global instance of a DocTestRunner
1743 # class, updated by testmod.
1746 def testmod(m
=None, name
=None, globs
=None, verbose
=None,
1747 report
=True, optionflags
=0, extraglobs
=None,
1748 raise_on_error
=False, exclude_empty
=False):
1749 """m=None, name=None, globs=None, verbose=None, report=True,
1750 optionflags=0, extraglobs=None, raise_on_error=False,
1753 Test examples in docstrings in functions and classes reachable
1754 from module m (or the current module if m is not supplied), starting
1757 Also test examples reachable from dict m.__test__ if it exists and is
1758 not None. m.__test__ maps names to functions, classes and strings;
1759 function and class docstrings are tested even if the name is private;
1760 strings are tested directly, as if they were docstrings.
1762 Return (#failures, #tests).
1764 See doctest.__doc__ for an overview.
1766 Optional keyword arg "name" gives the name of the module; by default
1769 Optional keyword arg "globs" gives a dict to be used as the globals
1770 when executing examples; by default, use m.__dict__. A copy of this
1771 dict is actually used for each docstring, so that each docstring's
1772 examples start with a clean slate.
1774 Optional keyword arg "extraglobs" gives a dictionary that should be
1775 merged into the globals that are used to execute examples. By
1776 default, no extra globals are used. This is new in 2.4.
1778 Optional keyword arg "verbose" prints lots of stuff if true, prints
1779 only failures if false; by default, it's true iff "-v" is in sys.argv.
1781 Optional keyword arg "report" prints a summary at the end when true,
1782 else prints nothing at the end. In verbose mode, the summary is
1783 detailed, else very brief (in fact, empty if all tests passed).
1785 Optional keyword arg "optionflags" or's together module constants,
1786 and defaults to 0. This is new in 2.3. Possible values (see the
1789 DONT_ACCEPT_TRUE_FOR_1
1790 DONT_ACCEPT_BLANKLINE
1791 NORMALIZE_WHITESPACE
1794 IGNORE_EXCEPTION_DETAIL
1798 REPORT_ONLY_FIRST_FAILURE
1800 Optional keyword arg "raise_on_error" raises an exception on the
1801 first unexpected exception or failure. This allows failures to be
1802 post-mortem debugged.
1804 Advanced tomfoolery: testmod runs methods of a local instance of
1805 class doctest.Tester, then merges the results into (or creates)
1806 global Tester instance doctest.master. Methods of doctest.master
1807 can be called directly too, if you want to do something unusual.
1808 Passing report=0 to testmod is especially useful then, to delay
1809 displaying a summary. Invoke doctest.master.summarize(verbose)
1810 when you're done fiddling.
1814 # If no module was given, then use __main__.
1816 # DWA - m will still be None if this wasn't invoked from the command
1817 # line, in which case the following TypeError is about as good an error
1818 # as we should expect
1819 m
= sys
.modules
.get('__main__')
1821 # Check that we were actually given a module.
1822 if not inspect
.ismodule(m
):
1823 raise TypeError("testmod: module required; %r" % (m
,))
1825 # If no name was given, then use the module's name.
1829 # Find, parse, and run all tests in the given module.
1830 finder
= DocTestFinder(exclude_empty
=exclude_empty
)
1833 runner
= DebugRunner(verbose
=verbose
, optionflags
=optionflags
)
1835 runner
= DocTestRunner(verbose
=verbose
, optionflags
=optionflags
)
1837 for test
in finder
.find(m
, name
, globs
=globs
, extraglobs
=extraglobs
):
1846 master
.merge(runner
)
1848 return TestResults(runner
.failures
, runner
.tries
)
1850 def testfile(filename
, module_relative
=True, name
=None, package
=None,
1851 globs
=None, verbose
=None, report
=True, optionflags
=0,
1852 extraglobs
=None, raise_on_error
=False, parser
=DocTestParser(),
1855 Test examples in the given file. Return (#failures, #tests).
1857 Optional keyword arg "module_relative" specifies how filenames
1858 should be interpreted:
1860 - If "module_relative" is True (the default), then "filename"
1861 specifies a module-relative path. By default, this path is
1862 relative to the calling module's directory; but if the
1863 "package" argument is specified, then it is relative to that
1864 package. To ensure os-independence, "filename" should use
1865 "/" characters to separate path segments, and should not
1866 be an absolute path (i.e., it may not begin with "/").
1868 - If "module_relative" is False, then "filename" specifies an
1869 os-specific path. The path may be absolute or relative (to
1870 the current working directory).
1872 Optional keyword arg "name" gives the name of the test; by default
1873 use the file's basename.
1875 Optional keyword argument "package" is a Python package or the
1876 name of a Python package whose directory should be used as the
1877 base directory for a module relative filename. If no package is
1878 specified, then the calling module's directory is used as the base
1879 directory for module relative filenames. It is an error to
1880 specify "package" if "module_relative" is False.
1882 Optional keyword arg "globs" gives a dict to be used as the globals
1883 when executing examples; by default, use {}. A copy of this dict
1884 is actually used for each docstring, so that each docstring's
1885 examples start with a clean slate.
1887 Optional keyword arg "extraglobs" gives a dictionary that should be
1888 merged into the globals that are used to execute examples. By
1889 default, no extra globals are used.
1891 Optional keyword arg "verbose" prints lots of stuff if true, prints
1892 only failures if false; by default, it's true iff "-v" is in sys.argv.
1894 Optional keyword arg "report" prints a summary at the end when true,
1895 else prints nothing at the end. In verbose mode, the summary is
1896 detailed, else very brief (in fact, empty if all tests passed).
1898 Optional keyword arg "optionflags" or's together module constants,
1899 and defaults to 0. Possible values (see the docs for details):
1901 DONT_ACCEPT_TRUE_FOR_1
1902 DONT_ACCEPT_BLANKLINE
1903 NORMALIZE_WHITESPACE
1906 IGNORE_EXCEPTION_DETAIL
1910 REPORT_ONLY_FIRST_FAILURE
1912 Optional keyword arg "raise_on_error" raises an exception on the
1913 first unexpected exception or failure. This allows failures to be
1914 post-mortem debugged.
1916 Optional keyword arg "parser" specifies a DocTestParser (or
1917 subclass) that should be used to extract tests from the files.
1919 Optional keyword arg "encoding" specifies an encoding that should
1920 be used to convert the file to unicode.
1922 Advanced tomfoolery: testmod runs methods of a local instance of
1923 class doctest.Tester, then merges the results into (or creates)
1924 global Tester instance doctest.master. Methods of doctest.master
1925 can be called directly too, if you want to do something unusual.
1926 Passing report=0 to testmod is especially useful then, to delay
1927 displaying a summary. Invoke doctest.master.summarize(verbose)
1928 when you're done fiddling.
1932 if package
and not module_relative
:
1933 raise ValueError("Package may only be specified for module-"
1936 # Relativize the path
1937 text
, filename
= _load_testfile(filename
, package
, module_relative
)
1939 # If no name was given, then use the file's name.
1941 name
= os
.path
.basename(filename
)
1943 # Assemble the globals.
1947 globs
= globs
.copy()
1948 if extraglobs
is not None:
1949 globs
.update(extraglobs
)
1950 if '__name__' not in globs
:
1951 globs
['__name__'] = '__main__'
1954 runner
= DebugRunner(verbose
=verbose
, optionflags
=optionflags
)
1956 runner
= DocTestRunner(verbose
=verbose
, optionflags
=optionflags
)
1958 if encoding
is not None:
1959 text
= text
.decode(encoding
)
1961 # Read the file, convert it to a test, and run it.
1962 test
= parser
.get_doctest(text
, globs
, name
, filename
, 0)
1971 master
.merge(runner
)
1973 return TestResults(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, optionflags
=0):
2007 warnings
.warn("class Tester is deprecated; "
2008 "use class doctest.DocTestRunner instead",
2009 DeprecationWarning, stacklevel
=2)
2010 if mod
is None and globs
is None:
2011 raise TypeError("Tester.__init__: must specify mod or globs")
2012 if mod
is not None and not inspect
.ismodule(mod
):
2013 raise TypeError("Tester.__init__: mod must be a module; %r" %
2016 globs
= mod
.__dict
__
2019 self
.verbose
= verbose
2020 self
.optionflags
= optionflags
2021 self
.testfinder
= DocTestFinder()
2022 self
.testrunner
= DocTestRunner(verbose
=verbose
,
2023 optionflags
=optionflags
)
2025 def runstring(self
, s
, name
):
2026 test
= DocTestParser().get_doctest(s
, self
.globs
, name
, None, None)
2028 print "Running string", name
2029 (f
,t
) = self
.testrunner
.run(test
)
2031 print f
, "of", t
, "examples failed in string", name
2032 return TestResults(f
,t
)
2034 def rundoc(self
, object, name
=None, module
=None):
2036 tests
= self
.testfinder
.find(object, name
, module
=module
,
2039 (f2
, t2
) = self
.testrunner
.run(test
)
2040 (f
,t
) = (f
+f2
, t
+t2
)
2041 return TestResults(f
,t
)
2043 def rundict(self
, d
, name
, module
=None):
2045 m
= types
.ModuleType(name
)
2046 m
.__dict
__.update(d
)
2049 return self
.rundoc(m
, name
, module
)
2051 def run__test__(self
, d
, name
):
2053 m
= types
.ModuleType(name
)
2055 return self
.rundoc(m
, name
)
2057 def summarize(self
, verbose
=None):
2058 return self
.testrunner
.summarize(verbose
)
2060 def merge(self
, other
):
2061 self
.testrunner
.merge(other
.testrunner
)
2063 ######################################################################
2064 ## 8. Unittest Support
2065 ######################################################################
2067 _unittest_reportflags
= 0
2069 def set_unittest_reportflags(flags
):
2070 """Sets the unittest option flags.
2072 The old flag is returned so that a runner could restore the old
2073 value if it wished to:
2076 >>> old = doctest._unittest_reportflags
2077 >>> doctest.set_unittest_reportflags(REPORT_NDIFF |
2078 ... REPORT_ONLY_FIRST_FAILURE) == old
2081 >>> doctest._unittest_reportflags == (REPORT_NDIFF |
2082 ... REPORT_ONLY_FIRST_FAILURE)
2085 Only reporting flags can be set:
2087 >>> doctest.set_unittest_reportflags(ELLIPSIS)
2088 Traceback (most recent call last):
2090 ValueError: ('Only reporting flags allowed', 8)
2092 >>> doctest.set_unittest_reportflags(old) == (REPORT_NDIFF |
2093 ... REPORT_ONLY_FIRST_FAILURE)
2096 global _unittest_reportflags
2098 if (flags
& REPORTING_FLAGS
) != flags
:
2099 raise ValueError("Only reporting flags allowed", flags
)
2100 old
= _unittest_reportflags
2101 _unittest_reportflags
= flags
2105 class DocTestCase(unittest
.TestCase
):
2107 def __init__(self
, test
, optionflags
=0, setUp
=None, tearDown
=None,
2110 unittest
.TestCase
.__init
__(self
)
2111 self
._dt
_optionflags
= optionflags
2112 self
._dt
_checker
= checker
2113 self
._dt
_test
= test
2114 self
._dt
_setUp
= setUp
2115 self
._dt
_tearDown
= tearDown
2118 test
= self
._dt
_test
2120 if self
._dt
_setUp
is not None:
2121 self
._dt
_setUp
(test
)
2124 test
= self
._dt
_test
2126 if self
._dt
_tearDown
is not None:
2127 self
._dt
_tearDown
(test
)
2132 test
= self
._dt
_test
2135 optionflags
= self
._dt
_optionflags
2137 if not (optionflags
& REPORTING_FLAGS
):
2138 # The option flags don't include any reporting flags,
2139 # so add the default reporting flags
2140 optionflags |
= _unittest_reportflags
2142 runner
= DocTestRunner(optionflags
=optionflags
,
2143 checker
=self
._dt
_checker
, verbose
=False)
2146 runner
.DIVIDER
= "-"*70
2147 failures
, tries
= runner
.run(
2148 test
, out
=new
.write
, clear_globs
=False)
2153 raise self
.failureException(self
.format_failure(new
.getvalue()))
2155 def format_failure(self
, err
):
2156 test
= self
._dt
_test
2157 if test
.lineno
is None:
2158 lineno
= 'unknown line number'
2160 lineno
= '%s' % test
.lineno
2161 lname
= '.'.join(test
.name
.split('.')[-1:])
2162 return ('Failed doctest test for %s\n'
2163 ' File "%s", line %s, in %s\n\n%s'
2164 % (test
.name
, test
.filename
, lineno
, lname
, err
)
2168 r
"""Run the test case without results and without catching exceptions
2170 The unit test framework includes a debug method on test cases
2171 and test suites to support post-mortem debugging. The test code
2172 is run in such a way that errors are not caught. This way a
2173 caller can catch the errors and initiate post-mortem debugging.
2175 The DocTestCase provides a debug method that raises
2176 UnexpectedException errors if there is an unexepcted
2179 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
2180 ... {}, 'foo', 'foo.py', 0)
2181 >>> case = DocTestCase(test)
2184 ... except UnexpectedException, failure:
2187 The UnexpectedException contains the test, the example, and
2188 the original exception:
2190 >>> failure.test is test
2193 >>> failure.example.want
2196 >>> exc_info = failure.exc_info
2197 >>> raise exc_info[0], exc_info[1], exc_info[2]
2198 Traceback (most recent call last):
2202 If the output doesn't match, then a DocTestFailure is raised:
2204 >>> test = DocTestParser().get_doctest('''
2208 ... ''', {}, 'foo', 'foo.py', 0)
2209 >>> case = DocTestCase(test)
2213 ... except DocTestFailure, failure:
2216 DocTestFailure objects provide access to the test:
2218 >>> failure.test is test
2221 As well as to the example:
2223 >>> failure.example.want
2226 and the actual output:
2234 runner
= DebugRunner(optionflags
=self
._dt
_optionflags
,
2235 checker
=self
._dt
_checker
, verbose
=False)
2236 runner
.run(self
._dt
_test
, clear_globs
=False)
2240 return self
._dt
_test
.name
2243 name
= self
._dt
_test
.name
.split('.')
2244 return "%s (%s)" % (name
[-1], '.'.join(name
[:-1]))
2248 def shortDescription(self
):
2249 return "Doctest: " + self
._dt
_test
.name
2251 class SkipDocTestCase(DocTestCase
):
2253 DocTestCase
.__init
__(self
, None)
2256 self
.skipTest("DocTestSuite will not work with -O2 and above")
2258 def test_skip(self
):
2261 def shortDescription(self
):
2262 return "Skipping tests from %s" % module
.__name
__
2264 def DocTestSuite(module
=None, globs
=None, extraglobs
=None, test_finder
=None,
2267 Convert doctest tests for a module to a unittest test suite.
2269 This converts each documentation string in a module that
2270 contains doctest tests to a unittest test case. If any of the
2271 tests in a doc string fail, then the test case fails. An exception
2272 is raised showing the name of the file containing the test and a
2273 (sometimes approximate) line number.
2275 The `module` argument provides the module to be tested. The argument
2276 can be either a module or a module name.
2278 If no argument is given, the calling module is used.
2280 A number of options may be provided as keyword arguments:
2283 A set-up function. This is called before running the
2284 tests in each file. The setUp function will be passed a DocTest
2285 object. The setUp function can access the test globals as the
2286 globs attribute of the test passed.
2289 A tear-down function. This is called after running the
2290 tests in each file. The tearDown function will be passed a DocTest
2291 object. The tearDown function can access the test globals as the
2292 globs attribute of the test passed.
2295 A dictionary containing initial global variables for the tests.
2298 A set of doctest option flags expressed as an integer.
2301 if test_finder
is None:
2302 test_finder
= DocTestFinder()
2304 module
= _normalize_module(module
)
2305 tests
= test_finder
.find(module
, globs
=globs
, extraglobs
=extraglobs
)
2307 if not tests
and sys
.flags
.optimize
>=2:
2308 # Skip doctests when running with -O2
2309 suite
= unittest
.TestSuite()
2310 suite
.addTest(SkipDocTestCase())
2313 # Why do we want to do this? Because it reveals a bug that might
2314 # otherwise be hidden.
2315 raise ValueError(module
, "has no tests")
2318 suite
= unittest
.TestSuite()
2321 if len(test
.examples
) == 0:
2323 if not test
.filename
:
2324 filename
= module
.__file
__
2325 if filename
[-4:] in (".pyc", ".pyo"):
2326 filename
= filename
[:-1]
2327 test
.filename
= filename
2328 suite
.addTest(DocTestCase(test
, **options
))
2332 class DocFileCase(DocTestCase
):
2335 return '_'.join(self
._dt
_test
.name
.split('.'))
2338 return self
._dt
_test
.filename
2341 def format_failure(self
, err
):
2342 return ('Failed doctest test for %s\n File "%s", line 0\n\n%s'
2343 % (self
._dt
_test
.name
, self
._dt
_test
.filename
, err
)
2346 def DocFileTest(path
, module_relative
=True, package
=None,
2347 globs
=None, parser
=DocTestParser(),
2348 encoding
=None, **options
):
2352 globs
= globs
.copy()
2354 if package
and not module_relative
:
2355 raise ValueError("Package may only be specified for module-"
2358 # Relativize the path.
2359 doc
, path
= _load_testfile(path
, package
, module_relative
)
2361 if "__file__" not in globs
:
2362 globs
["__file__"] = path
2364 # Find the file and read it.
2365 name
= os
.path
.basename(path
)
2367 # If an encoding is specified, use it to convert the file to unicode
2368 if encoding
is not None:
2369 doc
= doc
.decode(encoding
)
2371 # Convert it to a test, and wrap it in a DocFileCase.
2372 test
= parser
.get_doctest(doc
, globs
, name
, path
, 0)
2373 return DocFileCase(test
, **options
)
2375 def DocFileSuite(*paths
, **kw
):
2376 """A unittest suite for one or more doctest files.
2378 The path to each doctest file is given as a string; the
2379 interpretation of that string depends on the keyword argument
2382 A number of options may be provided as keyword arguments:
2385 If "module_relative" is True, then the given file paths are
2386 interpreted as os-independent module-relative paths. By
2387 default, these paths are relative to the calling module's
2388 directory; but if the "package" argument is specified, then
2389 they are relative to that package. To ensure os-independence,
2390 "filename" should use "/" characters to separate path
2391 segments, and may not be an absolute path (i.e., it may not
2394 If "module_relative" is False, then the given file paths are
2395 interpreted as os-specific paths. These paths may be absolute
2396 or relative (to the current working directory).
2399 A Python package or the name of a Python package whose directory
2400 should be used as the base directory for module relative paths.
2401 If "package" is not specified, then the calling module's
2402 directory is used as the base directory for module relative
2403 filenames. It is an error to specify "package" if
2404 "module_relative" is False.
2407 A set-up function. This is called before running the
2408 tests in each file. The setUp function will be passed a DocTest
2409 object. The setUp function can access the test globals as the
2410 globs attribute of the test passed.
2413 A tear-down function. This is called after running the
2414 tests in each file. The tearDown function will be passed a DocTest
2415 object. The tearDown function can access the test globals as the
2416 globs attribute of the test passed.
2419 A dictionary containing initial global variables for the tests.
2422 A set of doctest option flags expressed as an integer.
2425 A DocTestParser (or subclass) that should be used to extract
2426 tests from the files.
2429 An encoding that will be used to convert the files to unicode.
2431 suite
= unittest
.TestSuite()
2433 # We do this here so that _normalize_module is called at the right
2434 # level. If it were called in DocFileTest, then this function
2435 # would be the caller and we might guess the package incorrectly.
2436 if kw
.get('module_relative', True):
2437 kw
['package'] = _normalize_module(kw
.get('package'))
2440 suite
.addTest(DocFileTest(path
, **kw
))
2444 ######################################################################
2445 ## 9. Debugging Support
2446 ######################################################################
2448 def script_from_examples(s
):
2449 r
"""Extract script from text with examples.
2451 Converts text with examples to a Python script. Example input is
2452 converted to regular code. Example output and all other words
2453 are converted to comments:
2456 ... Here are examples of simple math.
2458 ... Python has super accurate integer addition
2463 ... And very friendly error messages:
2470 ... You can use logic if you want:
2480 >>> print script_from_examples(text)
2481 # Here are examples of simple math.
2483 # Python has super accurate integer addition
2489 # And very friendly error messages:
2497 # You can use logic if you want:
2507 for piece
in DocTestParser().parse(s
):
2508 if isinstance(piece
, Example
):
2509 # Add the example's source code (strip trailing NL)
2510 output
.append(piece
.source
[:-1])
2511 # Add the expected output:
2514 output
.append('# Expected:')
2515 output
+= ['## '+l
for l
in want
.split('\n')[:-1]]
2517 # Add non-example text.
2518 output
+= [_comment_line(l
)
2519 for l
in piece
.split('\n')[:-1]]
2521 # Trim junk on both ends.
2522 while output
and output
[-1] == '#':
2524 while output
and output
[0] == '#':
2526 # Combine the output, and return it.
2527 # Add a courtesy newline to prevent exec from choking (see bug #1172785)
2528 return '\n'.join(output
) + '\n'
2530 def testsource(module
, name
):
2531 """Extract the test sources from a doctest docstring as a script.
2533 Provide the module (or dotted name of the module) containing the
2534 test to be debugged and the name (within the module) of the object
2535 with the doc string with tests to be debugged.
2537 module
= _normalize_module(module
)
2538 tests
= DocTestFinder().find(module
)
2539 test
= [t
for t
in tests
if t
.name
== name
]
2541 raise ValueError(name
, "not found in tests")
2543 testsrc
= script_from_examples(test
.docstring
)
2546 def debug_src(src
, pm
=False, globs
=None):
2547 """Debug a single doctest docstring, in argument `src`'"""
2548 testsrc
= script_from_examples(src
)
2549 debug_script(testsrc
, pm
, globs
)
2551 def debug_script(src
, pm
=False, globs
=None):
2552 "Debug a test script. `src` is the script, as a string."
2555 # Note that tempfile.NameTemporaryFile() cannot be used. As the
2556 # docs say, a file so created cannot be opened by name a second time
2557 # on modern Windows boxes, and execfile() needs to open it.
2558 srcfilename
= tempfile
.mktemp(".py", "doctestdebug")
2559 f
= open(srcfilename
, 'w')
2565 globs
= globs
.copy()
2571 execfile(srcfilename
, globs
, globs
)
2573 print sys
.exc_info()[1]
2574 pdb
.post_mortem(sys
.exc_info()[2])
2576 # Note that %r is vital here. '%s' instead can, e.g., cause
2577 # backslashes to get treated as metacharacters on Windows.
2578 pdb
.run("execfile(%r)" % srcfilename
, globs
, globs
)
2581 os
.remove(srcfilename
)
2583 def debug(module
, name
, pm
=False):
2584 """Debug a single doctest docstring.
2586 Provide the module (or dotted name of the module) containing the
2587 test to be debugged and the name (within the module) of the object
2588 with the docstring with tests to be debugged.
2590 module
= _normalize_module(module
)
2591 testsrc
= testsource(module
, name
)
2592 debug_script(testsrc
, pm
, module
.__dict
__)
2594 ######################################################################
2595 ## 10. Example Usage
2596 ######################################################################
2599 A pointless class, for sanity-checking of docstring testing.
2605 >>> _TestClass(13).get() + _TestClass(-12).get()
2607 >>> hex(_TestClass(13).square().get())
2611 def __init__(self
, val
):
2612 """val -> _TestClass object with associated value val.
2614 >>> t = _TestClass(123)
2622 """square() -> square TestClass's associated value
2624 >>> _TestClass(13).square().get()
2628 self
.val
= self
.val
** 2
2632 """get() -> return TestClass's associated value.
2634 >>> x = _TestClass(-42)
2641 __test__
= {"_TestClass": _TestClass
,
2643 Example of a string object, searched as-is.
2649 "bool-int equivalence": r
"""
2650 In 2.2, boolean expressions displayed
2651 0 or 1. By default, we still accept
2652 them. This can be disabled by passing
2653 DONT_ACCEPT_TRUE_FOR_1 to the new
2654 optionflags argument.
2666 Blank lines can be marked with <BLANKLINE>:
2667 >>> print 'foo\n\nbar\n'
2675 If the ellipsis flag is used, then '...' can be used to
2676 elide substrings in the desired output:
2677 >>> print range(1000) #doctest: +ELLIPSIS
2681 "whitespace normalization": r
"""
2682 If the whitespace normalization flag is used, then
2683 differences in whitespace are ignored.
2684 >>> print range(30) #doctest: +NORMALIZE_WHITESPACE
2685 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
2686 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,
2693 testfiles
= [arg
for arg
in sys
.argv
[1:] if arg
and arg
[0] != '-']
2695 name
= os
.path
.basename(sys
.argv
[0])
2696 if '__loader__' in globals(): # python -m
2697 name
, _
= os
.path
.splitext(name
)
2698 print("usage: {0} [-v] file ...".format(name
))
2700 for filename
in testfiles
:
2701 if filename
.endswith(".py"):
2702 # It is a module -- insert its dir into sys.path and try to
2703 # import it. If it is part of a package, that possibly
2704 # won't work because of package imports.
2705 dirname
, filename
= os
.path
.split(filename
)
2706 sys
.path
.insert(0, dirname
)
2707 m
= __import__(filename
[:-3])
2709 failures
, _
= testmod(m
)
2711 failures
, _
= testfile(filename
, module_relative
=False)
2717 if __name__
== "__main__":