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
103 # There are 4 basic classes:
104 # - Example: a <source, want> pair, plus an intra-docstring line number.
105 # - DocTest: a collection of examples, parsed from a docstring, plus
106 # info about where the docstring came from (name, filename, lineno).
107 # - DocTestFinder: extracts DocTests from a given object's docstring and
108 # its contained objects' docstrings.
109 # - DocTestRunner: runs DocTest cases, and accumulates statistics.
111 # So the basic picture is:
114 # +------+ +---------+ +-------+
115 # |object| --DocTestFinder-> | DocTest | --DocTestRunner-> |results|
116 # +------+ +---------+ +-------+
124 OPTIONFLAGS_BY_NAME
= {}
125 def register_optionflag(name
):
126 # Create a new flag unless `name` is already known.
127 return OPTIONFLAGS_BY_NAME
.setdefault(name
, 1 << len(OPTIONFLAGS_BY_NAME
))
129 DONT_ACCEPT_TRUE_FOR_1
= register_optionflag('DONT_ACCEPT_TRUE_FOR_1')
130 DONT_ACCEPT_BLANKLINE
= register_optionflag('DONT_ACCEPT_BLANKLINE')
131 NORMALIZE_WHITESPACE
= register_optionflag('NORMALIZE_WHITESPACE')
132 ELLIPSIS
= register_optionflag('ELLIPSIS')
133 SKIP
= register_optionflag('SKIP')
134 IGNORE_EXCEPTION_DETAIL
= register_optionflag('IGNORE_EXCEPTION_DETAIL')
136 COMPARISON_FLAGS
= (DONT_ACCEPT_TRUE_FOR_1 |
137 DONT_ACCEPT_BLANKLINE |
138 NORMALIZE_WHITESPACE |
141 IGNORE_EXCEPTION_DETAIL
)
143 REPORT_UDIFF
= register_optionflag('REPORT_UDIFF')
144 REPORT_CDIFF
= register_optionflag('REPORT_CDIFF')
145 REPORT_NDIFF
= register_optionflag('REPORT_NDIFF')
146 REPORT_ONLY_FIRST_FAILURE
= register_optionflag('REPORT_ONLY_FIRST_FAILURE')
148 REPORTING_FLAGS
= (REPORT_UDIFF |
151 REPORT_ONLY_FIRST_FAILURE
)
153 # Special string markers for use in `want` strings:
154 BLANKLINE_MARKER
= '<BLANKLINE>'
155 ELLIPSIS_MARKER
= '...'
157 ######################################################################
159 ######################################################################
160 # 1. Utility Functions
161 # 2. Example & DocTest -- store test cases
162 # 3. DocTest Parser -- extracts examples from strings
163 # 4. DocTest Finder -- extracts test cases from objects
164 # 5. DocTest Runner -- runs test cases
165 # 6. Test Functions -- convenient wrappers for testing
166 # 7. Tester Class -- for backwards compatibility
167 # 8. Unittest Support
168 # 9. Debugging Support
171 ######################################################################
172 ## 1. Utility Functions
173 ######################################################################
175 def _extract_future_flags(globs
):
177 Return the compiler-flags associated with the future features that
178 have been imported into the given namespace (globs).
181 for fname
in __future__
.all_feature_names
:
182 feature
= globs
.get(fname
, None)
183 if feature
is getattr(__future__
, fname
):
184 flags |
= feature
.compiler_flag
187 def _normalize_module(module
, depth
=2):
189 Return the module specified by `module`. In particular:
190 - If `module` is a module, then return module.
191 - If `module` is a string, then import and return the
192 module with that name.
193 - If `module` is None, then return the calling module.
194 The calling module is assumed to be the module of
195 the stack frame at the given depth in the call stack.
197 if inspect
.ismodule(module
):
199 elif isinstance(module
, (str, unicode)):
200 return __import__(module
, globals(), locals(), ["*"])
202 return sys
.modules
[sys
._getframe
(depth
).f_globals
['__name__']]
204 raise TypeError("Expected a module, string, or None")
206 def _load_testfile(filename
, package
, module_relative
):
208 package
= _normalize_module(package
, 3)
209 filename
= _module_relative_path(package
, filename
)
210 if hasattr(package
, '__loader__'):
211 if hasattr(package
.__loader
__, 'get_data'):
212 file_contents
= package
.__loader
__.get_data(filename
)
213 # get_data() opens files as 'rb', so one must do the equivalent
214 # conversion as universal newlines would do.
215 return file_contents
.replace(os
.linesep
, '\n'), filename
216 return open(filename
).read(), filename
218 def _indent(s
, indent
=4):
220 Add the given number of space characters to the beginning every
221 non-blank line in `s`, and return the result.
223 # This regexp matches the start of non-blank lines:
224 return re
.sub('(?m)^(?!$)', indent
*' ', s
)
226 def _exception_traceback(exc_info
):
228 Return a string containing a traceback message for the given
229 exc_info tuple (as returned by sys.exc_info()).
231 # Get a traceback message.
233 exc_type
, exc_val
, exc_tb
= exc_info
234 traceback
.print_exception(exc_type
, exc_val
, exc_tb
, file=excout
)
235 return excout
.getvalue()
237 # Override some StringIO methods.
238 class _SpoofOut(StringIO
):
240 result
= StringIO
.getvalue(self
)
241 # If anything at all was written, make sure there's a trailing
242 # newline. There's no way for the expected output to indicate
243 # that a trailing newline is missing.
244 if result
and not result
.endswith("\n"):
246 # Prevent softspace from screwing up the next test case, in
247 # case they used print with a trailing comma in an example.
248 if hasattr(self
, "softspace"):
252 def truncate(self
, size
=None):
253 StringIO
.truncate(self
, size
)
254 if hasattr(self
, "softspace"):
257 # Worst-case linear-time ellipsis matching.
258 def _ellipsis_match(want
, got
):
260 Essentially the only subtle case:
261 >>> _ellipsis_match('aa...aa', 'aaa')
264 if ELLIPSIS_MARKER
not in want
:
267 # Find "the real" strings.
268 ws
= want
.split(ELLIPSIS_MARKER
)
271 # Deal with exact matches possibly needed at one or both ends.
272 startpos
, endpos
= 0, len(got
)
274 if w
: # starts with exact match
275 if got
.startswith(w
):
281 if w
: # ends with exact match
288 if startpos
> endpos
:
289 # Exact end matches required more characters than we have, as in
290 # _ellipsis_match('aa...aa', 'aaa')
293 # For the rest, we only need to find the leftmost non-overlapping
294 # match for each piece. If there's no overall match that way alone,
295 # there's no overall match period.
297 # w may be '' at times, if there are consecutive ellipses, or
298 # due to an ellipsis at the start or end of `want`. That's OK.
299 # Search for an empty string succeeds, and doesn't change startpos.
300 startpos
= got
.find(w
, startpos
, endpos
)
307 def _comment_line(line
):
308 "Return a commented form of the given line"
315 class _OutputRedirectingPdb(pdb
.Pdb
):
317 A specialized version of the python debugger that redirects stdout
318 to a given stream when interacting with the user. Stdout is *not*
319 redirected when traced code is executed.
321 def __init__(self
, out
):
323 self
.__debugger
_used
= False
324 pdb
.Pdb
.__init
__(self
, stdout
=out
)
326 def set_trace(self
, frame
=None):
327 self
.__debugger
_used
= True
329 frame
= sys
._getframe
().f_back
330 pdb
.Pdb
.set_trace(self
, frame
)
332 def set_continue(self
):
333 # Calling set_continue unconditionally would break unit test
334 # coverage reporting, as Bdb.set_continue calls sys.settrace(None).
335 if self
.__debugger
_used
:
336 pdb
.Pdb
.set_continue(self
)
338 def trace_dispatch(self
, *args
):
339 # Redirect stdout to the given stream.
340 save_stdout
= sys
.stdout
341 sys
.stdout
= self
.__out
342 # Call Pdb's trace dispatch method.
344 return pdb
.Pdb
.trace_dispatch(self
, *args
)
346 sys
.stdout
= save_stdout
348 # [XX] Normalize with respect to os.path.pardir?
349 def _module_relative_path(module
, path
):
350 if not inspect
.ismodule(module
):
351 raise TypeError, 'Expected a module: %r' % module
352 if path
.startswith('/'):
353 raise ValueError, 'Module-relative files may not have absolute paths'
355 # Find the base directory for the path.
356 if hasattr(module
, '__file__'):
357 # A normal module/package
358 basedir
= os
.path
.split(module
.__file
__)[0]
359 elif module
.__name
__ == '__main__':
360 # An interactive session.
361 if len(sys
.argv
)>0 and sys
.argv
[0] != '':
362 basedir
= os
.path
.split(sys
.argv
[0])[0]
366 # A module w/o __file__ (this includes builtins)
367 raise ValueError("Can't resolve paths relative to the module " +
368 module
+ " (it has no __file__)")
370 # Combine the base directory and the path.
371 return os
.path
.join(basedir
, *(path
.split('/')))
373 ######################################################################
374 ## 2. Example & DocTest
375 ######################################################################
376 ## - An "example" is a <source, want> pair, where "source" is a
377 ## fragment of source code, and "want" is the expected output for
378 ## "source." The Example class also includes information about
379 ## where the example was extracted from.
381 ## - A "doctest" is a collection of examples, typically extracted from
382 ## a string (such as an object's docstring). The DocTest class also
383 ## includes information about where the string was extracted from.
387 A single doctest example, consisting of source code and expected
388 output. `Example` defines the following attributes:
390 - source: A single Python statement, always ending with a newline.
391 The constructor adds a newline if needed.
393 - want: The expected output from running the source code (either
394 from stdout, or a traceback in case of exception). `want` ends
395 with a newline unless it's empty, in which case it's an empty
396 string. The constructor adds a newline if needed.
398 - exc_msg: The exception message generated by the example, if
399 the example is expected to generate an exception; or `None` if
400 it is not expected to generate an exception. This exception
401 message is compared against the return value of
402 `traceback.format_exception_only()`. `exc_msg` ends with a
403 newline unless it's `None`. The constructor adds a newline
406 - lineno: The line number within the DocTest string containing
407 this Example where the Example begins. This line number is
408 zero-based, with respect to the beginning of the DocTest.
410 - indent: The example's indentation in the DocTest string.
411 I.e., the number of space characters that preceed the
412 example's first prompt.
414 - options: A dictionary mapping from option flags to True or
415 False, which is used to override default options for this
416 example. Any option flags not contained in this dictionary
417 are left at their default value (as specified by the
418 DocTestRunner's optionflags). By default, no options are set.
420 def __init__(self
, source
, want
, exc_msg
=None, lineno
=0, indent
=0,
423 if not source
.endswith('\n'):
425 if want
and not want
.endswith('\n'):
427 if exc_msg
is not None and not exc_msg
.endswith('\n'):
434 if options
is None: options
= {}
435 self
.options
= options
436 self
.exc_msg
= exc_msg
440 A collection of doctest examples that should be run in a single
441 namespace. Each `DocTest` defines the following attributes:
443 - examples: the list of examples.
445 - globs: The namespace (aka globals) that the examples should
448 - name: A name identifying the DocTest (typically, the name of
449 the object whose docstring this DocTest was extracted from).
451 - filename: The name of the file that this DocTest was extracted
452 from, or `None` if the filename is unknown.
454 - lineno: The line number within filename where this DocTest
455 begins, or `None` if the line number is unavailable. This
456 line number is zero-based, with respect to the beginning of
459 - docstring: The string that the examples were extracted from,
460 or `None` if the string is unavailable.
462 def __init__(self
, examples
, globs
, name
, filename
, lineno
, docstring
):
464 Create a new DocTest containing the given examples. The
465 DocTest's globals are initialized with a copy of `globs`.
467 assert not isinstance(examples
, basestring
), \
468 "DocTest no longer accepts str; use DocTestParser instead"
469 self
.examples
= examples
470 self
.docstring
= docstring
471 self
.globs
= globs
.copy()
473 self
.filename
= filename
477 if len(self
.examples
) == 0:
478 examples
= 'no examples'
479 elif len(self
.examples
) == 1:
480 examples
= '1 example'
482 examples
= '%d examples' % len(self
.examples
)
483 return ('<DocTest %s from %s:%s (%s)>' %
484 (self
.name
, self
.filename
, self
.lineno
, examples
))
487 # This lets us sort tests by name:
488 def __cmp__(self
, other
):
489 if not isinstance(other
, DocTest
):
491 return cmp((self
.name
, self
.filename
, self
.lineno
, id(self
)),
492 (other
.name
, other
.filename
, other
.lineno
, id(other
)))
494 ######################################################################
496 ######################################################################
500 A class used to parse strings containing doctest examples.
502 # This regular expression is used to find doctest examples in a
503 # string. It defines three groups: `source` is the source code
504 # (including leading indentation and prompts); `indent` is the
505 # indentation of the first (PS1) line of the source code; and
506 # `want` is the expected output (including leading indentation).
507 _EXAMPLE_RE
= re
.compile(r
'''
508 # Source consists of a PS1 line followed by zero or more PS2 lines.
510 (?:^(?P<indent> [ ]*) >>> .*) # PS1 line
511 (?:\n [ ]* \.\.\. .*)*) # PS2 lines
513 # Want consists of any non-blank lines that do not start with PS1.
514 (?P<want> (?:(?![ ]*$) # Not a blank line
515 (?![ ]*>>>) # Not a line starting with PS1
516 .*$\n? # But any other line
518 ''', re
.MULTILINE | re
.VERBOSE
)
520 # A regular expression for handling `want` strings that contain
521 # expected exceptions. It divides `want` into three pieces:
522 # - the traceback header line (`hdr`)
523 # - the traceback stack (`stack`)
524 # - the exception message (`msg`), as generated by
525 # traceback.format_exception_only()
526 # `msg` may have multiple lines. We assume/require that the
527 # exception message is the first non-indented line starting with a word
528 # character following the traceback header line.
529 _EXCEPTION_RE
= re
.compile(r
"""
530 # Grab the traceback header. Different versions of Python have
531 # said different things on the first traceback line.
532 ^(?P<hdr> Traceback\ \(
533 (?: most\ recent\ call\ last
537 \s* $ # toss trailing whitespace on the header.
538 (?P<stack> .*?) # don't blink: absorb stuff until...
539 ^ (?P<msg> \w+ .*) # a line *starts* with alphanum.
540 """, re
.VERBOSE | re
.MULTILINE | re
.DOTALL
)
542 # A callable returning a true value iff its argument is a blank line
543 # or contains a single comment.
544 _IS_BLANK_OR_COMMENT
= re
.compile(r
'^[ ]*(#.*)?$').match
546 def parse(self
, string
, name
='<string>'):
548 Divide the given string into examples and intervening text,
549 and return them as a list of alternating Examples and strings.
550 Line numbers for the Examples are 0-based. The optional
551 argument `name` is a name identifying this string, and is only
552 used for error messages.
554 string
= string
.expandtabs()
555 # If all lines begin with the same indentation, then strip it.
556 min_indent
= self
._min
_indent
(string
)
558 string
= '\n'.join([l
[min_indent
:] for l
in string
.split('\n')])
561 charno
, lineno
= 0, 0
562 # Find all doctest examples in the string:
563 for m
in self
._EXAMPLE
_RE
.finditer(string
):
564 # Add the pre-example text to `output`.
565 output
.append(string
[charno
:m
.start()])
566 # Update lineno (lines before this example)
567 lineno
+= string
.count('\n', charno
, m
.start())
568 # Extract info from the regexp match.
569 (source
, options
, want
, exc_msg
) = \
570 self
._parse
_example
(m
, name
, lineno
)
571 # Create an Example, and add it to the list.
572 if not self
._IS
_BLANK
_OR
_COMMENT
(source
):
573 output
.append( Example(source
, want
, exc_msg
,
575 indent
=min_indent
+len(m
.group('indent')),
577 # Update lineno (lines inside this example)
578 lineno
+= string
.count('\n', m
.start(), m
.end())
581 # Add any remaining post-example text to `output`.
582 output
.append(string
[charno
:])
585 def get_doctest(self
, string
, globs
, name
, filename
, lineno
):
587 Extract all doctest examples from the given string, and
588 collect them into a `DocTest` object.
590 `globs`, `name`, `filename`, and `lineno` are attributes for
591 the new `DocTest` object. See the documentation for `DocTest`
592 for more information.
594 return DocTest(self
.get_examples(string
, name
), globs
,
595 name
, filename
, lineno
, string
)
597 def get_examples(self
, string
, name
='<string>'):
599 Extract all doctest examples from the given string, and return
600 them as a list of `Example` objects. Line numbers are
601 0-based, because it's most common in doctests that nothing
602 interesting appears on the same line as opening triple-quote,
603 and so the first interesting line is called \"line 1\" then.
605 The optional argument `name` is a name identifying this
606 string, and is only used for error messages.
608 return [x
for x
in self
.parse(string
, name
)
609 if isinstance(x
, Example
)]
611 def _parse_example(self
, m
, name
, lineno
):
613 Given a regular expression match from `_EXAMPLE_RE` (`m`),
614 return a pair `(source, want)`, where `source` is the matched
615 example's source code (with prompts and indentation stripped);
616 and `want` is the example's expected output (with indentation
619 `name` is the string's name, and `lineno` is the line number
620 where the example starts; both are used for error messages.
622 # Get the example's indentation level.
623 indent
= len(m
.group('indent'))
625 # Divide source into lines; check that they're properly
626 # indented; and then strip their indentation & prompts.
627 source_lines
= m
.group('source').split('\n')
628 self
._check
_prompt
_blank
(source_lines
, indent
, name
, lineno
)
629 self
._check
_prefix
(source_lines
[1:], ' '*indent
+ '.', name
, lineno
)
630 source
= '\n'.join([sl
[indent
+4:] for sl
in source_lines
])
632 # Divide want into lines; check that it's properly indented; and
633 # then strip the indentation. Spaces before the last newline should
634 # be preserved, so plain rstrip() isn't good enough.
635 want
= m
.group('want')
636 want_lines
= want
.split('\n')
637 if len(want_lines
) > 1 and re
.match(r
' *$', want_lines
[-1]):
638 del want_lines
[-1] # forget final newline & spaces after it
639 self
._check
_prefix
(want_lines
, ' '*indent
, name
,
640 lineno
+ len(source_lines
))
641 want
= '\n'.join([wl
[indent
:] for wl
in want_lines
])
643 # If `want` contains a traceback message, then extract it.
644 m
= self
._EXCEPTION
_RE
.match(want
)
646 exc_msg
= m
.group('msg')
650 # Extract options from the source.
651 options
= self
._find
_options
(source
, name
, lineno
)
653 return source
, options
, want
, exc_msg
655 # This regular expression looks for option directives in the
656 # source code of an example. Option directives are comments
657 # starting with "doctest:". Warning: this may give false
658 # positives for string-literals that contain the string
659 # "#doctest:". Eliminating these false positives would require
660 # actually parsing the string; but we limit them by ignoring any
661 # line containing "#doctest:" that is *followed* by a quote mark.
662 _OPTION_DIRECTIVE_RE
= re
.compile(r
'#\s*doctest:\s*([^\n\'"]*)$',
665 def _find_options(self, source, name, lineno):
667 Return a dictionary containing option overrides extracted from
668 option directives in the given source string.
670 `name` is the string's name, and `lineno` is the line number
671 where the example starts; both are used for error messages.
674 # (note: with the current regexp, this will match at most once:)
675 for m in self._OPTION_DIRECTIVE_RE.finditer(source):
676 option_strings = m.group(1).replace(',', ' ').split()
677 for option in option_strings:
678 if (option[0] not in '+-' or
679 option[1:] not in OPTIONFLAGS_BY_NAME):
680 raise ValueError('line %r of the doctest for %s '
681 'has an invalid option: %r' %
682 (lineno+1, name, option))
683 flag = OPTIONFLAGS_BY_NAME[option[1:]]
684 options[flag] = (option[0] == '+')
685 if options and self._IS_BLANK_OR_COMMENT(source):
686 raise ValueError('line %r of the doctest for %s has an option '
687 'directive on a line with no example: %r' %
688 (lineno, name, source))
691 # This regular expression finds the indentation of every non-blank
693 _INDENT_RE = re.compile('^([ ]*)(?=\S)', re.MULTILINE)
695 def _min_indent(self, s):
696 "Return the minimum indentation of any non
-blank line
in `s`
"
697 indents = [len(indent) for indent in self._INDENT_RE.findall(s)]
703 def _check_prompt_blank(self, lines, indent, name, lineno):
705 Given the lines of a source string (including prompts and
706 leading indentation), check to make sure that every prompt is
707 followed by a space character. If any line is not followed by
708 a space character, then raise ValueError.
710 for i, line in enumerate(lines):
711 if len(line) >= indent+4 and line[indent+3] != ' ':
712 raise ValueError('line %r of the docstring for %s '
713 'lacks blank after %s: %r' %
715 line[indent:indent+3], line))
717 def _check_prefix(self, lines, prefix, name, lineno):
719 Check that every line in the given list starts with the given
720 prefix; if any line does not, then raise a ValueError.
722 for i, line in enumerate(lines):
723 if line and not line.startswith(prefix):
724 raise ValueError('line %r of the docstring for %s has '
725 'inconsistent leading whitespace: %r' %
726 (lineno+i+1, name, line))
729 ######################################################################
731 ######################################################################
735 A class used to extract the DocTests that are relevant to a given
736 object, from its docstring and the docstrings of its contained
737 objects. Doctests can currently be extracted from the following
738 object types: modules, functions, classes, methods, staticmethods,
739 classmethods, and properties.
742 def __init__(self, verbose=False, parser=DocTestParser(),
743 recurse=True, exclude_empty=True):
745 Create a new doctest finder.
747 The optional argument `parser` specifies a class or
748 function that should be used to create new DocTest objects (or
749 objects that implement the same interface as DocTest). The
750 signature for this factory function should match the signature
751 of the DocTest constructor.
753 If the optional argument `recurse` is false, then `find` will
754 only examine the given object, and not any contained objects.
756 If the optional argument `exclude_empty` is false, then `find`
757 will include tests for objects with empty docstrings.
759 self._parser = parser
760 self._verbose = verbose
761 self._recurse = recurse
762 self._exclude_empty = exclude_empty
764 def find(self, obj, name=None, module=None, globs=None, extraglobs=None):
766 Return a list of the DocTests that are defined by the given
767 object's docstring, or by any of its contained objects'
770 The optional parameter `module` is the module that contains
771 the given object. If the module is not specified or is None, then
772 the test finder will attempt to automatically determine the
773 correct module. The object's module is used:
775 - As a default namespace, if `globs` is not specified.
776 - To prevent the DocTestFinder from extracting DocTests
777 from objects that are imported from other modules.
778 - To find the name of the file containing the object.
779 - To help find the line number of the object within its
782 Contained objects whose module does not match `module` are ignored.
784 If `module` is False, no attempt to find the module will be made.
785 This is obscure, of use mostly in tests: if `module` is False, or
786 is None but cannot be found automatically, then all objects are
787 considered to belong to the (non-existent) module, so all contained
788 objects will (recursively) be searched for doctests.
790 The globals for each DocTest is formed by combining `globs`
791 and `extraglobs` (bindings in `extraglobs` override bindings
792 in `globs`). A new copy of the globals dictionary is created
793 for each DocTest. If `globs` is not specified, then it
794 defaults to the module's `__dict__`, if specified, or {}
795 otherwise. If `extraglobs` is not specified, then it defaults
799 # If name was not specified, then extract it from the object.
801 name = getattr(obj, '__name__', None)
803 raise ValueError("DocTestFinder
.find
: name must be given
"
804 "when obj
.__name
__ doesn
't exist: %r" %
807 # Find the module that contains the given object (if obj is
808 # a module, then module=obj.). Note: this may fail, in which
809 # case module will be None.
813 module = inspect.getmodule(obj)
815 # Read the module's source code
. This
is used by
816 # DocTestFinder._find_lineno to find the line number for a
817 # given object's docstring.
819 file = inspect
.getsourcefile(obj
) or inspect
.getfile(obj
)
820 source_lines
= linecache
.getlines(file)
826 # Initialize globals, and merge in extraglobs.
831 globs
= module
.__dict
__.copy()
834 if extraglobs
is not None:
835 globs
.update(extraglobs
)
837 # Recursively expore `obj`, extracting DocTests.
839 self
._find
(tests
, obj
, name
, module
, source_lines
, globs
, {})
840 # Sort the tests by alpha order of names, for consistency in
841 # verbose-mode output. This was a feature of doctest in Pythons
842 # <= 2.3 that got lost by accident in 2.4. It was repaired in
847 def _from_module(self
, module
, object):
849 Return true if the given object is defined in the given
854 elif inspect
.isfunction(object):
855 return module
.__dict
__ is object.func_globals
856 elif inspect
.isclass(object):
857 return module
.__name
__ == object.__module
__
858 elif inspect
.getmodule(object) is not None:
859 return module
is inspect
.getmodule(object)
860 elif hasattr(object, '__module__'):
861 return module
.__name
__ == object.__module
__
862 elif isinstance(object, property):
863 return True # [XX] no way not be sure.
865 raise ValueError("object must be a class or function")
867 def _find(self
, tests
, obj
, name
, module
, source_lines
, globs
, seen
):
869 Find tests for the given object and any contained objects, and
873 print 'Finding tests in %s' % name
875 # If we've already processed this object, then ignore it.
880 # Find a test for this object, and add it to the list of tests.
881 test
= self
._get
_test
(obj
, name
, module
, globs
, source_lines
)
885 # Look for tests in a module's contained objects.
886 if inspect
.ismodule(obj
) and self
._recurse
:
887 for valname
, val
in obj
.__dict
__.items():
888 valname
= '%s.%s' % (name
, valname
)
889 # Recurse to functions & classes.
890 if ((inspect
.isfunction(val
) or inspect
.isclass(val
)) and
891 self
._from
_module
(module
, val
)):
892 self
._find
(tests
, val
, valname
, module
, source_lines
,
895 # Look for tests in a module's __test__ dictionary.
896 if inspect
.ismodule(obj
) and self
._recurse
:
897 for valname
, val
in getattr(obj
, '__test__', {}).items():
898 if not isinstance(valname
, basestring
):
899 raise ValueError("DocTestFinder.find: __test__ keys "
900 "must be strings: %r" %
902 if not (inspect
.isfunction(val
) or inspect
.isclass(val
) or
903 inspect
.ismethod(val
) or inspect
.ismodule(val
) or
904 isinstance(val
, basestring
)):
905 raise ValueError("DocTestFinder.find: __test__ values "
906 "must be strings, functions, methods, "
907 "classes, or modules: %r" %
909 valname
= '%s.__test__.%s' % (name
, valname
)
910 self
._find
(tests
, val
, valname
, module
, source_lines
,
913 # Look for tests in a class's contained objects.
914 if inspect
.isclass(obj
) and self
._recurse
:
915 for valname
, val
in obj
.__dict
__.items():
916 # Special handling for staticmethod/classmethod.
917 if isinstance(val
, staticmethod):
918 val
= getattr(obj
, valname
)
919 if isinstance(val
, classmethod):
920 val
= getattr(obj
, valname
).im_func
922 # Recurse to methods, properties, and nested classes.
923 if ((inspect
.isfunction(val
) or inspect
.isclass(val
) or
924 isinstance(val
, property)) and
925 self
._from
_module
(module
, val
)):
926 valname
= '%s.%s' % (name
, valname
)
927 self
._find
(tests
, val
, valname
, module
, source_lines
,
930 def _get_test(self
, obj
, name
, module
, globs
, source_lines
):
932 Return a DocTest for the given object, if it defines a docstring;
933 otherwise, return None.
935 # Extract the object's docstring. If it doesn't have one,
936 # then return None (no test for this object).
937 if isinstance(obj
, basestring
):
941 if obj
.__doc
__ is None:
944 docstring
= obj
.__doc
__
945 if not isinstance(docstring
, basestring
):
946 docstring
= str(docstring
)
947 except (TypeError, AttributeError):
950 # Find the docstring's location in the file.
951 lineno
= self
._find
_lineno
(obj
, source_lines
)
953 # Don't bother if the docstring is empty.
954 if self
._exclude
_empty
and not docstring
:
957 # Return a DocTest for this object.
961 filename
= getattr(module
, '__file__', module
.__name
__)
962 if filename
[-4:] in (".pyc", ".pyo"):
963 filename
= filename
[:-1]
964 return self
._parser
.get_doctest(docstring
, globs
, name
,
967 def _find_lineno(self
, obj
, source_lines
):
969 Return a line number of the given object's docstring. Note:
970 this method assumes that the object has a docstring.
974 # Find the line number for modules.
975 if inspect
.ismodule(obj
):
978 # Find the line number for classes.
979 # Note: this could be fooled if a class is defined multiple
980 # times in a single file.
981 if inspect
.isclass(obj
):
982 if source_lines
is None:
984 pat
= re
.compile(r
'^\s*class\s*%s\b' %
985 getattr(obj
, '__name__', '-'))
986 for i
, line
in enumerate(source_lines
):
991 # Find the line number for functions & methods.
992 if inspect
.ismethod(obj
): obj
= obj
.im_func
993 if inspect
.isfunction(obj
): obj
= obj
.func_code
994 if inspect
.istraceback(obj
): obj
= obj
.tb_frame
995 if inspect
.isframe(obj
): obj
= obj
.f_code
996 if inspect
.iscode(obj
):
997 lineno
= getattr(obj
, 'co_firstlineno', None)-1
999 # Find the line number where the docstring starts. Assume
1000 # that it's the first line that begins with a quote mark.
1001 # Note: this could be fooled by a multiline function
1002 # signature, where a continuation line begins with a quote
1004 if lineno
is not None:
1005 if source_lines
is None:
1007 pat
= re
.compile('(^|.*:)\s*\w*("|\')')
1008 for lineno
in range(lineno
, len(source_lines
)):
1009 if pat
.match(source_lines
[lineno
]):
1012 # We couldn't find the line number.
1015 ######################################################################
1016 ## 5. DocTest Runner
1017 ######################################################################
1019 class DocTestRunner
:
1021 A class used to run DocTest test cases, and accumulate statistics.
1022 The `run` method is used to process a single DocTest case. It
1023 returns a tuple `(f, t)`, where `t` is the number of test cases
1024 tried, and `f` is the number of test cases that failed.
1026 >>> tests = DocTestFinder().find(_TestClass)
1027 >>> runner = DocTestRunner(verbose=False)
1028 >>> tests.sort(key = lambda test: test.name)
1029 >>> for test in tests:
1030 ... print test.name, '->', runner.run(test)
1031 _TestClass -> (0, 2)
1032 _TestClass.__init__ -> (0, 2)
1033 _TestClass.get -> (0, 2)
1034 _TestClass.square -> (0, 1)
1036 The `summarize` method prints a summary of all the test cases that
1037 have been run by the runner, and returns an aggregated `(f, t)`
1040 >>> runner.summarize(verbose=1)
1041 4 items passed all tests:
1042 2 tests in _TestClass
1043 2 tests in _TestClass.__init__
1044 2 tests in _TestClass.get
1045 1 tests in _TestClass.square
1047 7 passed and 0 failed.
1051 The aggregated number of tried examples and failed examples is
1052 also available via the `tries` and `failures` attributes:
1059 The comparison between expected outputs and actual outputs is done
1060 by an `OutputChecker`. This comparison may be customized with a
1061 number of option flags; see the documentation for `testmod` for
1062 more information. If the option flags are insufficient, then the
1063 comparison may also be customized by passing a subclass of
1064 `OutputChecker` to the constructor.
1066 The test runner's display output can be controlled in two ways.
1067 First, an output function (`out) can be passed to
1068 `TestRunner.run`; this function will be called with strings that
1069 should be displayed. It defaults to `sys.stdout.write`. If
1070 capturing the output is not sufficient, then the display output
1071 can be also customized by subclassing DocTestRunner, and
1072 overriding the methods `report_start`, `report_success`,
1073 `report_unexpected_exception`, and `report_failure`.
1075 # This divider string is used to separate failure messages, and to
1076 # separate sections of the summary.
1079 def __init__(self
, checker
=None, verbose
=None, optionflags
=0):
1081 Create a new test runner.
1083 Optional keyword arg `checker` is the `OutputChecker` that
1084 should be used to compare the expected outputs and actual
1085 outputs of doctest examples.
1087 Optional keyword arg 'verbose' prints lots of stuff if true,
1088 only failures if false; by default, it's true iff '-v' is in
1091 Optional argument `optionflags` can be used to control how the
1092 test runner compares expected output to actual output, and how
1093 it displays failures. See the documentation for `testmod` for
1096 self
._checker
= checker
or OutputChecker()
1098 verbose
= '-v' in sys
.argv
1099 self
._verbose
= verbose
1100 self
.optionflags
= optionflags
1101 self
.original_optionflags
= optionflags
1103 # Keep track of the examples we've run.
1108 # Create a fake output target for capturing doctest output.
1109 self
._fakeout
= _SpoofOut()
1111 #/////////////////////////////////////////////////////////////////
1113 #/////////////////////////////////////////////////////////////////
1115 def report_start(self
, out
, test
, example
):
1117 Report that the test runner is about to process the given
1118 example. (Only displays a message if verbose=True)
1122 out('Trying:\n' + _indent(example
.source
) +
1123 'Expecting:\n' + _indent(example
.want
))
1125 out('Trying:\n' + _indent(example
.source
) +
1126 'Expecting nothing\n')
1128 def report_success(self
, out
, test
, example
, got
):
1130 Report that the given example ran successfully. (Only
1131 displays a message if verbose=True)
1136 def report_failure(self
, out
, test
, example
, got
):
1138 Report that the given example failed.
1140 out(self
._failure
_header
(test
, example
) +
1141 self
._checker
.output_difference(example
, got
, self
.optionflags
))
1143 def report_unexpected_exception(self
, out
, test
, example
, exc_info
):
1145 Report that the given example raised an unexpected exception.
1147 out(self
._failure
_header
(test
, example
) +
1148 'Exception raised:\n' + _indent(_exception_traceback(exc_info
)))
1150 def _failure_header(self
, test
, example
):
1151 out
= [self
.DIVIDER
]
1153 if test
.lineno
is not None and example
.lineno
is not None:
1154 lineno
= test
.lineno
+ example
.lineno
+ 1
1157 out
.append('File "%s", line %s, in %s' %
1158 (test
.filename
, lineno
, test
.name
))
1160 out
.append('Line %s, in %s' % (example
.lineno
+1, test
.name
))
1161 out
.append('Failed example:')
1162 source
= example
.source
1163 out
.append(_indent(source
))
1164 return '\n'.join(out
)
1166 #/////////////////////////////////////////////////////////////////
1168 #/////////////////////////////////////////////////////////////////
1170 def __run(self
, test
, compileflags
, out
):
1172 Run the examples in `test`. Write the outcome of each example
1173 with one of the `DocTestRunner.report_*` methods, using the
1174 writer function `out`. `compileflags` is the set of compiler
1175 flags that should be used to execute examples. Return a tuple
1176 `(f, t)`, where `t` is the number of examples tried, and `f`
1177 is the number of examples that failed. The examples are run
1178 in the namespace `test.globs`.
1180 # Keep track of the number of failures and tries.
1181 failures
= tries
= 0
1183 # Save the option flags (since option directives can be used
1185 original_optionflags
= self
.optionflags
1187 SUCCESS
, FAILURE
, BOOM
= range(3) # `outcome` state
1189 check
= self
._checker
.check_output
1191 # Process each example.
1192 for examplenum
, example
in enumerate(test
.examples
):
1194 # If REPORT_ONLY_FIRST_FAILURE is set, then supress
1195 # reporting after the first failure.
1196 quiet
= (self
.optionflags
& REPORT_ONLY_FIRST_FAILURE
and
1199 # Merge in the example's options.
1200 self
.optionflags
= original_optionflags
1202 for (optionflag
, val
) in example
.options
.items():
1204 self
.optionflags |
= optionflag
1206 self
.optionflags
&= ~optionflag
1208 # If 'SKIP' is set, then skip this example.
1209 if self
.optionflags
& SKIP
:
1212 # Record that we started this example.
1215 self
.report_start(out
, test
, example
)
1217 # Use a special filename for compile(), so we can retrieve
1218 # the source code during interactive debugging (see
1219 # __patched_linecache_getlines).
1220 filename
= '<doctest %s[%d]>' % (test
.name
, examplenum
)
1222 # Run the example in the given context (globs), and record
1223 # any exception that gets raised. (But don't intercept
1224 # keyboard interrupts.)
1226 # Don't blink! This is where the user's code gets run.
1227 exec compile(example
.source
, filename
, "single",
1228 compileflags
, 1) in test
.globs
1229 self
.debugger
.set_continue() # ==== Example Finished ====
1231 except KeyboardInterrupt:
1234 exception
= sys
.exc_info()
1235 self
.debugger
.set_continue() # ==== Example Finished ====
1237 got
= self
._fakeout
.getvalue() # the actual output
1238 self
._fakeout
.truncate(0)
1239 outcome
= FAILURE
# guilty until proved innocent or insane
1241 # If the example executed without raising any exceptions,
1242 # verify its output.
1243 if exception
is None:
1244 if check(example
.want
, got
, self
.optionflags
):
1247 # The example raised an exception: check if it was expected.
1249 exc_info
= sys
.exc_info()
1250 exc_msg
= traceback
.format_exception_only(*exc_info
[:2])[-1]
1252 got
+= _exception_traceback(exc_info
)
1254 # If `example.exc_msg` is None, then we weren't expecting
1256 if example
.exc_msg
is None:
1259 # We expected an exception: see whether it matches.
1260 elif check(example
.exc_msg
, exc_msg
, self
.optionflags
):
1263 # Another chance if they didn't care about the detail.
1264 elif self
.optionflags
& IGNORE_EXCEPTION_DETAIL
:
1265 m1
= re
.match(r
'[^:]*:', example
.exc_msg
)
1266 m2
= re
.match(r
'[^:]*:', exc_msg
)
1267 if m1
and m2
and check(m1
.group(0), m2
.group(0),
1271 # Report the outcome.
1272 if outcome
is SUCCESS
:
1274 self
.report_success(out
, test
, example
, got
)
1275 elif outcome
is FAILURE
:
1277 self
.report_failure(out
, test
, example
, got
)
1279 elif outcome
is BOOM
:
1281 self
.report_unexpected_exception(out
, test
, example
,
1285 assert False, ("unknown outcome", outcome
)
1287 # Restore the option flags (in case they were modified)
1288 self
.optionflags
= original_optionflags
1290 # Record and return the number of failures and tries.
1291 self
.__record
_outcome
(test
, failures
, tries
)
1292 return failures
, tries
1294 def __record_outcome(self
, test
, f
, t
):
1296 Record the fact that the given DocTest (`test`) generated `f`
1297 failures out of `t` tried examples.
1299 f2
, t2
= self
._name
2ft
.get(test
.name
, (0,0))
1300 self
._name
2ft
[test
.name
] = (f
+f2
, t
+t2
)
1304 __LINECACHE_FILENAME_RE
= re
.compile(r
'<doctest '
1305 r
'(?P<name>[\w\.]+)'
1306 r
'\[(?P<examplenum>\d+)\]>$')
1307 def __patched_linecache_getlines(self
, filename
, module_globals
=None):
1308 m
= self
.__LINECACHE
_FILENAME
_RE
.match(filename
)
1309 if m
and m
.group('name') == self
.test
.name
:
1310 example
= self
.test
.examples
[int(m
.group('examplenum'))]
1311 return example
.source
.splitlines(True)
1313 return self
.save_linecache_getlines(filename
, module_globals
)
1315 def run(self
, test
, compileflags
=None, out
=None, clear_globs
=True):
1317 Run the examples in `test`, and display the results using the
1318 writer function `out`.
1320 The examples are run in the namespace `test.globs`. If
1321 `clear_globs` is true (the default), then this namespace will
1322 be cleared after the test runs, to help with garbage
1323 collection. If you would like to examine the namespace after
1324 the test completes, then use `clear_globs=False`.
1326 `compileflags` gives the set of flags that should be used by
1327 the Python compiler when running the examples. If not
1328 specified, then it will default to the set of future-import
1329 flags that apply to `globs`.
1331 The output of each example is checked using
1332 `DocTestRunner.check_output`, and the results are formatted by
1333 the `DocTestRunner.report_*` methods.
1337 if compileflags
is None:
1338 compileflags
= _extract_future_flags(test
.globs
)
1340 save_stdout
= sys
.stdout
1342 out
= save_stdout
.write
1343 sys
.stdout
= self
._fakeout
1345 # Patch pdb.set_trace to restore sys.stdout during interactive
1346 # debugging (so it's not still redirected to self._fakeout).
1347 # Note that the interactive output will go to *our*
1348 # save_stdout, even if that's not the real sys.stdout; this
1349 # allows us to write test cases for the set_trace behavior.
1350 save_set_trace
= pdb
.set_trace
1351 self
.debugger
= _OutputRedirectingPdb(save_stdout
)
1352 self
.debugger
.reset()
1353 pdb
.set_trace
= self
.debugger
.set_trace
1355 # Patch linecache.getlines, so we can see the example's source
1356 # when we're inside the debugger.
1357 self
.save_linecache_getlines
= linecache
.getlines
1358 linecache
.getlines
= self
.__patched
_linecache
_getlines
1361 return self
.__run
(test
, compileflags
, out
)
1363 sys
.stdout
= save_stdout
1364 pdb
.set_trace
= save_set_trace
1365 linecache
.getlines
= self
.save_linecache_getlines
1369 #/////////////////////////////////////////////////////////////////
1371 #/////////////////////////////////////////////////////////////////
1372 def summarize(self
, verbose
=None):
1374 Print a summary of all the test cases that have been run by
1375 this DocTestRunner, and return a tuple `(f, t)`, where `f` is
1376 the total number of failed examples, and `t` is the total
1377 number of tried examples.
1379 The optional `verbose` argument controls how detailed the
1380 summary is. If the verbosity is not specified, then the
1381 DocTestRunner's verbosity is used.
1384 verbose
= self
._verbose
1389 for x
in self
._name
2ft
.items():
1395 notests
.append(name
)
1397 passed
.append( (name
, t
) )
1402 print len(notests
), "items had no tests:"
1404 for thing
in notests
:
1407 print len(passed
), "items passed all tests:"
1409 for thing
, count
in passed
:
1410 print " %3d tests in %s" % (count
, thing
)
1413 print len(failed
), "items had failures:"
1415 for thing
, (f
, t
) in failed
:
1416 print " %3d of %3d in %s" % (f
, t
, thing
)
1418 print totalt
, "tests in", len(self
._name
2ft
), "items."
1419 print totalt
- totalf
, "passed and", totalf
, "failed."
1421 print "***Test Failed***", totalf
, "failures."
1423 print "Test passed."
1424 return totalf
, totalt
1426 #/////////////////////////////////////////////////////////////////
1427 # Backward compatibility cruft to maintain doctest.master.
1428 #/////////////////////////////////////////////////////////////////
1429 def merge(self
, other
):
1431 for name
, (f
, t
) in other
._name
2ft
.items():
1433 print "*** DocTestRunner.merge: '" + name
+ "' in both" \
1434 " testers; summing outcomes."
1440 class OutputChecker
:
1442 A class used to check the whether the actual output from a doctest
1443 example matches the expected output. `OutputChecker` defines two
1444 methods: `check_output`, which compares a given pair of outputs,
1445 and returns true if they match; and `output_difference`, which
1446 returns a string describing the differences between two outputs.
1448 def check_output(self
, want
, got
, optionflags
):
1450 Return True iff the actual output from an example (`got`)
1451 matches the expected output (`want`). These strings are
1452 always considered to match if they are identical; but
1453 depending on what option flags the test runner is using,
1454 several non-exact match types are also possible. See the
1455 documentation for `TestRunner` for more information about
1458 # Handle the common case first, for efficiency:
1459 # if they're string-identical, always return true.
1463 # The values True and False replaced 1 and 0 as the return
1464 # value for boolean comparisons in Python 2.3.
1465 if not (optionflags
& DONT_ACCEPT_TRUE_FOR_1
):
1466 if (got
,want
) == ("True\n", "1\n"):
1468 if (got
,want
) == ("False\n", "0\n"):
1471 # <BLANKLINE> can be used as a special sequence to signify a
1472 # blank line, unless the DONT_ACCEPT_BLANKLINE flag is used.
1473 if not (optionflags
& DONT_ACCEPT_BLANKLINE
):
1474 # Replace <BLANKLINE> in want with a blank line.
1475 want
= re
.sub('(?m)^%s\s*?$' % re
.escape(BLANKLINE_MARKER
),
1477 # If a line in got contains only spaces, then remove the
1479 got
= re
.sub('(?m)^\s*?$', '', got
)
1483 # This flag causes doctest to ignore any differences in the
1484 # contents of whitespace strings. Note that this can be used
1485 # in conjunction with the ELLIPSIS flag.
1486 if optionflags
& NORMALIZE_WHITESPACE
:
1487 got
= ' '.join(got
.split())
1488 want
= ' '.join(want
.split())
1492 # The ELLIPSIS flag says to let the sequence "..." in `want`
1493 # match any substring in `got`.
1494 if optionflags
& ELLIPSIS
:
1495 if _ellipsis_match(want
, got
):
1498 # We didn't find any match; return false.
1501 # Should we do a fancy diff?
1502 def _do_a_fancy_diff(self
, want
, got
, optionflags
):
1503 # Not unless they asked for a fancy diff.
1504 if not optionflags
& (REPORT_UDIFF |
1509 # If expected output uses ellipsis, a meaningful fancy diff is
1510 # too hard ... or maybe not. In two real-life failures Tim saw,
1511 # a diff was a major help anyway, so this is commented out.
1512 # [todo] _ellipsis_match() knows which pieces do and don't match,
1513 # and could be the basis for a kick-ass diff in this case.
1514 ##if optionflags & ELLIPSIS and ELLIPSIS_MARKER in want:
1517 # ndiff does intraline difference marking, so can be useful even
1518 # for 1-line differences.
1519 if optionflags
& REPORT_NDIFF
:
1522 # The other diff types need at least a few lines to be helpful.
1523 return want
.count('\n') > 2 and got
.count('\n') > 2
1525 def output_difference(self
, example
, got
, optionflags
):
1527 Return a string describing the differences between the
1528 expected output for a given example (`example`) and the actual
1529 output (`got`). `optionflags` is the set of option flags used
1530 to compare `want` and `got`.
1533 # If <BLANKLINE>s are being used, then replace blank lines
1534 # with <BLANKLINE> in the actual output string.
1535 if not (optionflags
& DONT_ACCEPT_BLANKLINE
):
1536 got
= re
.sub('(?m)^[ ]*(?=\n)', BLANKLINE_MARKER
, got
)
1538 # Check if we should use diff.
1539 if self
._do
_a
_fancy
_diff
(want
, got
, optionflags
):
1540 # Split want & got into lines.
1541 want_lines
= want
.splitlines(True) # True == keep line ends
1542 got_lines
= got
.splitlines(True)
1543 # Use difflib to find their differences.
1544 if optionflags
& REPORT_UDIFF
:
1545 diff
= difflib
.unified_diff(want_lines
, got_lines
, n
=2)
1546 diff
= list(diff
)[2:] # strip the diff header
1547 kind
= 'unified diff with -expected +actual'
1548 elif optionflags
& REPORT_CDIFF
:
1549 diff
= difflib
.context_diff(want_lines
, got_lines
, n
=2)
1550 diff
= list(diff
)[2:] # strip the diff header
1551 kind
= 'context diff with expected followed by actual'
1552 elif optionflags
& REPORT_NDIFF
:
1553 engine
= difflib
.Differ(charjunk
=difflib
.IS_CHARACTER_JUNK
)
1554 diff
= list(engine
.compare(want_lines
, got_lines
))
1555 kind
= 'ndiff with -expected +actual'
1557 assert 0, 'Bad diff option'
1558 # Remove trailing whitespace on diff output.
1559 diff
= [line
.rstrip() + '\n' for line
in diff
]
1560 return 'Differences (%s):\n' % kind
+ _indent(''.join(diff
))
1562 # If we're not using diff, then simply list the expected
1563 # output followed by the actual output.
1565 return 'Expected:\n%sGot:\n%s' % (_indent(want
), _indent(got
))
1567 return 'Expected:\n%sGot nothing\n' % _indent(want
)
1569 return 'Expected nothing\nGot:\n%s' % _indent(got
)
1571 return 'Expected nothing\nGot nothing\n'
1573 class DocTestFailure(Exception):
1574 """A DocTest example has failed in debugging mode.
1576 The exception instance has variables:
1578 - test: the DocTest object being run
1580 - example: the Example object that failed
1582 - got: the actual output
1584 def __init__(self
, test
, example
, got
):
1586 self
.example
= example
1590 return str(self
.test
)
1592 class UnexpectedException(Exception):
1593 """A DocTest example has encountered an unexpected exception
1595 The exception instance has variables:
1597 - test: the DocTest object being run
1599 - example: the Example object that failed
1601 - exc_info: the exception info
1603 def __init__(self
, test
, example
, exc_info
):
1605 self
.example
= example
1606 self
.exc_info
= exc_info
1609 return str(self
.test
)
1611 class DebugRunner(DocTestRunner
):
1612 r
"""Run doc tests but raise an exception as soon as there is a failure.
1614 If an unexpected exception occurs, an UnexpectedException is raised.
1615 It contains the test, the example, and the original exception:
1617 >>> runner = DebugRunner(verbose=False)
1618 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
1619 ... {}, 'foo', 'foo.py', 0)
1621 ... runner.run(test)
1622 ... except UnexpectedException, failure:
1625 >>> failure.test is test
1628 >>> failure.example.want
1631 >>> exc_info = failure.exc_info
1632 >>> raise exc_info[0], exc_info[1], exc_info[2]
1633 Traceback (most recent call last):
1637 We wrap the original exception to give the calling application
1638 access to the test and example information.
1640 If the output doesn't match, then a DocTestFailure is raised:
1642 >>> test = DocTestParser().get_doctest('''
1646 ... ''', {}, 'foo', 'foo.py', 0)
1649 ... runner.run(test)
1650 ... except DocTestFailure, failure:
1653 DocTestFailure objects provide access to the test:
1655 >>> failure.test is test
1658 As well as to the example:
1660 >>> failure.example.want
1663 and the actual output:
1668 If a failure or error occurs, the globals are left intact:
1670 >>> del test.globs['__builtins__']
1674 >>> test = DocTestParser().get_doctest('''
1676 ... >>> raise KeyError
1677 ... ''', {}, 'foo', 'foo.py', 0)
1679 >>> runner.run(test)
1680 Traceback (most recent call last):
1682 UnexpectedException: <DocTest foo from foo.py:0 (2 examples)>
1684 >>> del test.globs['__builtins__']
1688 But the globals are cleared if there is no error:
1690 >>> test = DocTestParser().get_doctest('''
1692 ... ''', {}, 'foo', 'foo.py', 0)
1694 >>> runner.run(test)
1702 def run(self
, test
, compileflags
=None, out
=None, clear_globs
=True):
1703 r
= DocTestRunner
.run(self
, test
, compileflags
, out
, False)
1708 def report_unexpected_exception(self
, out
, test
, example
, exc_info
):
1709 raise UnexpectedException(test
, example
, exc_info
)
1711 def report_failure(self
, out
, test
, example
, got
):
1712 raise DocTestFailure(test
, example
, got
)
1714 ######################################################################
1715 ## 6. Test Functions
1716 ######################################################################
1717 # These should be backwards compatible.
1719 # For backward compatibility, a global instance of a DocTestRunner
1720 # class, updated by testmod.
1723 def testmod(m
=None, name
=None, globs
=None, verbose
=None,
1724 report
=True, optionflags
=0, extraglobs
=None,
1725 raise_on_error
=False, exclude_empty
=False):
1726 """m=None, name=None, globs=None, verbose=None, report=True,
1727 optionflags=0, extraglobs=None, raise_on_error=False,
1730 Test examples in docstrings in functions and classes reachable
1731 from module m (or the current module if m is not supplied), starting
1734 Also test examples reachable from dict m.__test__ if it exists and is
1735 not None. m.__test__ maps names to functions, classes and strings;
1736 function and class docstrings are tested even if the name is private;
1737 strings are tested directly, as if they were docstrings.
1739 Return (#failures, #tests).
1741 See doctest.__doc__ for an overview.
1743 Optional keyword arg "name" gives the name of the module; by default
1746 Optional keyword arg "globs" gives a dict to be used as the globals
1747 when executing examples; by default, use m.__dict__. A copy of this
1748 dict is actually used for each docstring, so that each docstring's
1749 examples start with a clean slate.
1751 Optional keyword arg "extraglobs" gives a dictionary that should be
1752 merged into the globals that are used to execute examples. By
1753 default, no extra globals are used. This is new in 2.4.
1755 Optional keyword arg "verbose" prints lots of stuff if true, prints
1756 only failures if false; by default, it's true iff "-v" is in sys.argv.
1758 Optional keyword arg "report" prints a summary at the end when true,
1759 else prints nothing at the end. In verbose mode, the summary is
1760 detailed, else very brief (in fact, empty if all tests passed).
1762 Optional keyword arg "optionflags" or's together module constants,
1763 and defaults to 0. This is new in 2.3. Possible values (see the
1766 DONT_ACCEPT_TRUE_FOR_1
1767 DONT_ACCEPT_BLANKLINE
1768 NORMALIZE_WHITESPACE
1771 IGNORE_EXCEPTION_DETAIL
1775 REPORT_ONLY_FIRST_FAILURE
1777 Optional keyword arg "raise_on_error" raises an exception on the
1778 first unexpected exception or failure. This allows failures to be
1779 post-mortem debugged.
1781 Advanced tomfoolery: testmod runs methods of a local instance of
1782 class doctest.Tester, then merges the results into (or creates)
1783 global Tester instance doctest.master. Methods of doctest.master
1784 can be called directly too, if you want to do something unusual.
1785 Passing report=0 to testmod is especially useful then, to delay
1786 displaying a summary. Invoke doctest.master.summarize(verbose)
1787 when you're done fiddling.
1791 # If no module was given, then use __main__.
1793 # DWA - m will still be None if this wasn't invoked from the command
1794 # line, in which case the following TypeError is about as good an error
1795 # as we should expect
1796 m
= sys
.modules
.get('__main__')
1798 # Check that we were actually given a module.
1799 if not inspect
.ismodule(m
):
1800 raise TypeError("testmod: module required; %r" % (m
,))
1802 # If no name was given, then use the module's name.
1806 # Find, parse, and run all tests in the given module.
1807 finder
= DocTestFinder(exclude_empty
=exclude_empty
)
1810 runner
= DebugRunner(verbose
=verbose
, optionflags
=optionflags
)
1812 runner
= DocTestRunner(verbose
=verbose
, optionflags
=optionflags
)
1814 for test
in finder
.find(m
, name
, globs
=globs
, extraglobs
=extraglobs
):
1823 master
.merge(runner
)
1825 return runner
.failures
, runner
.tries
1827 def testfile(filename
, module_relative
=True, name
=None, package
=None,
1828 globs
=None, verbose
=None, report
=True, optionflags
=0,
1829 extraglobs
=None, raise_on_error
=False, parser
=DocTestParser(),
1832 Test examples in the given file. Return (#failures, #tests).
1834 Optional keyword arg "module_relative" specifies how filenames
1835 should be interpreted:
1837 - If "module_relative" is True (the default), then "filename"
1838 specifies a module-relative path. By default, this path is
1839 relative to the calling module's directory; but if the
1840 "package" argument is specified, then it is relative to that
1841 package. To ensure os-independence, "filename" should use
1842 "/" characters to separate path segments, and should not
1843 be an absolute path (i.e., it may not begin with "/").
1845 - If "module_relative" is False, then "filename" specifies an
1846 os-specific path. The path may be absolute or relative (to
1847 the current working directory).
1849 Optional keyword arg "name" gives the name of the test; by default
1850 use the file's basename.
1852 Optional keyword argument "package" is a Python package or the
1853 name of a Python package whose directory should be used as the
1854 base directory for a module relative filename. If no package is
1855 specified, then the calling module's directory is used as the base
1856 directory for module relative filenames. It is an error to
1857 specify "package" if "module_relative" is False.
1859 Optional keyword arg "globs" gives a dict to be used as the globals
1860 when executing examples; by default, use {}. A copy of this dict
1861 is actually used for each docstring, so that each docstring's
1862 examples start with a clean slate.
1864 Optional keyword arg "extraglobs" gives a dictionary that should be
1865 merged into the globals that are used to execute examples. By
1866 default, no extra globals are used.
1868 Optional keyword arg "verbose" prints lots of stuff if true, prints
1869 only failures if false; by default, it's true iff "-v" is in sys.argv.
1871 Optional keyword arg "report" prints a summary at the end when true,
1872 else prints nothing at the end. In verbose mode, the summary is
1873 detailed, else very brief (in fact, empty if all tests passed).
1875 Optional keyword arg "optionflags" or's together module constants,
1876 and defaults to 0. Possible values (see the docs for details):
1878 DONT_ACCEPT_TRUE_FOR_1
1879 DONT_ACCEPT_BLANKLINE
1880 NORMALIZE_WHITESPACE
1883 IGNORE_EXCEPTION_DETAIL
1887 REPORT_ONLY_FIRST_FAILURE
1889 Optional keyword arg "raise_on_error" raises an exception on the
1890 first unexpected exception or failure. This allows failures to be
1891 post-mortem debugged.
1893 Optional keyword arg "parser" specifies a DocTestParser (or
1894 subclass) that should be used to extract tests from the files.
1896 Optional keyword arg "encoding" specifies an encoding that should
1897 be used to convert the file to unicode.
1899 Advanced tomfoolery: testmod runs methods of a local instance of
1900 class doctest.Tester, then merges the results into (or creates)
1901 global Tester instance doctest.master. Methods of doctest.master
1902 can be called directly too, if you want to do something unusual.
1903 Passing report=0 to testmod is especially useful then, to delay
1904 displaying a summary. Invoke doctest.master.summarize(verbose)
1905 when you're done fiddling.
1909 if package
and not module_relative
:
1910 raise ValueError("Package may only be specified for module-"
1913 # Relativize the path
1914 text
, filename
= _load_testfile(filename
, package
, module_relative
)
1916 # If no name was given, then use the file's name.
1918 name
= os
.path
.basename(filename
)
1920 # Assemble the globals.
1924 globs
= globs
.copy()
1925 if extraglobs
is not None:
1926 globs
.update(extraglobs
)
1929 runner
= DebugRunner(verbose
=verbose
, optionflags
=optionflags
)
1931 runner
= DocTestRunner(verbose
=verbose
, optionflags
=optionflags
)
1933 if encoding
is not None:
1934 text
= text
.decode(encoding
)
1936 # Read the file, convert it to a test, and run it.
1937 test
= parser
.get_doctest(text
, globs
, name
, filename
, 0)
1946 master
.merge(runner
)
1948 return runner
.failures
, runner
.tries
1950 def run_docstring_examples(f
, globs
, verbose
=False, name
="NoName",
1951 compileflags
=None, optionflags
=0):
1953 Test examples in the given object's docstring (`f`), using `globs`
1954 as globals. Optional argument `name` is used in failure messages.
1955 If the optional argument `verbose` is true, then generate output
1956 even if there are no failures.
1958 `compileflags` gives the set of flags that should be used by the
1959 Python compiler when running the examples. If not specified, then
1960 it will default to the set of future-import flags that apply to
1963 Optional keyword arg `optionflags` specifies options for the
1964 testing and output. See the documentation for `testmod` for more
1967 # Find, parse, and run all tests in the given module.
1968 finder
= DocTestFinder(verbose
=verbose
, recurse
=False)
1969 runner
= DocTestRunner(verbose
=verbose
, optionflags
=optionflags
)
1970 for test
in finder
.find(f
, name
, globs
=globs
):
1971 runner
.run(test
, compileflags
=compileflags
)
1973 ######################################################################
1975 ######################################################################
1976 # This is provided only for backwards compatibility. It's not
1977 # actually used in any way.
1980 def __init__(self
, mod
=None, globs
=None, verbose
=None, optionflags
=0):
1982 warnings
.warn("class Tester is deprecated; "
1983 "use class doctest.DocTestRunner instead",
1984 DeprecationWarning, stacklevel
=2)
1985 if mod
is None and globs
is None:
1986 raise TypeError("Tester.__init__: must specify mod or globs")
1987 if mod
is not None and not inspect
.ismodule(mod
):
1988 raise TypeError("Tester.__init__: mod must be a module; %r" %
1991 globs
= mod
.__dict
__
1994 self
.verbose
= verbose
1995 self
.optionflags
= optionflags
1996 self
.testfinder
= DocTestFinder()
1997 self
.testrunner
= DocTestRunner(verbose
=verbose
,
1998 optionflags
=optionflags
)
2000 def runstring(self
, s
, name
):
2001 test
= DocTestParser().get_doctest(s
, self
.globs
, name
, None, None)
2003 print "Running string", name
2004 (f
,t
) = self
.testrunner
.run(test
)
2006 print f
, "of", t
, "examples failed in string", name
2009 def rundoc(self
, object, name
=None, module
=None):
2011 tests
= self
.testfinder
.find(object, name
, module
=module
,
2014 (f2
, t2
) = self
.testrunner
.run(test
)
2015 (f
,t
) = (f
+f2
, t
+t2
)
2018 def rundict(self
, d
, name
, module
=None):
2020 m
= types
.ModuleType(name
)
2021 m
.__dict
__.update(d
)
2024 return self
.rundoc(m
, name
, module
)
2026 def run__test__(self
, d
, name
):
2028 m
= types
.ModuleType(name
)
2030 return self
.rundoc(m
, name
)
2032 def summarize(self
, verbose
=None):
2033 return self
.testrunner
.summarize(verbose
)
2035 def merge(self
, other
):
2036 self
.testrunner
.merge(other
.testrunner
)
2038 ######################################################################
2039 ## 8. Unittest Support
2040 ######################################################################
2042 _unittest_reportflags
= 0
2044 def set_unittest_reportflags(flags
):
2045 """Sets the unittest option flags.
2047 The old flag is returned so that a runner could restore the old
2048 value if it wished to:
2051 >>> old = doctest._unittest_reportflags
2052 >>> doctest.set_unittest_reportflags(REPORT_NDIFF |
2053 ... REPORT_ONLY_FIRST_FAILURE) == old
2056 >>> doctest._unittest_reportflags == (REPORT_NDIFF |
2057 ... REPORT_ONLY_FIRST_FAILURE)
2060 Only reporting flags can be set:
2062 >>> doctest.set_unittest_reportflags(ELLIPSIS)
2063 Traceback (most recent call last):
2065 ValueError: ('Only reporting flags allowed', 8)
2067 >>> doctest.set_unittest_reportflags(old) == (REPORT_NDIFF |
2068 ... REPORT_ONLY_FIRST_FAILURE)
2071 global _unittest_reportflags
2073 if (flags
& REPORTING_FLAGS
) != flags
:
2074 raise ValueError("Only reporting flags allowed", flags
)
2075 old
= _unittest_reportflags
2076 _unittest_reportflags
= flags
2080 class DocTestCase(unittest
.TestCase
):
2082 def __init__(self
, test
, optionflags
=0, setUp
=None, tearDown
=None,
2085 unittest
.TestCase
.__init
__(self
)
2086 self
._dt
_optionflags
= optionflags
2087 self
._dt
_checker
= checker
2088 self
._dt
_test
= test
2089 self
._dt
_setUp
= setUp
2090 self
._dt
_tearDown
= tearDown
2093 test
= self
._dt
_test
2095 if self
._dt
_setUp
is not None:
2096 self
._dt
_setUp
(test
)
2099 test
= self
._dt
_test
2101 if self
._dt
_tearDown
is not None:
2102 self
._dt
_tearDown
(test
)
2107 test
= self
._dt
_test
2110 optionflags
= self
._dt
_optionflags
2112 if not (optionflags
& REPORTING_FLAGS
):
2113 # The option flags don't include any reporting flags,
2114 # so add the default reporting flags
2115 optionflags |
= _unittest_reportflags
2117 runner
= DocTestRunner(optionflags
=optionflags
,
2118 checker
=self
._dt
_checker
, verbose
=False)
2121 runner
.DIVIDER
= "-"*70
2122 failures
, tries
= runner
.run(
2123 test
, out
=new
.write
, clear_globs
=False)
2128 raise self
.failureException(self
.format_failure(new
.getvalue()))
2130 def format_failure(self
, err
):
2131 test
= self
._dt
_test
2132 if test
.lineno
is None:
2133 lineno
= 'unknown line number'
2135 lineno
= '%s' % test
.lineno
2136 lname
= '.'.join(test
.name
.split('.')[-1:])
2137 return ('Failed doctest test for %s\n'
2138 ' File "%s", line %s, in %s\n\n%s'
2139 % (test
.name
, test
.filename
, lineno
, lname
, err
)
2143 r
"""Run the test case without results and without catching exceptions
2145 The unit test framework includes a debug method on test cases
2146 and test suites to support post-mortem debugging. The test code
2147 is run in such a way that errors are not caught. This way a
2148 caller can catch the errors and initiate post-mortem debugging.
2150 The DocTestCase provides a debug method that raises
2151 UnexpectedException errors if there is an unexepcted
2154 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
2155 ... {}, 'foo', 'foo.py', 0)
2156 >>> case = DocTestCase(test)
2159 ... except UnexpectedException, failure:
2162 The UnexpectedException contains the test, the example, and
2163 the original exception:
2165 >>> failure.test is test
2168 >>> failure.example.want
2171 >>> exc_info = failure.exc_info
2172 >>> raise exc_info[0], exc_info[1], exc_info[2]
2173 Traceback (most recent call last):
2177 If the output doesn't match, then a DocTestFailure is raised:
2179 >>> test = DocTestParser().get_doctest('''
2183 ... ''', {}, 'foo', 'foo.py', 0)
2184 >>> case = DocTestCase(test)
2188 ... except DocTestFailure, failure:
2191 DocTestFailure objects provide access to the test:
2193 >>> failure.test is test
2196 As well as to the example:
2198 >>> failure.example.want
2201 and the actual output:
2209 runner
= DebugRunner(optionflags
=self
._dt
_optionflags
,
2210 checker
=self
._dt
_checker
, verbose
=False)
2211 runner
.run(self
._dt
_test
)
2215 return self
._dt
_test
.name
2218 name
= self
._dt
_test
.name
.split('.')
2219 return "%s (%s)" % (name
[-1], '.'.join(name
[:-1]))
2223 def shortDescription(self
):
2224 return "Doctest: " + self
._dt
_test
.name
2226 def DocTestSuite(module
=None, globs
=None, extraglobs
=None, test_finder
=None,
2229 Convert doctest tests for a module to a unittest test suite.
2231 This converts each documentation string in a module that
2232 contains doctest tests to a unittest test case. If any of the
2233 tests in a doc string fail, then the test case fails. An exception
2234 is raised showing the name of the file containing the test and a
2235 (sometimes approximate) line number.
2237 The `module` argument provides the module to be tested. The argument
2238 can be either a module or a module name.
2240 If no argument is given, the calling module is used.
2242 A number of options may be provided as keyword arguments:
2245 A set-up function. This is called before running the
2246 tests in each file. The setUp function will be passed a DocTest
2247 object. The setUp function can access the test globals as the
2248 globs attribute of the test passed.
2251 A tear-down function. This is called after running the
2252 tests in each file. The tearDown function will be passed a DocTest
2253 object. The tearDown function can access the test globals as the
2254 globs attribute of the test passed.
2257 A dictionary containing initial global variables for the tests.
2260 A set of doctest option flags expressed as an integer.
2263 if test_finder
is None:
2264 test_finder
= DocTestFinder()
2266 module
= _normalize_module(module
)
2267 tests
= test_finder
.find(module
, globs
=globs
, extraglobs
=extraglobs
)
2269 globs
= module
.__dict
__
2271 # Why do we want to do this? Because it reveals a bug that might
2272 # otherwise be hidden.
2273 raise ValueError(module
, "has no tests")
2276 suite
= unittest
.TestSuite()
2278 if len(test
.examples
) == 0:
2280 if not test
.filename
:
2281 filename
= module
.__file
__
2282 if filename
[-4:] in (".pyc", ".pyo"):
2283 filename
= filename
[:-1]
2284 test
.filename
= filename
2285 suite
.addTest(DocTestCase(test
, **options
))
2289 class DocFileCase(DocTestCase
):
2292 return '_'.join(self
._dt
_test
.name
.split('.'))
2295 return self
._dt
_test
.filename
2298 def format_failure(self
, err
):
2299 return ('Failed doctest test for %s\n File "%s", line 0\n\n%s'
2300 % (self
._dt
_test
.name
, self
._dt
_test
.filename
, err
)
2303 def DocFileTest(path
, module_relative
=True, package
=None,
2304 globs
=None, parser
=DocTestParser(),
2305 encoding
=None, **options
):
2309 globs
= globs
.copy()
2311 if package
and not module_relative
:
2312 raise ValueError("Package may only be specified for module-"
2315 # Relativize the path.
2316 doc
, path
= _load_testfile(path
, package
, module_relative
)
2318 if "__file__" not in globs
:
2319 globs
["__file__"] = path
2321 # Find the file and read it.
2322 name
= os
.path
.basename(path
)
2324 # If an encoding is specified, use it to convert the file to unicode
2325 if encoding
is not None:
2326 doc
= doc
.decode(encoding
)
2328 # Convert it to a test, and wrap it in a DocFileCase.
2329 test
= parser
.get_doctest(doc
, globs
, name
, path
, 0)
2330 return DocFileCase(test
, **options
)
2332 def DocFileSuite(*paths
, **kw
):
2333 """A unittest suite for one or more doctest files.
2335 The path to each doctest file is given as a string; the
2336 interpretation of that string depends on the keyword argument
2339 A number of options may be provided as keyword arguments:
2342 If "module_relative" is True, then the given file paths are
2343 interpreted as os-independent module-relative paths. By
2344 default, these paths are relative to the calling module's
2345 directory; but if the "package" argument is specified, then
2346 they are relative to that package. To ensure os-independence,
2347 "filename" should use "/" characters to separate path
2348 segments, and may not be an absolute path (i.e., it may not
2351 If "module_relative" is False, then the given file paths are
2352 interpreted as os-specific paths. These paths may be absolute
2353 or relative (to the current working directory).
2356 A Python package or the name of a Python package whose directory
2357 should be used as the base directory for module relative paths.
2358 If "package" is not specified, then the calling module's
2359 directory is used as the base directory for module relative
2360 filenames. It is an error to specify "package" if
2361 "module_relative" is False.
2364 A set-up function. This is called before running the
2365 tests in each file. The setUp function will be passed a DocTest
2366 object. The setUp function can access the test globals as the
2367 globs attribute of the test passed.
2370 A tear-down function. This is called after running the
2371 tests in each file. The tearDown function will be passed a DocTest
2372 object. The tearDown function can access the test globals as the
2373 globs attribute of the test passed.
2376 A dictionary containing initial global variables for the tests.
2379 A set of doctest option flags expressed as an integer.
2382 A DocTestParser (or subclass) that should be used to extract
2383 tests from the files.
2386 An encoding that will be used to convert the files to unicode.
2388 suite
= unittest
.TestSuite()
2390 # We do this here so that _normalize_module is called at the right
2391 # level. If it were called in DocFileTest, then this function
2392 # would be the caller and we might guess the package incorrectly.
2393 if kw
.get('module_relative', True):
2394 kw
['package'] = _normalize_module(kw
.get('package'))
2397 suite
.addTest(DocFileTest(path
, **kw
))
2401 ######################################################################
2402 ## 9. Debugging Support
2403 ######################################################################
2405 def script_from_examples(s
):
2406 r
"""Extract script from text with examples.
2408 Converts text with examples to a Python script. Example input is
2409 converted to regular code. Example output and all other words
2410 are converted to comments:
2413 ... Here are examples of simple math.
2415 ... Python has super accurate integer addition
2420 ... And very friendly error messages:
2427 ... You can use logic if you want:
2437 >>> print script_from_examples(text)
2438 # Here are examples of simple math.
2440 # Python has super accurate integer addition
2446 # And very friendly error messages:
2454 # You can use logic if you want:
2464 for piece
in DocTestParser().parse(s
):
2465 if isinstance(piece
, Example
):
2466 # Add the example's source code (strip trailing NL)
2467 output
.append(piece
.source
[:-1])
2468 # Add the expected output:
2471 output
.append('# Expected:')
2472 output
+= ['## '+l
for l
in want
.split('\n')[:-1]]
2474 # Add non-example text.
2475 output
+= [_comment_line(l
)
2476 for l
in piece
.split('\n')[:-1]]
2478 # Trim junk on both ends.
2479 while output
and output
[-1] == '#':
2481 while output
and output
[0] == '#':
2483 # Combine the output, and return it.
2484 # Add a courtesy newline to prevent exec from choking (see bug #1172785)
2485 return '\n'.join(output
) + '\n'
2487 def testsource(module
, name
):
2488 """Extract the test sources from a doctest docstring as a script.
2490 Provide the module (or dotted name of the module) containing the
2491 test to be debugged and the name (within the module) of the object
2492 with the doc string with tests to be debugged.
2494 module
= _normalize_module(module
)
2495 tests
= DocTestFinder().find(module
)
2496 test
= [t
for t
in tests
if t
.name
== name
]
2498 raise ValueError(name
, "not found in tests")
2500 testsrc
= script_from_examples(test
.docstring
)
2503 def debug_src(src
, pm
=False, globs
=None):
2504 """Debug a single doctest docstring, in argument `src`'"""
2505 testsrc
= script_from_examples(src
)
2506 debug_script(testsrc
, pm
, globs
)
2508 def debug_script(src
, pm
=False, globs
=None):
2509 "Debug a test script. `src` is the script, as a string."
2512 # Note that tempfile.NameTemporaryFile() cannot be used. As the
2513 # docs say, a file so created cannot be opened by name a second time
2514 # on modern Windows boxes, and execfile() needs to open it.
2515 srcfilename
= tempfile
.mktemp(".py", "doctestdebug")
2516 f
= open(srcfilename
, 'w')
2522 globs
= globs
.copy()
2528 execfile(srcfilename
, globs
, globs
)
2530 print sys
.exc_info()[1]
2531 pdb
.post_mortem(sys
.exc_info()[2])
2533 # Note that %r is vital here. '%s' instead can, e.g., cause
2534 # backslashes to get treated as metacharacters on Windows.
2535 pdb
.run("execfile(%r)" % srcfilename
, globs
, globs
)
2538 os
.remove(srcfilename
)
2540 def debug(module
, name
, pm
=False):
2541 """Debug a single doctest docstring.
2543 Provide the module (or dotted name of the module) containing the
2544 test to be debugged and the name (within the module) of the object
2545 with the docstring with tests to be debugged.
2547 module
= _normalize_module(module
)
2548 testsrc
= testsource(module
, name
)
2549 debug_script(testsrc
, pm
, module
.__dict
__)
2551 ######################################################################
2552 ## 10. Example Usage
2553 ######################################################################
2556 A pointless class, for sanity-checking of docstring testing.
2562 >>> _TestClass(13).get() + _TestClass(-12).get()
2564 >>> hex(_TestClass(13).square().get())
2568 def __init__(self
, val
):
2569 """val -> _TestClass object with associated value val.
2571 >>> t = _TestClass(123)
2579 """square() -> square TestClass's associated value
2581 >>> _TestClass(13).square().get()
2585 self
.val
= self
.val
** 2
2589 """get() -> return TestClass's associated value.
2591 >>> x = _TestClass(-42)
2598 __test__
= {"_TestClass": _TestClass
,
2600 Example of a string object, searched as-is.
2606 "bool-int equivalence": r
"""
2607 In 2.2, boolean expressions displayed
2608 0 or 1. By default, we still accept
2609 them. This can be disabled by passing
2610 DONT_ACCEPT_TRUE_FOR_1 to the new
2611 optionflags argument.
2623 Blank lines can be marked with <BLANKLINE>:
2624 >>> print 'foo\n\nbar\n'
2632 If the ellipsis flag is used, then '...' can be used to
2633 elide substrings in the desired output:
2634 >>> print range(1000) #doctest: +ELLIPSIS
2638 "whitespace normalization": r
"""
2639 If the whitespace normalization flag is used, then
2640 differences in whitespace are ignored.
2641 >>> print range(30) #doctest: +NORMALIZE_WHITESPACE
2642 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
2643 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,
2649 testfiles
= [arg
for arg
in sys
.argv
[1:] if arg
and arg
[0] != '-']
2651 for filename
in testfiles
:
2652 if filename
.endswith(".py"):
2653 # It is a module -- insert its dir into sys.path and try to
2654 # import it. If it is part of a package, that possibly won't work
2655 # because of package imports.
2656 dirname
, filename
= os
.path
.split(filename
)
2657 sys
.path
.insert(0, dirname
)
2658 m
= __import__(filename
[:-3])
2660 failures
, _
= testmod(m
)
2662 failures
, _
= testfile(filename
, module_relative
=False)
2666 r
= unittest
.TextTestRunner()
2667 r
.run(DocTestSuite())
2670 if __name__
== "__main__":