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 def _indent(s
, indent
=4):
223 Add the given number of space characters to the beginning every
224 non-blank line in `s`, and return the result.
226 # This regexp matches the start of non-blank lines:
227 return re
.sub('(?m)^(?!$)', indent
*' ', s
)
229 def _exception_traceback(exc_info
):
231 Return a string containing a traceback message for the given
232 exc_info tuple (as returned by sys.exc_info()).
234 # Get a traceback message.
236 exc_type
, exc_val
, exc_tb
= exc_info
237 traceback
.print_exception(exc_type
, exc_val
, exc_tb
, file=excout
)
238 return excout
.getvalue()
240 # Override some StringIO methods.
241 class _SpoofOut(StringIO
):
243 result
= StringIO
.getvalue(self
)
244 # If anything at all was written, make sure there's a trailing
245 # newline. There's no way for the expected output to indicate
246 # that a trailing newline is missing.
247 if result
and not result
.endswith("\n"):
249 # Prevent softspace from screwing up the next test case, in
250 # case they used print with a trailing comma in an example.
251 if hasattr(self
, "softspace"):
255 def truncate(self
, size
=None):
256 StringIO
.truncate(self
, size
)
257 if hasattr(self
, "softspace"):
260 # Worst-case linear-time ellipsis matching.
261 def _ellipsis_match(want
, got
):
263 Essentially the only subtle case:
264 >>> _ellipsis_match('aa...aa', 'aaa')
267 if ELLIPSIS_MARKER
not in want
:
270 # Find "the real" strings.
271 ws
= want
.split(ELLIPSIS_MARKER
)
274 # Deal with exact matches possibly needed at one or both ends.
275 startpos
, endpos
= 0, len(got
)
277 if w
: # starts with exact match
278 if got
.startswith(w
):
284 if w
: # ends with exact match
291 if startpos
> endpos
:
292 # Exact end matches required more characters than we have, as in
293 # _ellipsis_match('aa...aa', 'aaa')
296 # For the rest, we only need to find the leftmost non-overlapping
297 # match for each piece. If there's no overall match that way alone,
298 # there's no overall match period.
300 # w may be '' at times, if there are consecutive ellipses, or
301 # due to an ellipsis at the start or end of `want`. That's OK.
302 # Search for an empty string succeeds, and doesn't change startpos.
303 startpos
= got
.find(w
, startpos
, endpos
)
310 def _comment_line(line
):
311 "Return a commented form of the given line"
318 class _OutputRedirectingPdb(pdb
.Pdb
):
320 A specialized version of the python debugger that redirects stdout
321 to a given stream when interacting with the user. Stdout is *not*
322 redirected when traced code is executed.
324 def __init__(self
, out
):
326 self
.__debugger
_used
= False
327 pdb
.Pdb
.__init
__(self
, stdout
=out
)
329 def set_trace(self
, frame
=None):
330 self
.__debugger
_used
= True
332 frame
= sys
._getframe
().f_back
333 pdb
.Pdb
.set_trace(self
, frame
)
335 def set_continue(self
):
336 # Calling set_continue unconditionally would break unit test
337 # coverage reporting, as Bdb.set_continue calls sys.settrace(None).
338 if self
.__debugger
_used
:
339 pdb
.Pdb
.set_continue(self
)
341 def trace_dispatch(self
, *args
):
342 # Redirect stdout to the given stream.
343 save_stdout
= sys
.stdout
344 sys
.stdout
= self
.__out
345 # Call Pdb's trace dispatch method.
347 return pdb
.Pdb
.trace_dispatch(self
, *args
)
349 sys
.stdout
= save_stdout
351 # [XX] Normalize with respect to os.path.pardir?
352 def _module_relative_path(module
, path
):
353 if not inspect
.ismodule(module
):
354 raise TypeError, 'Expected a module: %r' % module
355 if path
.startswith('/'):
356 raise ValueError, 'Module-relative files may not have absolute paths'
358 # Find the base directory for the path.
359 if hasattr(module
, '__file__'):
360 # A normal module/package
361 basedir
= os
.path
.split(module
.__file
__)[0]
362 elif module
.__name
__ == '__main__':
363 # An interactive session.
364 if len(sys
.argv
)>0 and sys
.argv
[0] != '':
365 basedir
= os
.path
.split(sys
.argv
[0])[0]
369 # A module w/o __file__ (this includes builtins)
370 raise ValueError("Can't resolve paths relative to the module " +
371 module
+ " (it has no __file__)")
373 # Combine the base directory and the path.
374 return os
.path
.join(basedir
, *(path
.split('/')))
376 ######################################################################
377 ## 2. Example & DocTest
378 ######################################################################
379 ## - An "example" is a <source, want> pair, where "source" is a
380 ## fragment of source code, and "want" is the expected output for
381 ## "source." The Example class also includes information about
382 ## where the example was extracted from.
384 ## - A "doctest" is a collection of examples, typically extracted from
385 ## a string (such as an object's docstring). The DocTest class also
386 ## includes information about where the string was extracted from.
390 A single doctest example, consisting of source code and expected
391 output. `Example` defines the following attributes:
393 - source: A single Python statement, always ending with a newline.
394 The constructor adds a newline if needed.
396 - want: The expected output from running the source code (either
397 from stdout, or a traceback in case of exception). `want` ends
398 with a newline unless it's empty, in which case it's an empty
399 string. The constructor adds a newline if needed.
401 - exc_msg: The exception message generated by the example, if
402 the example is expected to generate an exception; or `None` if
403 it is not expected to generate an exception. This exception
404 message is compared against the return value of
405 `traceback.format_exception_only()`. `exc_msg` ends with a
406 newline unless it's `None`. The constructor adds a newline
409 - lineno: The line number within the DocTest string containing
410 this Example where the Example begins. This line number is
411 zero-based, with respect to the beginning of the DocTest.
413 - indent: The example's indentation in the DocTest string.
414 I.e., the number of space characters that preceed the
415 example's first prompt.
417 - options: A dictionary mapping from option flags to True or
418 False, which is used to override default options for this
419 example. Any option flags not contained in this dictionary
420 are left at their default value (as specified by the
421 DocTestRunner's optionflags). By default, no options are set.
423 def __init__(self
, source
, want
, exc_msg
=None, lineno
=0, indent
=0,
426 if not source
.endswith('\n'):
428 if want
and not want
.endswith('\n'):
430 if exc_msg
is not None and not exc_msg
.endswith('\n'):
437 if options
is None: options
= {}
438 self
.options
= options
439 self
.exc_msg
= exc_msg
443 A collection of doctest examples that should be run in a single
444 namespace. Each `DocTest` defines the following attributes:
446 - examples: the list of examples.
448 - globs: The namespace (aka globals) that the examples should
451 - name: A name identifying the DocTest (typically, the name of
452 the object whose docstring this DocTest was extracted from).
454 - filename: The name of the file that this DocTest was extracted
455 from, or `None` if the filename is unknown.
457 - lineno: The line number within filename where this DocTest
458 begins, or `None` if the line number is unavailable. This
459 line number is zero-based, with respect to the beginning of
462 - docstring: The string that the examples were extracted from,
463 or `None` if the string is unavailable.
465 def __init__(self
, examples
, globs
, name
, filename
, lineno
, docstring
):
467 Create a new DocTest containing the given examples. The
468 DocTest's globals are initialized with a copy of `globs`.
470 assert not isinstance(examples
, basestring
), \
471 "DocTest no longer accepts str; use DocTestParser instead"
472 self
.examples
= examples
473 self
.docstring
= docstring
474 self
.globs
= globs
.copy()
476 self
.filename
= filename
480 if len(self
.examples
) == 0:
481 examples
= 'no examples'
482 elif len(self
.examples
) == 1:
483 examples
= '1 example'
485 examples
= '%d examples' % len(self
.examples
)
486 return ('<DocTest %s from %s:%s (%s)>' %
487 (self
.name
, self
.filename
, self
.lineno
, examples
))
490 # This lets us sort tests by name:
491 def __cmp__(self
, other
):
492 if not isinstance(other
, DocTest
):
494 return cmp((self
.name
, self
.filename
, self
.lineno
, id(self
)),
495 (other
.name
, other
.filename
, other
.lineno
, id(other
)))
497 ######################################################################
499 ######################################################################
503 A class used to parse strings containing doctest examples.
505 # This regular expression is used to find doctest examples in a
506 # string. It defines three groups: `source` is the source code
507 # (including leading indentation and prompts); `indent` is the
508 # indentation of the first (PS1) line of the source code; and
509 # `want` is the expected output (including leading indentation).
510 _EXAMPLE_RE
= re
.compile(r
'''
511 # Source consists of a PS1 line followed by zero or more PS2 lines.
513 (?:^(?P<indent> [ ]*) >>> .*) # PS1 line
514 (?:\n [ ]* \.\.\. .*)*) # PS2 lines
516 # Want consists of any non-blank lines that do not start with PS1.
517 (?P<want> (?:(?![ ]*$) # Not a blank line
518 (?![ ]*>>>) # Not a line starting with PS1
519 .*$\n? # But any other line
521 ''', re
.MULTILINE | re
.VERBOSE
)
523 # A regular expression for handling `want` strings that contain
524 # expected exceptions. It divides `want` into three pieces:
525 # - the traceback header line (`hdr`)
526 # - the traceback stack (`stack`)
527 # - the exception message (`msg`), as generated by
528 # traceback.format_exception_only()
529 # `msg` may have multiple lines. We assume/require that the
530 # exception message is the first non-indented line starting with a word
531 # character following the traceback header line.
532 _EXCEPTION_RE
= re
.compile(r
"""
533 # Grab the traceback header. Different versions of Python have
534 # said different things on the first traceback line.
535 ^(?P<hdr> Traceback\ \(
536 (?: most\ recent\ call\ last
540 \s* $ # toss trailing whitespace on the header.
541 (?P<stack> .*?) # don't blink: absorb stuff until...
542 ^ (?P<msg> \w+ .*) # a line *starts* with alphanum.
543 """, re
.VERBOSE | re
.MULTILINE | re
.DOTALL
)
545 # A callable returning a true value iff its argument is a blank line
546 # or contains a single comment.
547 _IS_BLANK_OR_COMMENT
= re
.compile(r
'^[ ]*(#.*)?$').match
549 def parse(self
, string
, name
='<string>'):
551 Divide the given string into examples and intervening text,
552 and return them as a list of alternating Examples and strings.
553 Line numbers for the Examples are 0-based. The optional
554 argument `name` is a name identifying this string, and is only
555 used for error messages.
557 string
= string
.expandtabs()
558 # If all lines begin with the same indentation, then strip it.
559 min_indent
= self
._min
_indent
(string
)
561 string
= '\n'.join([l
[min_indent
:] for l
in string
.split('\n')])
564 charno
, lineno
= 0, 0
565 # Find all doctest examples in the string:
566 for m
in self
._EXAMPLE
_RE
.finditer(string
):
567 # Add the pre-example text to `output`.
568 output
.append(string
[charno
:m
.start()])
569 # Update lineno (lines before this example)
570 lineno
+= string
.count('\n', charno
, m
.start())
571 # Extract info from the regexp match.
572 (source
, options
, want
, exc_msg
) = \
573 self
._parse
_example
(m
, name
, lineno
)
574 # Create an Example, and add it to the list.
575 if not self
._IS
_BLANK
_OR
_COMMENT
(source
):
576 output
.append( Example(source
, want
, exc_msg
,
578 indent
=min_indent
+len(m
.group('indent')),
580 # Update lineno (lines inside this example)
581 lineno
+= string
.count('\n', m
.start(), m
.end())
584 # Add any remaining post-example text to `output`.
585 output
.append(string
[charno
:])
588 def get_doctest(self
, string
, globs
, name
, filename
, lineno
):
590 Extract all doctest examples from the given string, and
591 collect them into a `DocTest` object.
593 `globs`, `name`, `filename`, and `lineno` are attributes for
594 the new `DocTest` object. See the documentation for `DocTest`
595 for more information.
597 return DocTest(self
.get_examples(string
, name
), globs
,
598 name
, filename
, lineno
, string
)
600 def get_examples(self
, string
, name
='<string>'):
602 Extract all doctest examples from the given string, and return
603 them as a list of `Example` objects. Line numbers are
604 0-based, because it's most common in doctests that nothing
605 interesting appears on the same line as opening triple-quote,
606 and so the first interesting line is called \"line 1\" then.
608 The optional argument `name` is a name identifying this
609 string, and is only used for error messages.
611 return [x
for x
in self
.parse(string
, name
)
612 if isinstance(x
, Example
)]
614 def _parse_example(self
, m
, name
, lineno
):
616 Given a regular expression match from `_EXAMPLE_RE` (`m`),
617 return a pair `(source, want)`, where `source` is the matched
618 example's source code (with prompts and indentation stripped);
619 and `want` is the example's expected output (with indentation
622 `name` is the string's name, and `lineno` is the line number
623 where the example starts; both are used for error messages.
625 # Get the example's indentation level.
626 indent
= len(m
.group('indent'))
628 # Divide source into lines; check that they're properly
629 # indented; and then strip their indentation & prompts.
630 source_lines
= m
.group('source').split('\n')
631 self
._check
_prompt
_blank
(source_lines
, indent
, name
, lineno
)
632 self
._check
_prefix
(source_lines
[1:], ' '*indent
+ '.', name
, lineno
)
633 source
= '\n'.join([sl
[indent
+4:] for sl
in source_lines
])
635 # Divide want into lines; check that it's properly indented; and
636 # then strip the indentation. Spaces before the last newline should
637 # be preserved, so plain rstrip() isn't good enough.
638 want
= m
.group('want')
639 want_lines
= want
.split('\n')
640 if len(want_lines
) > 1 and re
.match(r
' *$', want_lines
[-1]):
641 del want_lines
[-1] # forget final newline & spaces after it
642 self
._check
_prefix
(want_lines
, ' '*indent
, name
,
643 lineno
+ len(source_lines
))
644 want
= '\n'.join([wl
[indent
:] for wl
in want_lines
])
646 # If `want` contains a traceback message, then extract it.
647 m
= self
._EXCEPTION
_RE
.match(want
)
649 exc_msg
= m
.group('msg')
653 # Extract options from the source.
654 options
= self
._find
_options
(source
, name
, lineno
)
656 return source
, options
, want
, exc_msg
658 # This regular expression looks for option directives in the
659 # source code of an example. Option directives are comments
660 # starting with "doctest:". Warning: this may give false
661 # positives for string-literals that contain the string
662 # "#doctest:". Eliminating these false positives would require
663 # actually parsing the string; but we limit them by ignoring any
664 # line containing "#doctest:" that is *followed* by a quote mark.
665 _OPTION_DIRECTIVE_RE
= re
.compile(r
'#\s*doctest:\s*([^\n\'"]*)$',
668 def _find_options(self, source, name, lineno):
670 Return a dictionary containing option overrides extracted from
671 option directives in the given source string.
673 `name` is the string's name, and `lineno` is the line number
674 where the example starts; both are used for error messages.
677 # (note: with the current regexp, this will match at most once:)
678 for m in self._OPTION_DIRECTIVE_RE.finditer(source):
679 option_strings = m.group(1).replace(',', ' ').split()
680 for option in option_strings:
681 if (option[0] not in '+-' or
682 option[1:] not in OPTIONFLAGS_BY_NAME):
683 raise ValueError('line %r of the doctest for %s '
684 'has an invalid option: %r' %
685 (lineno+1, name, option))
686 flag = OPTIONFLAGS_BY_NAME[option[1:]]
687 options[flag] = (option[0] == '+')
688 if options and self._IS_BLANK_OR_COMMENT(source):
689 raise ValueError('line %r of the doctest for %s has an option '
690 'directive on a line with no example: %r' %
691 (lineno, name, source))
694 # This regular expression finds the indentation of every non-blank
696 _INDENT_RE = re.compile('^([ ]*)(?=\S)', re.MULTILINE)
698 def _min_indent(self, s):
699 "Return the minimum indentation of any non
-blank line
in `s`
"
700 indents = [len(indent) for indent in self._INDENT_RE.findall(s)]
706 def _check_prompt_blank(self, lines, indent, name, lineno):
708 Given the lines of a source string (including prompts and
709 leading indentation), check to make sure that every prompt is
710 followed by a space character. If any line is not followed by
711 a space character, then raise ValueError.
713 for i, line in enumerate(lines):
714 if len(line) >= indent+4 and line[indent+3] != ' ':
715 raise ValueError('line %r of the docstring for %s '
716 'lacks blank after %s: %r' %
718 line[indent:indent+3], line))
720 def _check_prefix(self, lines, prefix, name, lineno):
722 Check that every line in the given list starts with the given
723 prefix; if any line does not, then raise a ValueError.
725 for i, line in enumerate(lines):
726 if line and not line.startswith(prefix):
727 raise ValueError('line %r of the docstring for %s has '
728 'inconsistent leading whitespace: %r' %
729 (lineno+i+1, name, line))
732 ######################################################################
734 ######################################################################
738 A class used to extract the DocTests that are relevant to a given
739 object, from its docstring and the docstrings of its contained
740 objects. Doctests can currently be extracted from the following
741 object types: modules, functions, classes, methods, staticmethods,
742 classmethods, and properties.
745 def __init__(self, verbose=False, parser=DocTestParser(),
746 recurse=True, exclude_empty=True):
748 Create a new doctest finder.
750 The optional argument `parser` specifies a class or
751 function that should be used to create new DocTest objects (or
752 objects that implement the same interface as DocTest). The
753 signature for this factory function should match the signature
754 of the DocTest constructor.
756 If the optional argument `recurse` is false, then `find` will
757 only examine the given object, and not any contained objects.
759 If the optional argument `exclude_empty` is false, then `find`
760 will include tests for objects with empty docstrings.
762 self._parser = parser
763 self._verbose = verbose
764 self._recurse = recurse
765 self._exclude_empty = exclude_empty
767 def find(self, obj, name=None, module=None, globs=None, extraglobs=None):
769 Return a list of the DocTests that are defined by the given
770 object's docstring, or by any of its contained objects'
773 The optional parameter `module` is the module that contains
774 the given object. If the module is not specified or is None, then
775 the test finder will attempt to automatically determine the
776 correct module. The object's module is used:
778 - As a default namespace, if `globs` is not specified.
779 - To prevent the DocTestFinder from extracting DocTests
780 from objects that are imported from other modules.
781 - To find the name of the file containing the object.
782 - To help find the line number of the object within its
785 Contained objects whose module does not match `module` are ignored.
787 If `module` is False, no attempt to find the module will be made.
788 This is obscure, of use mostly in tests: if `module` is False, or
789 is None but cannot be found automatically, then all objects are
790 considered to belong to the (non-existent) module, so all contained
791 objects will (recursively) be searched for doctests.
793 The globals for each DocTest is formed by combining `globs`
794 and `extraglobs` (bindings in `extraglobs` override bindings
795 in `globs`). A new copy of the globals dictionary is created
796 for each DocTest. If `globs` is not specified, then it
797 defaults to the module's `__dict__`, if specified, or {}
798 otherwise. If `extraglobs` is not specified, then it defaults
802 # If name was not specified, then extract it from the object.
804 name = getattr(obj, '__name__', None)
806 raise ValueError("DocTestFinder
.find
: name must be given
"
807 "when obj
.__name
__ doesn
't exist: %r" %
810 # Find the module that contains the given object (if obj is
811 # a module, then module=obj.). Note: this may fail, in which
812 # case module will be None.
816 module = inspect.getmodule(obj)
818 # Read the module's source code
. This
is used by
819 # DocTestFinder._find_lineno to find the line number for a
820 # given object's docstring.
822 file = inspect
.getsourcefile(obj
) or inspect
.getfile(obj
)
823 if module
is not None:
824 # Supply the module globals in case the module was
825 # originally loaded via a PEP 302 loader and
826 # file is not a valid filesystem path
827 source_lines
= linecache
.getlines(file, module
.__dict
__)
829 # No access to a loader, so assume it's a normal
831 source_lines
= linecache
.getlines(file)
837 # Initialize globals, and merge in extraglobs.
842 globs
= module
.__dict
__.copy()
845 if extraglobs
is not None:
846 globs
.update(extraglobs
)
848 # Recursively expore `obj`, extracting DocTests.
850 self
._find
(tests
, obj
, name
, module
, source_lines
, globs
, {})
851 # Sort the tests by alpha order of names, for consistency in
852 # verbose-mode output. This was a feature of doctest in Pythons
853 # <= 2.3 that got lost by accident in 2.4. It was repaired in
858 def _from_module(self
, module
, object):
860 Return true if the given object is defined in the given
865 elif inspect
.getmodule(object) is not None:
866 return module
is inspect
.getmodule(object)
867 elif inspect
.isfunction(object):
868 return module
.__dict
__ is object.func_globals
869 elif inspect
.isclass(object):
870 return module
.__name
__ == object.__module
__
871 elif hasattr(object, '__module__'):
872 return module
.__name
__ == object.__module
__
873 elif isinstance(object, property):
874 return True # [XX] no way not be sure.
876 raise ValueError("object must be a class or function")
878 def _find(self
, tests
, obj
, name
, module
, source_lines
, globs
, seen
):
880 Find tests for the given object and any contained objects, and
884 print 'Finding tests in %s' % name
886 # If we've already processed this object, then ignore it.
891 # Find a test for this object, and add it to the list of tests.
892 test
= self
._get
_test
(obj
, name
, module
, globs
, source_lines
)
896 # Look for tests in a module's contained objects.
897 if inspect
.ismodule(obj
) and self
._recurse
:
898 for valname
, val
in obj
.__dict
__.items():
899 valname
= '%s.%s' % (name
, valname
)
900 # Recurse to functions & classes.
901 if ((inspect
.isfunction(val
) or inspect
.isclass(val
)) and
902 self
._from
_module
(module
, val
)):
903 self
._find
(tests
, val
, valname
, module
, source_lines
,
906 # Look for tests in a module's __test__ dictionary.
907 if inspect
.ismodule(obj
) and self
._recurse
:
908 for valname
, val
in getattr(obj
, '__test__', {}).items():
909 if not isinstance(valname
, basestring
):
910 raise ValueError("DocTestFinder.find: __test__ keys "
911 "must be strings: %r" %
913 if not (inspect
.isfunction(val
) or inspect
.isclass(val
) or
914 inspect
.ismethod(val
) or inspect
.ismodule(val
) or
915 isinstance(val
, basestring
)):
916 raise ValueError("DocTestFinder.find: __test__ values "
917 "must be strings, functions, methods, "
918 "classes, or modules: %r" %
920 valname
= '%s.__test__.%s' % (name
, valname
)
921 self
._find
(tests
, val
, valname
, module
, source_lines
,
924 # Look for tests in a class's contained objects.
925 if inspect
.isclass(obj
) and self
._recurse
:
926 for valname
, val
in obj
.__dict
__.items():
927 # Special handling for staticmethod/classmethod.
928 if isinstance(val
, staticmethod):
929 val
= getattr(obj
, valname
)
930 if isinstance(val
, classmethod):
931 val
= getattr(obj
, valname
).im_func
933 # Recurse to methods, properties, and nested classes.
934 if ((inspect
.isfunction(val
) or inspect
.isclass(val
) or
935 isinstance(val
, property)) and
936 self
._from
_module
(module
, val
)):
937 valname
= '%s.%s' % (name
, valname
)
938 self
._find
(tests
, val
, valname
, module
, source_lines
,
941 def _get_test(self
, obj
, name
, module
, globs
, source_lines
):
943 Return a DocTest for the given object, if it defines a docstring;
944 otherwise, return None.
946 # Extract the object's docstring. If it doesn't have one,
947 # then return None (no test for this object).
948 if isinstance(obj
, basestring
):
952 if obj
.__doc
__ is None:
955 docstring
= obj
.__doc
__
956 if not isinstance(docstring
, basestring
):
957 docstring
= str(docstring
)
958 except (TypeError, AttributeError):
961 # Find the docstring's location in the file.
962 lineno
= self
._find
_lineno
(obj
, source_lines
)
964 # Don't bother if the docstring is empty.
965 if self
._exclude
_empty
and not docstring
:
968 # Return a DocTest for this object.
972 filename
= getattr(module
, '__file__', module
.__name
__)
973 if filename
[-4:] in (".pyc", ".pyo"):
974 filename
= filename
[:-1]
975 return self
._parser
.get_doctest(docstring
, globs
, name
,
978 def _find_lineno(self
, obj
, source_lines
):
980 Return a line number of the given object's docstring. Note:
981 this method assumes that the object has a docstring.
985 # Find the line number for modules.
986 if inspect
.ismodule(obj
):
989 # Find the line number for classes.
990 # Note: this could be fooled if a class is defined multiple
991 # times in a single file.
992 if inspect
.isclass(obj
):
993 if source_lines
is None:
995 pat
= re
.compile(r
'^\s*class\s*%s\b' %
996 getattr(obj
, '__name__', '-'))
997 for i
, line
in enumerate(source_lines
):
1002 # Find the line number for functions & methods.
1003 if inspect
.ismethod(obj
): obj
= obj
.im_func
1004 if inspect
.isfunction(obj
): obj
= obj
.func_code
1005 if inspect
.istraceback(obj
): obj
= obj
.tb_frame
1006 if inspect
.isframe(obj
): obj
= obj
.f_code
1007 if inspect
.iscode(obj
):
1008 lineno
= getattr(obj
, 'co_firstlineno', None)-1
1010 # Find the line number where the docstring starts. Assume
1011 # that it's the first line that begins with a quote mark.
1012 # Note: this could be fooled by a multiline function
1013 # signature, where a continuation line begins with a quote
1015 if lineno
is not None:
1016 if source_lines
is None:
1018 pat
= re
.compile('(^|.*:)\s*\w*("|\')')
1019 for lineno
in range(lineno
, len(source_lines
)):
1020 if pat
.match(source_lines
[lineno
]):
1023 # We couldn't find the line number.
1026 ######################################################################
1027 ## 5. DocTest Runner
1028 ######################################################################
1030 class DocTestRunner
:
1032 A class used to run DocTest test cases, and accumulate statistics.
1033 The `run` method is used to process a single DocTest case. It
1034 returns a tuple `(f, t)`, where `t` is the number of test cases
1035 tried, and `f` is the number of test cases that failed.
1037 >>> tests = DocTestFinder().find(_TestClass)
1038 >>> runner = DocTestRunner(verbose=False)
1039 >>> tests.sort(key = lambda test: test.name)
1040 >>> for test in tests:
1041 ... print test.name, '->', runner.run(test)
1042 _TestClass -> TestResults(failed=0, attempted=2)
1043 _TestClass.__init__ -> TestResults(failed=0, attempted=2)
1044 _TestClass.get -> TestResults(failed=0, attempted=2)
1045 _TestClass.square -> TestResults(failed=0, attempted=1)
1047 The `summarize` method prints a summary of all the test cases that
1048 have been run by the runner, and returns an aggregated `(f, t)`
1051 >>> runner.summarize(verbose=1)
1052 4 items passed all tests:
1053 2 tests in _TestClass
1054 2 tests in _TestClass.__init__
1055 2 tests in _TestClass.get
1056 1 tests in _TestClass.square
1058 7 passed and 0 failed.
1060 TestResults(failed=0, attempted=7)
1062 The aggregated number of tried examples and failed examples is
1063 also available via the `tries` and `failures` attributes:
1070 The comparison between expected outputs and actual outputs is done
1071 by an `OutputChecker`. This comparison may be customized with a
1072 number of option flags; see the documentation for `testmod` for
1073 more information. If the option flags are insufficient, then the
1074 comparison may also be customized by passing a subclass of
1075 `OutputChecker` to the constructor.
1077 The test runner's display output can be controlled in two ways.
1078 First, an output function (`out) can be passed to
1079 `TestRunner.run`; this function will be called with strings that
1080 should be displayed. It defaults to `sys.stdout.write`. If
1081 capturing the output is not sufficient, then the display output
1082 can be also customized by subclassing DocTestRunner, and
1083 overriding the methods `report_start`, `report_success`,
1084 `report_unexpected_exception`, and `report_failure`.
1086 # This divider string is used to separate failure messages, and to
1087 # separate sections of the summary.
1090 def __init__(self
, checker
=None, verbose
=None, optionflags
=0):
1092 Create a new test runner.
1094 Optional keyword arg `checker` is the `OutputChecker` that
1095 should be used to compare the expected outputs and actual
1096 outputs of doctest examples.
1098 Optional keyword arg 'verbose' prints lots of stuff if true,
1099 only failures if false; by default, it's true iff '-v' is in
1102 Optional argument `optionflags` can be used to control how the
1103 test runner compares expected output to actual output, and how
1104 it displays failures. See the documentation for `testmod` for
1107 self
._checker
= checker
or OutputChecker()
1109 verbose
= '-v' in sys
.argv
1110 self
._verbose
= verbose
1111 self
.optionflags
= optionflags
1112 self
.original_optionflags
= optionflags
1114 # Keep track of the examples we've run.
1119 # Create a fake output target for capturing doctest output.
1120 self
._fakeout
= _SpoofOut()
1122 #/////////////////////////////////////////////////////////////////
1124 #/////////////////////////////////////////////////////////////////
1126 def report_start(self
, out
, test
, example
):
1128 Report that the test runner is about to process the given
1129 example. (Only displays a message if verbose=True)
1133 out('Trying:\n' + _indent(example
.source
) +
1134 'Expecting:\n' + _indent(example
.want
))
1136 out('Trying:\n' + _indent(example
.source
) +
1137 'Expecting nothing\n')
1139 def report_success(self
, out
, test
, example
, got
):
1141 Report that the given example ran successfully. (Only
1142 displays a message if verbose=True)
1147 def report_failure(self
, out
, test
, example
, got
):
1149 Report that the given example failed.
1151 out(self
._failure
_header
(test
, example
) +
1152 self
._checker
.output_difference(example
, got
, self
.optionflags
))
1154 def report_unexpected_exception(self
, out
, test
, example
, exc_info
):
1156 Report that the given example raised an unexpected exception.
1158 out(self
._failure
_header
(test
, example
) +
1159 'Exception raised:\n' + _indent(_exception_traceback(exc_info
)))
1161 def _failure_header(self
, test
, example
):
1162 out
= [self
.DIVIDER
]
1164 if test
.lineno
is not None and example
.lineno
is not None:
1165 lineno
= test
.lineno
+ example
.lineno
+ 1
1168 out
.append('File "%s", line %s, in %s' %
1169 (test
.filename
, lineno
, test
.name
))
1171 out
.append('Line %s, in %s' % (example
.lineno
+1, test
.name
))
1172 out
.append('Failed example:')
1173 source
= example
.source
1174 out
.append(_indent(source
))
1175 return '\n'.join(out
)
1177 #/////////////////////////////////////////////////////////////////
1179 #/////////////////////////////////////////////////////////////////
1181 def __run(self
, test
, compileflags
, out
):
1183 Run the examples in `test`. Write the outcome of each example
1184 with one of the `DocTestRunner.report_*` methods, using the
1185 writer function `out`. `compileflags` is the set of compiler
1186 flags that should be used to execute examples. Return a tuple
1187 `(f, t)`, where `t` is the number of examples tried, and `f`
1188 is the number of examples that failed. The examples are run
1189 in the namespace `test.globs`.
1191 # Keep track of the number of failures and tries.
1192 failures
= tries
= 0
1194 # Save the option flags (since option directives can be used
1196 original_optionflags
= self
.optionflags
1198 SUCCESS
, FAILURE
, BOOM
= range(3) # `outcome` state
1200 check
= self
._checker
.check_output
1202 # Process each example.
1203 for examplenum
, example
in enumerate(test
.examples
):
1205 # If REPORT_ONLY_FIRST_FAILURE is set, then supress
1206 # reporting after the first failure.
1207 quiet
= (self
.optionflags
& REPORT_ONLY_FIRST_FAILURE
and
1210 # Merge in the example's options.
1211 self
.optionflags
= original_optionflags
1213 for (optionflag
, val
) in example
.options
.items():
1215 self
.optionflags |
= optionflag
1217 self
.optionflags
&= ~optionflag
1219 # If 'SKIP' is set, then skip this example.
1220 if self
.optionflags
& SKIP
:
1223 # Record that we started this example.
1226 self
.report_start(out
, test
, example
)
1228 # Use a special filename for compile(), so we can retrieve
1229 # the source code during interactive debugging (see
1230 # __patched_linecache_getlines).
1231 filename
= '<doctest %s[%d]>' % (test
.name
, examplenum
)
1233 # Run the example in the given context (globs), and record
1234 # any exception that gets raised. (But don't intercept
1235 # keyboard interrupts.)
1237 # Don't blink! This is where the user's code gets run.
1238 exec compile(example
.source
, filename
, "single",
1239 compileflags
, 1) in test
.globs
1240 self
.debugger
.set_continue() # ==== Example Finished ====
1242 except KeyboardInterrupt:
1245 exception
= sys
.exc_info()
1246 self
.debugger
.set_continue() # ==== Example Finished ====
1248 got
= self
._fakeout
.getvalue() # the actual output
1249 self
._fakeout
.truncate(0)
1250 outcome
= FAILURE
# guilty until proved innocent or insane
1252 # If the example executed without raising any exceptions,
1253 # verify its output.
1254 if exception
is None:
1255 if check(example
.want
, got
, self
.optionflags
):
1258 # The example raised an exception: check if it was expected.
1260 exc_info
= sys
.exc_info()
1261 exc_msg
= traceback
.format_exception_only(*exc_info
[:2])[-1]
1263 got
+= _exception_traceback(exc_info
)
1265 # If `example.exc_msg` is None, then we weren't expecting
1267 if example
.exc_msg
is None:
1270 # We expected an exception: see whether it matches.
1271 elif check(example
.exc_msg
, exc_msg
, self
.optionflags
):
1274 # Another chance if they didn't care about the detail.
1275 elif self
.optionflags
& IGNORE_EXCEPTION_DETAIL
:
1276 m1
= re
.match(r
'[^:]*:', example
.exc_msg
)
1277 m2
= re
.match(r
'[^:]*:', exc_msg
)
1278 if m1
and m2
and check(m1
.group(0), m2
.group(0),
1282 # Report the outcome.
1283 if outcome
is SUCCESS
:
1285 self
.report_success(out
, test
, example
, got
)
1286 elif outcome
is FAILURE
:
1288 self
.report_failure(out
, test
, example
, got
)
1290 elif outcome
is BOOM
:
1292 self
.report_unexpected_exception(out
, test
, example
,
1296 assert False, ("unknown outcome", outcome
)
1298 # Restore the option flags (in case they were modified)
1299 self
.optionflags
= original_optionflags
1301 # Record and return the number of failures and tries.
1302 self
.__record
_outcome
(test
, failures
, tries
)
1303 return TestResults(failures
, tries
)
1305 def __record_outcome(self
, test
, f
, t
):
1307 Record the fact that the given DocTest (`test`) generated `f`
1308 failures out of `t` tried examples.
1310 f2
, t2
= self
._name
2ft
.get(test
.name
, (0,0))
1311 self
._name
2ft
[test
.name
] = (f
+f2
, t
+t2
)
1315 __LINECACHE_FILENAME_RE
= re
.compile(r
'<doctest '
1316 r
'(?P<name>[\w\.]+)'
1317 r
'\[(?P<examplenum>\d+)\]>$')
1318 def __patched_linecache_getlines(self
, filename
, module_globals
=None):
1319 m
= self
.__LINECACHE
_FILENAME
_RE
.match(filename
)
1320 if m
and m
.group('name') == self
.test
.name
:
1321 example
= self
.test
.examples
[int(m
.group('examplenum'))]
1322 return example
.source
.splitlines(True)
1324 return self
.save_linecache_getlines(filename
, module_globals
)
1326 def run(self
, test
, compileflags
=None, out
=None, clear_globs
=True):
1328 Run the examples in `test`, and display the results using the
1329 writer function `out`.
1331 The examples are run in the namespace `test.globs`. If
1332 `clear_globs` is true (the default), then this namespace will
1333 be cleared after the test runs, to help with garbage
1334 collection. If you would like to examine the namespace after
1335 the test completes, then use `clear_globs=False`.
1337 `compileflags` gives the set of flags that should be used by
1338 the Python compiler when running the examples. If not
1339 specified, then it will default to the set of future-import
1340 flags that apply to `globs`.
1342 The output of each example is checked using
1343 `DocTestRunner.check_output`, and the results are formatted by
1344 the `DocTestRunner.report_*` methods.
1348 if compileflags
is None:
1349 compileflags
= _extract_future_flags(test
.globs
)
1351 save_stdout
= sys
.stdout
1353 out
= save_stdout
.write
1354 sys
.stdout
= self
._fakeout
1356 # Patch pdb.set_trace to restore sys.stdout during interactive
1357 # debugging (so it's not still redirected to self._fakeout).
1358 # Note that the interactive output will go to *our*
1359 # save_stdout, even if that's not the real sys.stdout; this
1360 # allows us to write test cases for the set_trace behavior.
1361 save_set_trace
= pdb
.set_trace
1362 self
.debugger
= _OutputRedirectingPdb(save_stdout
)
1363 self
.debugger
.reset()
1364 pdb
.set_trace
= self
.debugger
.set_trace
1366 # Patch linecache.getlines, so we can see the example's source
1367 # when we're inside the debugger.
1368 self
.save_linecache_getlines
= linecache
.getlines
1369 linecache
.getlines
= self
.__patched
_linecache
_getlines
1372 return self
.__run
(test
, compileflags
, out
)
1374 sys
.stdout
= save_stdout
1375 pdb
.set_trace
= save_set_trace
1376 linecache
.getlines
= self
.save_linecache_getlines
1380 #/////////////////////////////////////////////////////////////////
1382 #/////////////////////////////////////////////////////////////////
1383 def summarize(self
, verbose
=None):
1385 Print a summary of all the test cases that have been run by
1386 this DocTestRunner, and return a tuple `(f, t)`, where `f` is
1387 the total number of failed examples, and `t` is the total
1388 number of tried examples.
1390 The optional `verbose` argument controls how detailed the
1391 summary is. If the verbosity is not specified, then the
1392 DocTestRunner's verbosity is used.
1395 verbose
= self
._verbose
1400 for x
in self
._name
2ft
.items():
1406 notests
.append(name
)
1408 passed
.append( (name
, t
) )
1413 print len(notests
), "items had no tests:"
1415 for thing
in notests
:
1418 print len(passed
), "items passed all tests:"
1420 for thing
, count
in passed
:
1421 print " %3d tests in %s" % (count
, thing
)
1424 print len(failed
), "items had failures:"
1426 for thing
, (f
, t
) in failed
:
1427 print " %3d of %3d in %s" % (f
, t
, thing
)
1429 print totalt
, "tests in", len(self
._name
2ft
), "items."
1430 print totalt
- totalf
, "passed and", totalf
, "failed."
1432 print "***Test Failed***", totalf
, "failures."
1434 print "Test passed."
1435 return TestResults(totalf
, totalt
)
1437 #/////////////////////////////////////////////////////////////////
1438 # Backward compatibility cruft to maintain doctest.master.
1439 #/////////////////////////////////////////////////////////////////
1440 def merge(self
, other
):
1442 for name
, (f
, t
) in other
._name
2ft
.items():
1444 # Don't print here by default, since doing
1445 # so breaks some of the buildbots
1446 #print "*** DocTestRunner.merge: '" + name + "' in both" \
1447 # " testers; summing outcomes."
1453 class OutputChecker
:
1455 A class used to check the whether the actual output from a doctest
1456 example matches the expected output. `OutputChecker` defines two
1457 methods: `check_output`, which compares a given pair of outputs,
1458 and returns true if they match; and `output_difference`, which
1459 returns a string describing the differences between two outputs.
1461 def check_output(self
, want
, got
, optionflags
):
1463 Return True iff the actual output from an example (`got`)
1464 matches the expected output (`want`). These strings are
1465 always considered to match if they are identical; but
1466 depending on what option flags the test runner is using,
1467 several non-exact match types are also possible. See the
1468 documentation for `TestRunner` for more information about
1471 # Handle the common case first, for efficiency:
1472 # if they're string-identical, always return true.
1476 # The values True and False replaced 1 and 0 as the return
1477 # value for boolean comparisons in Python 2.3.
1478 if not (optionflags
& DONT_ACCEPT_TRUE_FOR_1
):
1479 if (got
,want
) == ("True\n", "1\n"):
1481 if (got
,want
) == ("False\n", "0\n"):
1484 # <BLANKLINE> can be used as a special sequence to signify a
1485 # blank line, unless the DONT_ACCEPT_BLANKLINE flag is used.
1486 if not (optionflags
& DONT_ACCEPT_BLANKLINE
):
1487 # Replace <BLANKLINE> in want with a blank line.
1488 want
= re
.sub('(?m)^%s\s*?$' % re
.escape(BLANKLINE_MARKER
),
1490 # If a line in got contains only spaces, then remove the
1492 got
= re
.sub('(?m)^\s*?$', '', got
)
1496 # This flag causes doctest to ignore any differences in the
1497 # contents of whitespace strings. Note that this can be used
1498 # in conjunction with the ELLIPSIS flag.
1499 if optionflags
& NORMALIZE_WHITESPACE
:
1500 got
= ' '.join(got
.split())
1501 want
= ' '.join(want
.split())
1505 # The ELLIPSIS flag says to let the sequence "..." in `want`
1506 # match any substring in `got`.
1507 if optionflags
& ELLIPSIS
:
1508 if _ellipsis_match(want
, got
):
1511 # We didn't find any match; return false.
1514 # Should we do a fancy diff?
1515 def _do_a_fancy_diff(self
, want
, got
, optionflags
):
1516 # Not unless they asked for a fancy diff.
1517 if not optionflags
& (REPORT_UDIFF |
1522 # If expected output uses ellipsis, a meaningful fancy diff is
1523 # too hard ... or maybe not. In two real-life failures Tim saw,
1524 # a diff was a major help anyway, so this is commented out.
1525 # [todo] _ellipsis_match() knows which pieces do and don't match,
1526 # and could be the basis for a kick-ass diff in this case.
1527 ##if optionflags & ELLIPSIS and ELLIPSIS_MARKER in want:
1530 # ndiff does intraline difference marking, so can be useful even
1531 # for 1-line differences.
1532 if optionflags
& REPORT_NDIFF
:
1535 # The other diff types need at least a few lines to be helpful.
1536 return want
.count('\n') > 2 and got
.count('\n') > 2
1538 def output_difference(self
, example
, got
, optionflags
):
1540 Return a string describing the differences between the
1541 expected output for a given example (`example`) and the actual
1542 output (`got`). `optionflags` is the set of option flags used
1543 to compare `want` and `got`.
1546 # If <BLANKLINE>s are being used, then replace blank lines
1547 # with <BLANKLINE> in the actual output string.
1548 if not (optionflags
& DONT_ACCEPT_BLANKLINE
):
1549 got
= re
.sub('(?m)^[ ]*(?=\n)', BLANKLINE_MARKER
, got
)
1551 # Check if we should use diff.
1552 if self
._do
_a
_fancy
_diff
(want
, got
, optionflags
):
1553 # Split want & got into lines.
1554 want_lines
= want
.splitlines(True) # True == keep line ends
1555 got_lines
= got
.splitlines(True)
1556 # Use difflib to find their differences.
1557 if optionflags
& REPORT_UDIFF
:
1558 diff
= difflib
.unified_diff(want_lines
, got_lines
, n
=2)
1559 diff
= list(diff
)[2:] # strip the diff header
1560 kind
= 'unified diff with -expected +actual'
1561 elif optionflags
& REPORT_CDIFF
:
1562 diff
= difflib
.context_diff(want_lines
, got_lines
, n
=2)
1563 diff
= list(diff
)[2:] # strip the diff header
1564 kind
= 'context diff with expected followed by actual'
1565 elif optionflags
& REPORT_NDIFF
:
1566 engine
= difflib
.Differ(charjunk
=difflib
.IS_CHARACTER_JUNK
)
1567 diff
= list(engine
.compare(want_lines
, got_lines
))
1568 kind
= 'ndiff with -expected +actual'
1570 assert 0, 'Bad diff option'
1571 # Remove trailing whitespace on diff output.
1572 diff
= [line
.rstrip() + '\n' for line
in diff
]
1573 return 'Differences (%s):\n' % kind
+ _indent(''.join(diff
))
1575 # If we're not using diff, then simply list the expected
1576 # output followed by the actual output.
1578 return 'Expected:\n%sGot:\n%s' % (_indent(want
), _indent(got
))
1580 return 'Expected:\n%sGot nothing\n' % _indent(want
)
1582 return 'Expected nothing\nGot:\n%s' % _indent(got
)
1584 return 'Expected nothing\nGot nothing\n'
1586 class DocTestFailure(Exception):
1587 """A DocTest example has failed in debugging mode.
1589 The exception instance has variables:
1591 - test: the DocTest object being run
1593 - example: the Example object that failed
1595 - got: the actual output
1597 def __init__(self
, test
, example
, got
):
1599 self
.example
= example
1603 return str(self
.test
)
1605 class UnexpectedException(Exception):
1606 """A DocTest example has encountered an unexpected exception
1608 The exception instance has variables:
1610 - test: the DocTest object being run
1612 - example: the Example object that failed
1614 - exc_info: the exception info
1616 def __init__(self
, test
, example
, exc_info
):
1618 self
.example
= example
1619 self
.exc_info
= exc_info
1622 return str(self
.test
)
1624 class DebugRunner(DocTestRunner
):
1625 r
"""Run doc tests but raise an exception as soon as there is a failure.
1627 If an unexpected exception occurs, an UnexpectedException is raised.
1628 It contains the test, the example, and the original exception:
1630 >>> runner = DebugRunner(verbose=False)
1631 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
1632 ... {}, 'foo', 'foo.py', 0)
1634 ... runner.run(test)
1635 ... except UnexpectedException, failure:
1638 >>> failure.test is test
1641 >>> failure.example.want
1644 >>> exc_info = failure.exc_info
1645 >>> raise exc_info[0], exc_info[1], exc_info[2]
1646 Traceback (most recent call last):
1650 We wrap the original exception to give the calling application
1651 access to the test and example information.
1653 If the output doesn't match, then a DocTestFailure is raised:
1655 >>> test = DocTestParser().get_doctest('''
1659 ... ''', {}, 'foo', 'foo.py', 0)
1662 ... runner.run(test)
1663 ... except DocTestFailure, failure:
1666 DocTestFailure objects provide access to the test:
1668 >>> failure.test is test
1671 As well as to the example:
1673 >>> failure.example.want
1676 and the actual output:
1681 If a failure or error occurs, the globals are left intact:
1683 >>> del test.globs['__builtins__']
1687 >>> test = DocTestParser().get_doctest('''
1689 ... >>> raise KeyError
1690 ... ''', {}, 'foo', 'foo.py', 0)
1692 >>> runner.run(test)
1693 Traceback (most recent call last):
1695 UnexpectedException: <DocTest foo from foo.py:0 (2 examples)>
1697 >>> del test.globs['__builtins__']
1701 But the globals are cleared if there is no error:
1703 >>> test = DocTestParser().get_doctest('''
1705 ... ''', {}, 'foo', 'foo.py', 0)
1707 >>> runner.run(test)
1708 TestResults(failed=0, attempted=1)
1715 def run(self
, test
, compileflags
=None, out
=None, clear_globs
=True):
1716 r
= DocTestRunner
.run(self
, test
, compileflags
, out
, False)
1721 def report_unexpected_exception(self
, out
, test
, example
, exc_info
):
1722 raise UnexpectedException(test
, example
, exc_info
)
1724 def report_failure(self
, out
, test
, example
, got
):
1725 raise DocTestFailure(test
, example
, got
)
1727 ######################################################################
1728 ## 6. Test Functions
1729 ######################################################################
1730 # These should be backwards compatible.
1732 # For backward compatibility, a global instance of a DocTestRunner
1733 # class, updated by testmod.
1736 def testmod(m
=None, name
=None, globs
=None, verbose
=None,
1737 report
=True, optionflags
=0, extraglobs
=None,
1738 raise_on_error
=False, exclude_empty
=False):
1739 """m=None, name=None, globs=None, verbose=None, report=True,
1740 optionflags=0, extraglobs=None, raise_on_error=False,
1743 Test examples in docstrings in functions and classes reachable
1744 from module m (or the current module if m is not supplied), starting
1747 Also test examples reachable from dict m.__test__ if it exists and is
1748 not None. m.__test__ maps names to functions, classes and strings;
1749 function and class docstrings are tested even if the name is private;
1750 strings are tested directly, as if they were docstrings.
1752 Return (#failures, #tests).
1754 See doctest.__doc__ for an overview.
1756 Optional keyword arg "name" gives the name of the module; by default
1759 Optional keyword arg "globs" gives a dict to be used as the globals
1760 when executing examples; by default, use m.__dict__. A copy of this
1761 dict is actually used for each docstring, so that each docstring's
1762 examples start with a clean slate.
1764 Optional keyword arg "extraglobs" gives a dictionary that should be
1765 merged into the globals that are used to execute examples. By
1766 default, no extra globals are used. This is new in 2.4.
1768 Optional keyword arg "verbose" prints lots of stuff if true, prints
1769 only failures if false; by default, it's true iff "-v" is in sys.argv.
1771 Optional keyword arg "report" prints a summary at the end when true,
1772 else prints nothing at the end. In verbose mode, the summary is
1773 detailed, else very brief (in fact, empty if all tests passed).
1775 Optional keyword arg "optionflags" or's together module constants,
1776 and defaults to 0. This is new in 2.3. Possible values (see the
1779 DONT_ACCEPT_TRUE_FOR_1
1780 DONT_ACCEPT_BLANKLINE
1781 NORMALIZE_WHITESPACE
1784 IGNORE_EXCEPTION_DETAIL
1788 REPORT_ONLY_FIRST_FAILURE
1790 Optional keyword arg "raise_on_error" raises an exception on the
1791 first unexpected exception or failure. This allows failures to be
1792 post-mortem debugged.
1794 Advanced tomfoolery: testmod runs methods of a local instance of
1795 class doctest.Tester, then merges the results into (or creates)
1796 global Tester instance doctest.master. Methods of doctest.master
1797 can be called directly too, if you want to do something unusual.
1798 Passing report=0 to testmod is especially useful then, to delay
1799 displaying a summary. Invoke doctest.master.summarize(verbose)
1800 when you're done fiddling.
1804 # If no module was given, then use __main__.
1806 # DWA - m will still be None if this wasn't invoked from the command
1807 # line, in which case the following TypeError is about as good an error
1808 # as we should expect
1809 m
= sys
.modules
.get('__main__')
1811 # Check that we were actually given a module.
1812 if not inspect
.ismodule(m
):
1813 raise TypeError("testmod: module required; %r" % (m
,))
1815 # If no name was given, then use the module's name.
1819 # Find, parse, and run all tests in the given module.
1820 finder
= DocTestFinder(exclude_empty
=exclude_empty
)
1823 runner
= DebugRunner(verbose
=verbose
, optionflags
=optionflags
)
1825 runner
= DocTestRunner(verbose
=verbose
, optionflags
=optionflags
)
1827 for test
in finder
.find(m
, name
, globs
=globs
, extraglobs
=extraglobs
):
1836 master
.merge(runner
)
1838 return TestResults(runner
.failures
, runner
.tries
)
1840 def testfile(filename
, module_relative
=True, name
=None, package
=None,
1841 globs
=None, verbose
=None, report
=True, optionflags
=0,
1842 extraglobs
=None, raise_on_error
=False, parser
=DocTestParser(),
1845 Test examples in the given file. Return (#failures, #tests).
1847 Optional keyword arg "module_relative" specifies how filenames
1848 should be interpreted:
1850 - If "module_relative" is True (the default), then "filename"
1851 specifies a module-relative path. By default, this path is
1852 relative to the calling module's directory; but if the
1853 "package" argument is specified, then it is relative to that
1854 package. To ensure os-independence, "filename" should use
1855 "/" characters to separate path segments, and should not
1856 be an absolute path (i.e., it may not begin with "/").
1858 - If "module_relative" is False, then "filename" specifies an
1859 os-specific path. The path may be absolute or relative (to
1860 the current working directory).
1862 Optional keyword arg "name" gives the name of the test; by default
1863 use the file's basename.
1865 Optional keyword argument "package" is a Python package or the
1866 name of a Python package whose directory should be used as the
1867 base directory for a module relative filename. If no package is
1868 specified, then the calling module's directory is used as the base
1869 directory for module relative filenames. It is an error to
1870 specify "package" if "module_relative" is False.
1872 Optional keyword arg "globs" gives a dict to be used as the globals
1873 when executing examples; by default, use {}. A copy of this dict
1874 is actually used for each docstring, so that each docstring's
1875 examples start with a clean slate.
1877 Optional keyword arg "extraglobs" gives a dictionary that should be
1878 merged into the globals that are used to execute examples. By
1879 default, no extra globals are used.
1881 Optional keyword arg "verbose" prints lots of stuff if true, prints
1882 only failures if false; by default, it's true iff "-v" is in sys.argv.
1884 Optional keyword arg "report" prints a summary at the end when true,
1885 else prints nothing at the end. In verbose mode, the summary is
1886 detailed, else very brief (in fact, empty if all tests passed).
1888 Optional keyword arg "optionflags" or's together module constants,
1889 and defaults to 0. Possible values (see the docs for details):
1891 DONT_ACCEPT_TRUE_FOR_1
1892 DONT_ACCEPT_BLANKLINE
1893 NORMALIZE_WHITESPACE
1896 IGNORE_EXCEPTION_DETAIL
1900 REPORT_ONLY_FIRST_FAILURE
1902 Optional keyword arg "raise_on_error" raises an exception on the
1903 first unexpected exception or failure. This allows failures to be
1904 post-mortem debugged.
1906 Optional keyword arg "parser" specifies a DocTestParser (or
1907 subclass) that should be used to extract tests from the files.
1909 Optional keyword arg "encoding" specifies an encoding that should
1910 be used to convert the file to unicode.
1912 Advanced tomfoolery: testmod runs methods of a local instance of
1913 class doctest.Tester, then merges the results into (or creates)
1914 global Tester instance doctest.master. Methods of doctest.master
1915 can be called directly too, if you want to do something unusual.
1916 Passing report=0 to testmod is especially useful then, to delay
1917 displaying a summary. Invoke doctest.master.summarize(verbose)
1918 when you're done fiddling.
1922 if package
and not module_relative
:
1923 raise ValueError("Package may only be specified for module-"
1926 # Relativize the path
1927 text
, filename
= _load_testfile(filename
, package
, module_relative
)
1929 # If no name was given, then use the file's name.
1931 name
= os
.path
.basename(filename
)
1933 # Assemble the globals.
1937 globs
= globs
.copy()
1938 if extraglobs
is not None:
1939 globs
.update(extraglobs
)
1942 runner
= DebugRunner(verbose
=verbose
, optionflags
=optionflags
)
1944 runner
= DocTestRunner(verbose
=verbose
, optionflags
=optionflags
)
1946 if encoding
is not None:
1947 text
= text
.decode(encoding
)
1949 # Read the file, convert it to a test, and run it.
1950 test
= parser
.get_doctest(text
, globs
, name
, filename
, 0)
1959 master
.merge(runner
)
1961 return TestResults(runner
.failures
, runner
.tries
)
1963 def run_docstring_examples(f
, globs
, verbose
=False, name
="NoName",
1964 compileflags
=None, optionflags
=0):
1966 Test examples in the given object's docstring (`f`), using `globs`
1967 as globals. Optional argument `name` is used in failure messages.
1968 If the optional argument `verbose` is true, then generate output
1969 even if there are no failures.
1971 `compileflags` gives the set of flags that should be used by the
1972 Python compiler when running the examples. If not specified, then
1973 it will default to the set of future-import flags that apply to
1976 Optional keyword arg `optionflags` specifies options for the
1977 testing and output. See the documentation for `testmod` for more
1980 # Find, parse, and run all tests in the given module.
1981 finder
= DocTestFinder(verbose
=verbose
, recurse
=False)
1982 runner
= DocTestRunner(verbose
=verbose
, optionflags
=optionflags
)
1983 for test
in finder
.find(f
, name
, globs
=globs
):
1984 runner
.run(test
, compileflags
=compileflags
)
1986 ######################################################################
1988 ######################################################################
1989 # This is provided only for backwards compatibility. It's not
1990 # actually used in any way.
1993 def __init__(self
, mod
=None, globs
=None, verbose
=None, optionflags
=0):
1995 warnings
.warn("class Tester is deprecated; "
1996 "use class doctest.DocTestRunner instead",
1997 DeprecationWarning, stacklevel
=2)
1998 if mod
is None and globs
is None:
1999 raise TypeError("Tester.__init__: must specify mod or globs")
2000 if mod
is not None and not inspect
.ismodule(mod
):
2001 raise TypeError("Tester.__init__: mod must be a module; %r" %
2004 globs
= mod
.__dict
__
2007 self
.verbose
= verbose
2008 self
.optionflags
= optionflags
2009 self
.testfinder
= DocTestFinder()
2010 self
.testrunner
= DocTestRunner(verbose
=verbose
,
2011 optionflags
=optionflags
)
2013 def runstring(self
, s
, name
):
2014 test
= DocTestParser().get_doctest(s
, self
.globs
, name
, None, None)
2016 print "Running string", name
2017 (f
,t
) = self
.testrunner
.run(test
)
2019 print f
, "of", t
, "examples failed in string", name
2020 return TestResults(f
,t
)
2022 def rundoc(self
, object, name
=None, module
=None):
2024 tests
= self
.testfinder
.find(object, name
, module
=module
,
2027 (f2
, t2
) = self
.testrunner
.run(test
)
2028 (f
,t
) = (f
+f2
, t
+t2
)
2029 return TestResults(f
,t
)
2031 def rundict(self
, d
, name
, module
=None):
2033 m
= types
.ModuleType(name
)
2034 m
.__dict
__.update(d
)
2037 return self
.rundoc(m
, name
, module
)
2039 def run__test__(self
, d
, name
):
2041 m
= types
.ModuleType(name
)
2043 return self
.rundoc(m
, name
)
2045 def summarize(self
, verbose
=None):
2046 return self
.testrunner
.summarize(verbose
)
2048 def merge(self
, other
):
2049 self
.testrunner
.merge(other
.testrunner
)
2051 ######################################################################
2052 ## 8. Unittest Support
2053 ######################################################################
2055 _unittest_reportflags
= 0
2057 def set_unittest_reportflags(flags
):
2058 """Sets the unittest option flags.
2060 The old flag is returned so that a runner could restore the old
2061 value if it wished to:
2064 >>> old = doctest._unittest_reportflags
2065 >>> doctest.set_unittest_reportflags(REPORT_NDIFF |
2066 ... REPORT_ONLY_FIRST_FAILURE) == old
2069 >>> doctest._unittest_reportflags == (REPORT_NDIFF |
2070 ... REPORT_ONLY_FIRST_FAILURE)
2073 Only reporting flags can be set:
2075 >>> doctest.set_unittest_reportflags(ELLIPSIS)
2076 Traceback (most recent call last):
2078 ValueError: ('Only reporting flags allowed', 8)
2080 >>> doctest.set_unittest_reportflags(old) == (REPORT_NDIFF |
2081 ... REPORT_ONLY_FIRST_FAILURE)
2084 global _unittest_reportflags
2086 if (flags
& REPORTING_FLAGS
) != flags
:
2087 raise ValueError("Only reporting flags allowed", flags
)
2088 old
= _unittest_reportflags
2089 _unittest_reportflags
= flags
2093 class DocTestCase(unittest
.TestCase
):
2095 def __init__(self
, test
, optionflags
=0, setUp
=None, tearDown
=None,
2098 unittest
.TestCase
.__init
__(self
)
2099 self
._dt
_optionflags
= optionflags
2100 self
._dt
_checker
= checker
2101 self
._dt
_test
= test
2102 self
._dt
_setUp
= setUp
2103 self
._dt
_tearDown
= tearDown
2106 test
= self
._dt
_test
2108 if self
._dt
_setUp
is not None:
2109 self
._dt
_setUp
(test
)
2112 test
= self
._dt
_test
2114 if self
._dt
_tearDown
is not None:
2115 self
._dt
_tearDown
(test
)
2120 test
= self
._dt
_test
2123 optionflags
= self
._dt
_optionflags
2125 if not (optionflags
& REPORTING_FLAGS
):
2126 # The option flags don't include any reporting flags,
2127 # so add the default reporting flags
2128 optionflags |
= _unittest_reportflags
2130 runner
= DocTestRunner(optionflags
=optionflags
,
2131 checker
=self
._dt
_checker
, verbose
=False)
2134 runner
.DIVIDER
= "-"*70
2135 failures
, tries
= runner
.run(
2136 test
, out
=new
.write
, clear_globs
=False)
2141 raise self
.failureException(self
.format_failure(new
.getvalue()))
2143 def format_failure(self
, err
):
2144 test
= self
._dt
_test
2145 if test
.lineno
is None:
2146 lineno
= 'unknown line number'
2148 lineno
= '%s' % test
.lineno
2149 lname
= '.'.join(test
.name
.split('.')[-1:])
2150 return ('Failed doctest test for %s\n'
2151 ' File "%s", line %s, in %s\n\n%s'
2152 % (test
.name
, test
.filename
, lineno
, lname
, err
)
2156 r
"""Run the test case without results and without catching exceptions
2158 The unit test framework includes a debug method on test cases
2159 and test suites to support post-mortem debugging. The test code
2160 is run in such a way that errors are not caught. This way a
2161 caller can catch the errors and initiate post-mortem debugging.
2163 The DocTestCase provides a debug method that raises
2164 UnexpectedException errors if there is an unexepcted
2167 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
2168 ... {}, 'foo', 'foo.py', 0)
2169 >>> case = DocTestCase(test)
2172 ... except UnexpectedException, failure:
2175 The UnexpectedException contains the test, the example, and
2176 the original exception:
2178 >>> failure.test is test
2181 >>> failure.example.want
2184 >>> exc_info = failure.exc_info
2185 >>> raise exc_info[0], exc_info[1], exc_info[2]
2186 Traceback (most recent call last):
2190 If the output doesn't match, then a DocTestFailure is raised:
2192 >>> test = DocTestParser().get_doctest('''
2196 ... ''', {}, 'foo', 'foo.py', 0)
2197 >>> case = DocTestCase(test)
2201 ... except DocTestFailure, failure:
2204 DocTestFailure objects provide access to the test:
2206 >>> failure.test is test
2209 As well as to the example:
2211 >>> failure.example.want
2214 and the actual output:
2222 runner
= DebugRunner(optionflags
=self
._dt
_optionflags
,
2223 checker
=self
._dt
_checker
, verbose
=False)
2224 runner
.run(self
._dt
_test
, clear_globs
=False)
2228 return self
._dt
_test
.name
2231 name
= self
._dt
_test
.name
.split('.')
2232 return "%s (%s)" % (name
[-1], '.'.join(name
[:-1]))
2236 def shortDescription(self
):
2237 return "Doctest: " + self
._dt
_test
.name
2239 def DocTestSuite(module
=None, globs
=None, extraglobs
=None, test_finder
=None,
2242 Convert doctest tests for a module to a unittest test suite.
2244 This converts each documentation string in a module that
2245 contains doctest tests to a unittest test case. If any of the
2246 tests in a doc string fail, then the test case fails. An exception
2247 is raised showing the name of the file containing the test and a
2248 (sometimes approximate) line number.
2250 The `module` argument provides the module to be tested. The argument
2251 can be either a module or a module name.
2253 If no argument is given, the calling module is used.
2255 A number of options may be provided as keyword arguments:
2258 A set-up function. This is called before running the
2259 tests in each file. The setUp function will be passed a DocTest
2260 object. The setUp function can access the test globals as the
2261 globs attribute of the test passed.
2264 A tear-down function. This is called after running the
2265 tests in each file. The tearDown function will be passed a DocTest
2266 object. The tearDown function can access the test globals as the
2267 globs attribute of the test passed.
2270 A dictionary containing initial global variables for the tests.
2273 A set of doctest option flags expressed as an integer.
2276 if test_finder
is None:
2277 test_finder
= DocTestFinder()
2279 module
= _normalize_module(module
)
2280 tests
= test_finder
.find(module
, globs
=globs
, extraglobs
=extraglobs
)
2282 # Why do we want to do this? Because it reveals a bug that might
2283 # otherwise be hidden.
2284 raise ValueError(module
, "has no tests")
2287 suite
= unittest
.TestSuite()
2289 if len(test
.examples
) == 0:
2291 if not test
.filename
:
2292 filename
= module
.__file
__
2293 if filename
[-4:] in (".pyc", ".pyo"):
2294 filename
= filename
[:-1]
2295 test
.filename
= filename
2296 suite
.addTest(DocTestCase(test
, **options
))
2300 class DocFileCase(DocTestCase
):
2303 return '_'.join(self
._dt
_test
.name
.split('.'))
2306 return self
._dt
_test
.filename
2309 def format_failure(self
, err
):
2310 return ('Failed doctest test for %s\n File "%s", line 0\n\n%s'
2311 % (self
._dt
_test
.name
, self
._dt
_test
.filename
, err
)
2314 def DocFileTest(path
, module_relative
=True, package
=None,
2315 globs
=None, parser
=DocTestParser(),
2316 encoding
=None, **options
):
2320 globs
= globs
.copy()
2322 if package
and not module_relative
:
2323 raise ValueError("Package may only be specified for module-"
2326 # Relativize the path.
2327 doc
, path
= _load_testfile(path
, package
, module_relative
)
2329 if "__file__" not in globs
:
2330 globs
["__file__"] = path
2332 # Find the file and read it.
2333 name
= os
.path
.basename(path
)
2335 # If an encoding is specified, use it to convert the file to unicode
2336 if encoding
is not None:
2337 doc
= doc
.decode(encoding
)
2339 # Convert it to a test, and wrap it in a DocFileCase.
2340 test
= parser
.get_doctest(doc
, globs
, name
, path
, 0)
2341 return DocFileCase(test
, **options
)
2343 def DocFileSuite(*paths
, **kw
):
2344 """A unittest suite for one or more doctest files.
2346 The path to each doctest file is given as a string; the
2347 interpretation of that string depends on the keyword argument
2350 A number of options may be provided as keyword arguments:
2353 If "module_relative" is True, then the given file paths are
2354 interpreted as os-independent module-relative paths. By
2355 default, these paths are relative to the calling module's
2356 directory; but if the "package" argument is specified, then
2357 they are relative to that package. To ensure os-independence,
2358 "filename" should use "/" characters to separate path
2359 segments, and may not be an absolute path (i.e., it may not
2362 If "module_relative" is False, then the given file paths are
2363 interpreted as os-specific paths. These paths may be absolute
2364 or relative (to the current working directory).
2367 A Python package or the name of a Python package whose directory
2368 should be used as the base directory for module relative paths.
2369 If "package" is not specified, then the calling module's
2370 directory is used as the base directory for module relative
2371 filenames. It is an error to specify "package" if
2372 "module_relative" is False.
2375 A set-up function. This is called before running the
2376 tests in each file. The setUp function will be passed a DocTest
2377 object. The setUp function can access the test globals as the
2378 globs attribute of the test passed.
2381 A tear-down function. This is called after running the
2382 tests in each file. The tearDown function will be passed a DocTest
2383 object. The tearDown function can access the test globals as the
2384 globs attribute of the test passed.
2387 A dictionary containing initial global variables for the tests.
2390 A set of doctest option flags expressed as an integer.
2393 A DocTestParser (or subclass) that should be used to extract
2394 tests from the files.
2397 An encoding that will be used to convert the files to unicode.
2399 suite
= unittest
.TestSuite()
2401 # We do this here so that _normalize_module is called at the right
2402 # level. If it were called in DocFileTest, then this function
2403 # would be the caller and we might guess the package incorrectly.
2404 if kw
.get('module_relative', True):
2405 kw
['package'] = _normalize_module(kw
.get('package'))
2408 suite
.addTest(DocFileTest(path
, **kw
))
2412 ######################################################################
2413 ## 9. Debugging Support
2414 ######################################################################
2416 def script_from_examples(s
):
2417 r
"""Extract script from text with examples.
2419 Converts text with examples to a Python script. Example input is
2420 converted to regular code. Example output and all other words
2421 are converted to comments:
2424 ... Here are examples of simple math.
2426 ... Python has super accurate integer addition
2431 ... And very friendly error messages:
2438 ... You can use logic if you want:
2448 >>> print script_from_examples(text)
2449 # Here are examples of simple math.
2451 # Python has super accurate integer addition
2457 # And very friendly error messages:
2465 # You can use logic if you want:
2475 for piece
in DocTestParser().parse(s
):
2476 if isinstance(piece
, Example
):
2477 # Add the example's source code (strip trailing NL)
2478 output
.append(piece
.source
[:-1])
2479 # Add the expected output:
2482 output
.append('# Expected:')
2483 output
+= ['## '+l
for l
in want
.split('\n')[:-1]]
2485 # Add non-example text.
2486 output
+= [_comment_line(l
)
2487 for l
in piece
.split('\n')[:-1]]
2489 # Trim junk on both ends.
2490 while output
and output
[-1] == '#':
2492 while output
and output
[0] == '#':
2494 # Combine the output, and return it.
2495 # Add a courtesy newline to prevent exec from choking (see bug #1172785)
2496 return '\n'.join(output
) + '\n'
2498 def testsource(module
, name
):
2499 """Extract the test sources from a doctest docstring as a script.
2501 Provide the module (or dotted name of the module) containing the
2502 test to be debugged and the name (within the module) of the object
2503 with the doc string with tests to be debugged.
2505 module
= _normalize_module(module
)
2506 tests
= DocTestFinder().find(module
)
2507 test
= [t
for t
in tests
if t
.name
== name
]
2509 raise ValueError(name
, "not found in tests")
2511 testsrc
= script_from_examples(test
.docstring
)
2514 def debug_src(src
, pm
=False, globs
=None):
2515 """Debug a single doctest docstring, in argument `src`'"""
2516 testsrc
= script_from_examples(src
)
2517 debug_script(testsrc
, pm
, globs
)
2519 def debug_script(src
, pm
=False, globs
=None):
2520 "Debug a test script. `src` is the script, as a string."
2523 # Note that tempfile.NameTemporaryFile() cannot be used. As the
2524 # docs say, a file so created cannot be opened by name a second time
2525 # on modern Windows boxes, and execfile() needs to open it.
2526 srcfilename
= tempfile
.mktemp(".py", "doctestdebug")
2527 f
= open(srcfilename
, 'w')
2533 globs
= globs
.copy()
2539 execfile(srcfilename
, globs
, globs
)
2541 print sys
.exc_info()[1]
2542 pdb
.post_mortem(sys
.exc_info()[2])
2544 # Note that %r is vital here. '%s' instead can, e.g., cause
2545 # backslashes to get treated as metacharacters on Windows.
2546 pdb
.run("execfile(%r)" % srcfilename
, globs
, globs
)
2549 os
.remove(srcfilename
)
2551 def debug(module
, name
, pm
=False):
2552 """Debug a single doctest docstring.
2554 Provide the module (or dotted name of the module) containing the
2555 test to be debugged and the name (within the module) of the object
2556 with the docstring with tests to be debugged.
2558 module
= _normalize_module(module
)
2559 testsrc
= testsource(module
, name
)
2560 debug_script(testsrc
, pm
, module
.__dict
__)
2562 ######################################################################
2563 ## 10. Example Usage
2564 ######################################################################
2567 A pointless class, for sanity-checking of docstring testing.
2573 >>> _TestClass(13).get() + _TestClass(-12).get()
2575 >>> hex(_TestClass(13).square().get())
2579 def __init__(self
, val
):
2580 """val -> _TestClass object with associated value val.
2582 >>> t = _TestClass(123)
2590 """square() -> square TestClass's associated value
2592 >>> _TestClass(13).square().get()
2596 self
.val
= self
.val
** 2
2600 """get() -> return TestClass's associated value.
2602 >>> x = _TestClass(-42)
2609 __test__
= {"_TestClass": _TestClass
,
2611 Example of a string object, searched as-is.
2617 "bool-int equivalence": r
"""
2618 In 2.2, boolean expressions displayed
2619 0 or 1. By default, we still accept
2620 them. This can be disabled by passing
2621 DONT_ACCEPT_TRUE_FOR_1 to the new
2622 optionflags argument.
2634 Blank lines can be marked with <BLANKLINE>:
2635 >>> print 'foo\n\nbar\n'
2643 If the ellipsis flag is used, then '...' can be used to
2644 elide substrings in the desired output:
2645 >>> print range(1000) #doctest: +ELLIPSIS
2649 "whitespace normalization": r
"""
2650 If the whitespace normalization flag is used, then
2651 differences in whitespace are ignored.
2652 >>> print range(30) #doctest: +NORMALIZE_WHITESPACE
2653 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
2654 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,
2660 testfiles
= [arg
for arg
in sys
.argv
[1:] if arg
and arg
[0] != '-']
2662 for filename
in testfiles
:
2663 if filename
.endswith(".py"):
2664 # It is a module -- insert its dir into sys.path and try to
2665 # import it. If it is part of a package, that possibly won't work
2666 # because of package imports.
2667 dirname
, filename
= os
.path
.split(filename
)
2668 sys
.path
.insert(0, dirname
)
2669 m
= __import__(filename
[:-3])
2671 failures
, _
= testmod(m
)
2673 failures
, _
= testfile(filename
, module_relative
=False)
2677 r
= unittest
.TextTestRunner()
2678 r
.run(DocTestSuite())
2681 if __name__
== "__main__":