2 # Released to the public domain 16-Jan-2001, by Tim Peters (tim@python.org).
3 # Major enhancements and refactoring by:
7 # Provided as-is; use at your own risk; no warranty; no promises; enjoy!
9 r
"""Module doctest -- a framework for running examples in docstrings.
11 In simplest use, end each module M to be tested with:
17 if __name__ == "__main__":
20 Then running the module as a script will cause the examples in the
21 docstrings to get executed and verified:
25 This won't display anything unless an example fails, in which case the
26 failing example(s) and the cause(s) of the failure(s) are printed to stdout
27 (why not stderr? because stderr is a lame hack <0.2 wink>), and the final
28 line of output is "Test failed.".
30 Run it with the -v switch instead:
34 and a detailed report of all examples tried is printed to stdout, along
35 with assorted summaries at the end.
37 You can force verbose mode by passing "verbose=True" to testmod, or prohibit
38 it by passing "verbose=False". In either of those cases, sys.argv is not
41 There are a variety of other ways to run doctests, including integration
42 with the unittest framework, and support for running non-Python text
43 files containing doctests. There are also many ways to override parts
44 of doctest's default behaviors. See the Library Reference Manual for
48 __docformat__
= 'reStructuredText en'
52 'register_optionflag',
53 'DONT_ACCEPT_TRUE_FOR_1',
54 'DONT_ACCEPT_BLANKLINE',
55 'NORMALIZE_WHITESPACE',
57 'IGNORE_EXCEPTION_DETAIL',
62 'REPORT_ONLY_FIRST_FAILURE',
64 # 1. Utility Functions
66 # 2. Example & DocTest
77 'UnexpectedException',
82 'run_docstring_examples',
88 'set_unittest_reportflags',
89 # 9. Debugging Support
90 'script_from_examples',
98 import sys
, traceback
, inspect
, linecache
, os
, re
, types
99 import unittest
, difflib
, pdb
, tempfile
101 from StringIO
import StringIO
103 # Don't whine about the deprecated is_private function in this
105 warnings
.filterwarnings("ignore", "is_private", DeprecationWarning,
108 # There are 4 basic classes:
109 # - Example: a <source, want> pair, plus an intra-docstring line number.
110 # - DocTest: a collection of examples, parsed from a docstring, plus
111 # info about where the docstring came from (name, filename, lineno).
112 # - DocTestFinder: extracts DocTests from a given object's docstring and
113 # its contained objects' docstrings.
114 # - DocTestRunner: runs DocTest cases, and accumulates statistics.
116 # So the basic picture is:
119 # +------+ +---------+ +-------+
120 # |object| --DocTestFinder-> | DocTest | --DocTestRunner-> |results|
121 # +------+ +---------+ +-------+
129 OPTIONFLAGS_BY_NAME
= {}
130 def register_optionflag(name
):
131 flag
= 1 << len(OPTIONFLAGS_BY_NAME
)
132 OPTIONFLAGS_BY_NAME
[name
] = flag
135 DONT_ACCEPT_TRUE_FOR_1
= register_optionflag('DONT_ACCEPT_TRUE_FOR_1')
136 DONT_ACCEPT_BLANKLINE
= register_optionflag('DONT_ACCEPT_BLANKLINE')
137 NORMALIZE_WHITESPACE
= register_optionflag('NORMALIZE_WHITESPACE')
138 ELLIPSIS
= register_optionflag('ELLIPSIS')
139 IGNORE_EXCEPTION_DETAIL
= register_optionflag('IGNORE_EXCEPTION_DETAIL')
141 COMPARISON_FLAGS
= (DONT_ACCEPT_TRUE_FOR_1 |
142 DONT_ACCEPT_BLANKLINE |
143 NORMALIZE_WHITESPACE |
145 IGNORE_EXCEPTION_DETAIL
)
147 REPORT_UDIFF
= register_optionflag('REPORT_UDIFF')
148 REPORT_CDIFF
= register_optionflag('REPORT_CDIFF')
149 REPORT_NDIFF
= register_optionflag('REPORT_NDIFF')
150 REPORT_ONLY_FIRST_FAILURE
= register_optionflag('REPORT_ONLY_FIRST_FAILURE')
152 REPORTING_FLAGS
= (REPORT_UDIFF |
155 REPORT_ONLY_FIRST_FAILURE
)
157 # Special string markers for use in `want` strings:
158 BLANKLINE_MARKER
= '<BLANKLINE>'
159 ELLIPSIS_MARKER
= '...'
161 ######################################################################
163 ######################################################################
164 # 1. Utility Functions
165 # 2. Example & DocTest -- store test cases
166 # 3. DocTest Parser -- extracts examples from strings
167 # 4. DocTest Finder -- extracts test cases from objects
168 # 5. DocTest Runner -- runs test cases
169 # 6. Test Functions -- convenient wrappers for testing
170 # 7. Tester Class -- for backwards compatibility
171 # 8. Unittest Support
172 # 9. Debugging Support
175 ######################################################################
176 ## 1. Utility Functions
177 ######################################################################
179 def is_private(prefix
, base
):
180 """prefix, base -> true iff name prefix + "." + base is "private".
182 Prefix may be an empty string, and base does not contain a period.
183 Prefix is ignored (although functions you write conforming to this
184 protocol may make use of it).
185 Return true iff base begins with an (at least one) underscore, but
186 does not both begin and end with (at least) two underscores.
188 >>> is_private("a.b", "my_func")
190 >>> is_private("____", "_my_func")
192 >>> is_private("someclass", "__init__")
194 >>> is_private("sometypo", "__init_")
196 >>> is_private("x.y.z", "_")
198 >>> is_private("_x.y.z", "__")
200 >>> is_private("", "") # senseless but consistent
203 warnings
.warn("is_private is deprecated; it wasn't useful; "
204 "examine DocTestFinder.find() lists instead",
205 DeprecationWarning, stacklevel
=2)
206 return base
[:1] == "_" and not base
[:2] == "__" == base
[-2:]
208 def _extract_future_flags(globs
):
210 Return the compiler-flags associated with the future features that
211 have been imported into the given namespace (globs).
214 for fname
in __future__
.all_feature_names
:
215 feature
= globs
.get(fname
, None)
216 if feature
is getattr(__future__
, fname
):
217 flags |
= feature
.compiler_flag
220 def _normalize_module(module
, depth
=2):
222 Return the module specified by `module`. In particular:
223 - If `module` is a module, then return module.
224 - If `module` is a string, then import and return the
225 module with that name.
226 - If `module` is None, then return the calling module.
227 The calling module is assumed to be the module of
228 the stack frame at the given depth in the call stack.
230 if inspect
.ismodule(module
):
232 elif isinstance(module
, (str, unicode)):
233 return __import__(module
, globals(), locals(), ["*"])
235 return sys
.modules
[sys
._getframe
(depth
).f_globals
['__name__']]
237 raise TypeError("Expected a module, string, or None")
239 def _indent(s
, indent
=4):
241 Add the given number of space characters to the beginning every
242 non-blank line in `s`, and return the result.
244 # This regexp matches the start of non-blank lines:
245 return re
.sub('(?m)^(?!$)', indent
*' ', s
)
247 def _exception_traceback(exc_info
):
249 Return a string containing a traceback message for the given
250 exc_info tuple (as returned by sys.exc_info()).
252 # Get a traceback message.
254 exc_type
, exc_val
, exc_tb
= exc_info
255 traceback
.print_exception(exc_type
, exc_val
, exc_tb
, file=excout
)
256 return excout
.getvalue()
258 # Override some StringIO methods.
259 class _SpoofOut(StringIO
):
261 result
= StringIO
.getvalue(self
)
262 # If anything at all was written, make sure there's a trailing
263 # newline. There's no way for the expected output to indicate
264 # that a trailing newline is missing.
265 if result
and not result
.endswith("\n"):
267 # Prevent softspace from screwing up the next test case, in
268 # case they used print with a trailing comma in an example.
269 if hasattr(self
, "softspace"):
273 def truncate(self
, size
=None):
274 StringIO
.truncate(self
, size
)
275 if hasattr(self
, "softspace"):
278 # Worst-case linear-time ellipsis matching.
279 def _ellipsis_match(want
, got
):
281 Essentially the only subtle case:
282 >>> _ellipsis_match('aa...aa', 'aaa')
285 if ELLIPSIS_MARKER
not in want
:
288 # Find "the real" strings.
289 ws
= want
.split(ELLIPSIS_MARKER
)
292 # Deal with exact matches possibly needed at one or both ends.
293 startpos
, endpos
= 0, len(got
)
295 if w
: # starts with exact match
296 if got
.startswith(w
):
302 if w
: # ends with exact match
309 if startpos
> endpos
:
310 # Exact end matches required more characters than we have, as in
311 # _ellipsis_match('aa...aa', 'aaa')
314 # For the rest, we only need to find the leftmost non-overlapping
315 # match for each piece. If there's no overall match that way alone,
316 # there's no overall match period.
318 # w may be '' at times, if there are consecutive ellipses, or
319 # due to an ellipsis at the start or end of `want`. That's OK.
320 # Search for an empty string succeeds, and doesn't change startpos.
321 startpos
= got
.find(w
, startpos
, endpos
)
328 def _comment_line(line
):
329 "Return a commented form of the given line"
336 class _OutputRedirectingPdb(pdb
.Pdb
):
338 A specialized version of the python debugger that redirects stdout
339 to a given stream when interacting with the user. Stdout is *not*
340 redirected when traced code is executed.
342 def __init__(self
, out
):
344 pdb
.Pdb
.__init
__(self
)
346 def trace_dispatch(self
, *args
):
347 # Redirect stdout to the given stream.
348 save_stdout
= sys
.stdout
349 sys
.stdout
= self
.__out
350 # Call Pdb's trace dispatch method.
352 return pdb
.Pdb
.trace_dispatch(self
, *args
)
354 sys
.stdout
= save_stdout
356 # [XX] Normalize with respect to os.path.pardir?
357 def _module_relative_path(module
, path
):
358 if not inspect
.ismodule(module
):
359 raise TypeError, 'Expected a module: %r' % module
360 if path
.startswith('/'):
361 raise ValueError, 'Module-relative files may not have absolute paths'
363 # Find the base directory for the path.
364 if hasattr(module
, '__file__'):
365 # A normal module/package
366 basedir
= os
.path
.split(module
.__file
__)[0]
367 elif module
.__name
__ == '__main__':
368 # An interactive session.
369 if len(sys
.argv
)>0 and sys
.argv
[0] != '':
370 basedir
= os
.path
.split(sys
.argv
[0])[0]
374 # A module w/o __file__ (this includes builtins)
375 raise ValueError("Can't resolve paths relative to the module " +
376 module
+ " (it has no __file__)")
378 # Combine the base directory and the path.
379 return os
.path
.join(basedir
, *(path
.split('/')))
381 ######################################################################
382 ## 2. Example & DocTest
383 ######################################################################
384 ## - An "example" is a <source, want> pair, where "source" is a
385 ## fragment of source code, and "want" is the expected output for
386 ## "source." The Example class also includes information about
387 ## where the example was extracted from.
389 ## - A "doctest" is a collection of examples, typically extracted from
390 ## a string (such as an object's docstring). The DocTest class also
391 ## includes information about where the string was extracted from.
395 A single doctest example, consisting of source code and expected
396 output. `Example` defines the following attributes:
398 - source: A single Python statement, always ending with a newline.
399 The constructor adds a newline if needed.
401 - want: The expected output from running the source code (either
402 from stdout, or a traceback in case of exception). `want` ends
403 with a newline unless it's empty, in which case it's an empty
404 string. The constructor adds a newline if needed.
406 - exc_msg: The exception message generated by the example, if
407 the example is expected to generate an exception; or `None` if
408 it is not expected to generate an exception. This exception
409 message is compared against the return value of
410 `traceback.format_exception_only()`. `exc_msg` ends with a
411 newline unless it's `None`. The constructor adds a newline
414 - lineno: The line number within the DocTest string containing
415 this Example where the Example begins. This line number is
416 zero-based, with respect to the beginning of the DocTest.
418 - indent: The example's indentation in the DocTest string.
419 I.e., the number of space characters that preceed the
420 example's first prompt.
422 - options: A dictionary mapping from option flags to True or
423 False, which is used to override default options for this
424 example. Any option flags not contained in this dictionary
425 are left at their default value (as specified by the
426 DocTestRunner's optionflags). By default, no options are set.
428 def __init__(self
, source
, want
, exc_msg
=None, lineno
=0, indent
=0,
431 if not source
.endswith('\n'):
433 if want
and not want
.endswith('\n'):
435 if exc_msg
is not None and not exc_msg
.endswith('\n'):
442 if options
is None: options
= {}
443 self
.options
= options
444 self
.exc_msg
= exc_msg
448 A collection of doctest examples that should be run in a single
449 namespace. Each `DocTest` defines the following attributes:
451 - examples: the list of examples.
453 - globs: The namespace (aka globals) that the examples should
456 - name: A name identifying the DocTest (typically, the name of
457 the object whose docstring this DocTest was extracted from).
459 - filename: The name of the file that this DocTest was extracted
460 from, or `None` if the filename is unknown.
462 - lineno: The line number within filename where this DocTest
463 begins, or `None` if the line number is unavailable. This
464 line number is zero-based, with respect to the beginning of
467 - docstring: The string that the examples were extracted from,
468 or `None` if the string is unavailable.
470 def __init__(self
, examples
, globs
, name
, filename
, lineno
, docstring
):
472 Create a new DocTest containing the given examples. The
473 DocTest's globals are initialized with a copy of `globs`.
475 assert not isinstance(examples
, basestring
), \
476 "DocTest no longer accepts str; use DocTestParser instead"
477 self
.examples
= examples
478 self
.docstring
= docstring
479 self
.globs
= globs
.copy()
481 self
.filename
= filename
485 if len(self
.examples
) == 0:
486 examples
= 'no examples'
487 elif len(self
.examples
) == 1:
488 examples
= '1 example'
490 examples
= '%d examples' % len(self
.examples
)
491 return ('<DocTest %s from %s:%s (%s)>' %
492 (self
.name
, self
.filename
, self
.lineno
, examples
))
495 # This lets us sort tests by name:
496 def __cmp__(self
, other
):
497 if not isinstance(other
, DocTest
):
499 return cmp((self
.name
, self
.filename
, self
.lineno
, id(self
)),
500 (other
.name
, other
.filename
, other
.lineno
, id(other
)))
502 ######################################################################
504 ######################################################################
508 A class used to parse strings containing doctest examples.
510 # This regular expression is used to find doctest examples in a
511 # string. It defines three groups: `source` is the source code
512 # (including leading indentation and prompts); `indent` is the
513 # indentation of the first (PS1) line of the source code; and
514 # `want` is the expected output (including leading indentation).
515 _EXAMPLE_RE
= re
.compile(r
'''
516 # Source consists of a PS1 line followed by zero or more PS2 lines.
518 (?:^(?P<indent> [ ]*) >>> .*) # PS1 line
519 (?:\n [ ]* \.\.\. .*)*) # PS2 lines
521 # Want consists of any non-blank lines that do not start with PS1.
522 (?P<want> (?:(?![ ]*$) # Not a blank line
523 (?![ ]*>>>) # Not a line starting with PS1
524 .*$\n? # But any other line
526 ''', re
.MULTILINE | re
.VERBOSE
)
528 # A regular expression for handling `want` strings that contain
529 # expected exceptions. It divides `want` into three pieces:
530 # - the traceback header line (`hdr`)
531 # - the traceback stack (`stack`)
532 # - the exception message (`msg`), as generated by
533 # traceback.format_exception_only()
534 # `msg` may have multiple lines. We assume/require that the
535 # exception message is the first non-indented line starting with a word
536 # character following the traceback header line.
537 _EXCEPTION_RE
= re
.compile(r
"""
538 # Grab the traceback header. Different versions of Python have
539 # said different things on the first traceback line.
540 ^(?P<hdr> Traceback\ \(
541 (?: most\ recent\ call\ last
545 \s* $ # toss trailing whitespace on the header.
546 (?P<stack> .*?) # don't blink: absorb stuff until...
547 ^ (?P<msg> \w+ .*) # a line *starts* with alphanum.
548 """, re
.VERBOSE | re
.MULTILINE | re
.DOTALL
)
550 # A callable returning a true value iff its argument is a blank line
551 # or contains a single comment.
552 _IS_BLANK_OR_COMMENT
= re
.compile(r
'^[ ]*(#.*)?$').match
554 def parse(self
, string
, name
='<string>'):
556 Divide the given string into examples and intervening text,
557 and return them as a list of alternating Examples and strings.
558 Line numbers for the Examples are 0-based. The optional
559 argument `name` is a name identifying this string, and is only
560 used for error messages.
562 string
= string
.expandtabs()
563 # If all lines begin with the same indentation, then strip it.
564 min_indent
= self
._min
_indent
(string
)
566 string
= '\n'.join([l
[min_indent
:] for l
in string
.split('\n')])
569 charno
, lineno
= 0, 0
570 # Find all doctest examples in the string:
571 for m
in self
._EXAMPLE
_RE
.finditer(string
):
572 # Add the pre-example text to `output`.
573 output
.append(string
[charno
:m
.start()])
574 # Update lineno (lines before this example)
575 lineno
+= string
.count('\n', charno
, m
.start())
576 # Extract info from the regexp match.
577 (source
, options
, want
, exc_msg
) = \
578 self
._parse
_example
(m
, name
, lineno
)
579 # Create an Example, and add it to the list.
580 if not self
._IS
_BLANK
_OR
_COMMENT
(source
):
581 output
.append( Example(source
, want
, exc_msg
,
583 indent
=min_indent
+len(m
.group('indent')),
585 # Update lineno (lines inside this example)
586 lineno
+= string
.count('\n', m
.start(), m
.end())
589 # Add any remaining post-example text to `output`.
590 output
.append(string
[charno
:])
593 def get_doctest(self
, string
, globs
, name
, filename
, lineno
):
595 Extract all doctest examples from the given string, and
596 collect them into a `DocTest` object.
598 `globs`, `name`, `filename`, and `lineno` are attributes for
599 the new `DocTest` object. See the documentation for `DocTest`
600 for more information.
602 return DocTest(self
.get_examples(string
, name
), globs
,
603 name
, filename
, lineno
, string
)
605 def get_examples(self
, string
, name
='<string>'):
607 Extract all doctest examples from the given string, and return
608 them as a list of `Example` objects. Line numbers are
609 0-based, because it's most common in doctests that nothing
610 interesting appears on the same line as opening triple-quote,
611 and so the first interesting line is called \"line 1\" then.
613 The optional argument `name` is a name identifying this
614 string, and is only used for error messages.
616 return [x
for x
in self
.parse(string
, name
)
617 if isinstance(x
, Example
)]
619 def _parse_example(self
, m
, name
, lineno
):
621 Given a regular expression match from `_EXAMPLE_RE` (`m`),
622 return a pair `(source, want)`, where `source` is the matched
623 example's source code (with prompts and indentation stripped);
624 and `want` is the example's expected output (with indentation
627 `name` is the string's name, and `lineno` is the line number
628 where the example starts; both are used for error messages.
630 # Get the example's indentation level.
631 indent
= len(m
.group('indent'))
633 # Divide source into lines; check that they're properly
634 # indented; and then strip their indentation & prompts.
635 source_lines
= m
.group('source').split('\n')
636 self
._check
_prompt
_blank
(source_lines
, indent
, name
, lineno
)
637 self
._check
_prefix
(source_lines
[1:], ' '*indent
+ '.', name
, lineno
)
638 source
= '\n'.join([sl
[indent
+4:] for sl
in source_lines
])
640 # Divide want into lines; check that it's properly indented; and
641 # then strip the indentation. Spaces before the last newline should
642 # be preserved, so plain rstrip() isn't good enough.
643 want
= m
.group('want')
644 want_lines
= want
.split('\n')
645 if len(want_lines
) > 1 and re
.match(r
' *$', want_lines
[-1]):
646 del want_lines
[-1] # forget final newline & spaces after it
647 self
._check
_prefix
(want_lines
, ' '*indent
, name
,
648 lineno
+ len(source_lines
))
649 want
= '\n'.join([wl
[indent
:] for wl
in want_lines
])
651 # If `want` contains a traceback message, then extract it.
652 m
= self
._EXCEPTION
_RE
.match(want
)
654 exc_msg
= m
.group('msg')
658 # Extract options from the source.
659 options
= self
._find
_options
(source
, name
, lineno
)
661 return source
, options
, want
, exc_msg
663 # This regular expression looks for option directives in the
664 # source code of an example. Option directives are comments
665 # starting with "doctest:". Warning: this may give false
666 # positives for string-literals that contain the string
667 # "#doctest:". Eliminating these false positives would require
668 # actually parsing the string; but we limit them by ignoring any
669 # line containing "#doctest:" that is *followed* by a quote mark.
670 _OPTION_DIRECTIVE_RE
= re
.compile(r
'#\s*doctest:\s*([^\n\'"]*)$',
673 def _find_options(self, source, name, lineno):
675 Return a dictionary containing option overrides extracted from
676 option directives in the given source string.
678 `name` is the string's name, and `lineno` is the line number
679 where the example starts; both are used for error messages.
682 # (note: with the current regexp, this will match at most once:)
683 for m in self._OPTION_DIRECTIVE_RE.finditer(source):
684 option_strings = m.group(1).replace(',', ' ').split()
685 for option in option_strings:
686 if (option[0] not in '+-' or
687 option[1:] not in OPTIONFLAGS_BY_NAME):
688 raise ValueError('line %r of the doctest for %s '
689 'has an invalid option: %r' %
690 (lineno+1, name, option))
691 flag = OPTIONFLAGS_BY_NAME[option[1:]]
692 options[flag] = (option[0] == '+')
693 if options and self._IS_BLANK_OR_COMMENT(source):
694 raise ValueError('line %r of the doctest for %s has an option '
695 'directive on a line with no example: %r' %
696 (lineno, name, source))
699 # This regular expression finds the indentation of every non-blank
701 _INDENT_RE = re.compile('^([ ]*)(?=\S)', re.MULTILINE)
703 def _min_indent(self, s):
704 "Return the minimum indentation of any non
-blank line
in `s`
"
705 indents = [len(indent) for indent in self._INDENT_RE.findall(s)]
711 def _check_prompt_blank(self, lines, indent, name, lineno):
713 Given the lines of a source string (including prompts and
714 leading indentation), check to make sure that every prompt is
715 followed by a space character. If any line is not followed by
716 a space character, then raise ValueError.
718 for i, line in enumerate(lines):
719 if len(line) >= indent+4 and line[indent+3] != ' ':
720 raise ValueError('line %r of the docstring for %s '
721 'lacks blank after %s: %r' %
723 line[indent:indent+3], line))
725 def _check_prefix(self, lines, prefix, name, lineno):
727 Check that every line in the given list starts with the given
728 prefix; if any line does not, then raise a ValueError.
730 for i, line in enumerate(lines):
731 if line and not line.startswith(prefix):
732 raise ValueError('line %r of the docstring for %s has '
733 'inconsistent leading whitespace: %r' %
734 (lineno+i+1, name, line))
737 ######################################################################
739 ######################################################################
743 A class used to extract the DocTests that are relevant to a given
744 object, from its docstring and the docstrings of its contained
745 objects. Doctests can currently be extracted from the following
746 object types: modules, functions, classes, methods, staticmethods,
747 classmethods, and properties.
750 def __init__(self, verbose=False, parser=DocTestParser(),
751 recurse=True, _namefilter=None, exclude_empty=True):
753 Create a new doctest finder.
755 The optional argument `parser` specifies a class or
756 function that should be used to create new DocTest objects (or
757 objects that implement the same interface as DocTest). The
758 signature for this factory function should match the signature
759 of the DocTest constructor.
761 If the optional argument `recurse` is false, then `find` will
762 only examine the given object, and not any contained objects.
764 If the optional argument `exclude_empty` is false, then `find`
765 will include tests for objects with empty docstrings.
767 self._parser = parser
768 self._verbose = verbose
769 self._recurse = recurse
770 self._exclude_empty = exclude_empty
771 # _namefilter is undocumented, and exists only for temporary backward-
772 # compatibility support of testmod's deprecated isprivate mess.
773 self._namefilter = _namefilter
775 def find(self, obj, name=None, module=None, globs=None,
778 Return a list of the DocTests that are defined by the given
779 object's docstring, or by any of its contained objects'
782 The optional parameter `module` is the module that contains
783 the given object. If the module is not specified or is None, then
784 the test finder will attempt to automatically determine the
785 correct module. The object's module is used:
787 - As a default namespace, if `globs` is not specified.
788 - To prevent the DocTestFinder from extracting DocTests
789 from objects that are imported from other modules.
790 - To find the name of the file containing the object.
791 - To help find the line number of the object within its
794 Contained objects whose module does not match `module` are ignored.
796 If `module` is False, no attempt to find the module will be made.
797 This is obscure, of use mostly in tests: if `module` is False, or
798 is None but cannot be found automatically, then all objects are
799 considered to belong to the (non-existent) module, so all contained
800 objects will (recursively) be searched for doctests.
802 The globals for each DocTest is formed by combining `globs`
803 and `extraglobs` (bindings in `extraglobs` override bindings
804 in `globs`). A new copy of the globals dictionary is created
805 for each DocTest. If `globs` is not specified, then it
806 defaults to the module's `__dict__`, if specified, or {}
807 otherwise. If `extraglobs` is not specified, then it defaults
811 # If name was not specified, then extract it from the object.
813 name = getattr(obj, '__name__', None)
815 raise ValueError("DocTestFinder
.find
: name must be given
"
816 "when obj
.__name
__ doesn
't exist: %r" %
819 # Find the module that contains the given object (if obj is
820 # a module, then module=obj.). Note: this may fail, in which
821 # case module will be None.
825 module = inspect.getmodule(obj)
827 # Read the module's source code
. This
is used by
828 # DocTestFinder._find_lineno to find the line number for a
829 # given object's docstring.
831 file = inspect
.getsourcefile(obj
) or inspect
.getfile(obj
)
832 source_lines
= linecache
.getlines(file)
838 # Initialize globals, and merge in extraglobs.
843 globs
= module
.__dict
__.copy()
846 if extraglobs
is not None:
847 globs
.update(extraglobs
)
849 # Recursively expore `obj`, extracting DocTests.
851 self
._find
(tests
, obj
, name
, module
, source_lines
, globs
, {})
854 def _filter(self
, obj
, prefix
, base
):
856 Return true if the given object should not be examined.
858 return (self
._namefilter
is not None and
859 self
._namefilter
(prefix
, base
))
861 def _from_module(self
, module
, object):
863 Return true if the given object is defined in the given
868 elif inspect
.isfunction(object):
869 return module
.__dict
__ is object.func_globals
870 elif inspect
.isclass(object):
871 return module
.__name
__ == object.__module
__
872 elif inspect
.getmodule(object) is not None:
873 return module
is inspect
.getmodule(object)
874 elif hasattr(object, '__module__'):
875 return module
.__name
__ == object.__module
__
876 elif isinstance(object, property):
877 return True # [XX] no way not be sure.
879 raise ValueError("object must be a class or function")
881 def _find(self
, tests
, obj
, name
, module
, source_lines
, globs
, seen
):
883 Find tests for the given object and any contained objects, and
887 print 'Finding tests in %s' % name
889 # If we've already processed this object, then ignore it.
894 # Find a test for this object, and add it to the list of tests.
895 test
= self
._get
_test
(obj
, name
, module
, globs
, source_lines
)
899 # Look for tests in a module's contained objects.
900 if inspect
.ismodule(obj
) and self
._recurse
:
901 for valname
, val
in obj
.__dict
__.items():
902 # Check if this contained object should be ignored.
903 if self
._filter
(val
, name
, valname
):
905 valname
= '%s.%s' % (name
, valname
)
906 # Recurse to functions & classes.
907 if ((inspect
.isfunction(val
) or inspect
.isclass(val
)) and
908 self
._from
_module
(module
, val
)):
909 self
._find
(tests
, val
, valname
, module
, source_lines
,
912 # Look for tests in a module's __test__ dictionary.
913 if inspect
.ismodule(obj
) and self
._recurse
:
914 for valname
, val
in getattr(obj
, '__test__', {}).items():
915 if not isinstance(valname
, basestring
):
916 raise ValueError("DocTestFinder.find: __test__ keys "
917 "must be strings: %r" %
919 if not (inspect
.isfunction(val
) or inspect
.isclass(val
) or
920 inspect
.ismethod(val
) or inspect
.ismodule(val
) or
921 isinstance(val
, basestring
)):
922 raise ValueError("DocTestFinder.find: __test__ values "
923 "must be strings, functions, methods, "
924 "classes, or modules: %r" %
926 valname
= '%s.__test__.%s' % (name
, valname
)
927 self
._find
(tests
, val
, valname
, module
, source_lines
,
930 # Look for tests in a class's contained objects.
931 if inspect
.isclass(obj
) and self
._recurse
:
932 for valname
, val
in obj
.__dict
__.items():
933 # Check if this contained object should be ignored.
934 if self
._filter
(val
, name
, valname
):
936 # Special handling for staticmethod/classmethod.
937 if isinstance(val
, staticmethod):
938 val
= getattr(obj
, valname
)
939 if isinstance(val
, classmethod):
940 val
= getattr(obj
, valname
).im_func
942 # Recurse to methods, properties, and nested classes.
943 if ((inspect
.isfunction(val
) or inspect
.isclass(val
) or
944 isinstance(val
, property)) and
945 self
._from
_module
(module
, val
)):
946 valname
= '%s.%s' % (name
, valname
)
947 self
._find
(tests
, val
, valname
, module
, source_lines
,
950 def _get_test(self
, obj
, name
, module
, globs
, source_lines
):
952 Return a DocTest for the given object, if it defines a docstring;
953 otherwise, return None.
955 # Extract the object's docstring. If it doesn't have one,
956 # then return None (no test for this object).
957 if isinstance(obj
, basestring
):
961 if obj
.__doc
__ is None:
964 docstring
= obj
.__doc
__
965 if not isinstance(docstring
, basestring
):
966 docstring
= str(docstring
)
967 except (TypeError, AttributeError):
970 # Find the docstring's location in the file.
971 lineno
= self
._find
_lineno
(obj
, source_lines
)
973 # Don't bother if the docstring is empty.
974 if self
._exclude
_empty
and not docstring
:
977 # Return a DocTest for this object.
981 filename
= getattr(module
, '__file__', module
.__name
__)
982 if filename
[-4:] in (".pyc", ".pyo"):
983 filename
= filename
[:-1]
984 return self
._parser
.get_doctest(docstring
, globs
, name
,
987 def _find_lineno(self
, obj
, source_lines
):
989 Return a line number of the given object's docstring. Note:
990 this method assumes that the object has a docstring.
994 # Find the line number for modules.
995 if inspect
.ismodule(obj
):
998 # Find the line number for classes.
999 # Note: this could be fooled if a class is defined multiple
1000 # times in a single file.
1001 if inspect
.isclass(obj
):
1002 if source_lines
is None:
1004 pat
= re
.compile(r
'^\s*class\s*%s\b' %
1005 getattr(obj
, '__name__', '-'))
1006 for i
, line
in enumerate(source_lines
):
1011 # Find the line number for functions & methods.
1012 if inspect
.ismethod(obj
): obj
= obj
.im_func
1013 if inspect
.isfunction(obj
): obj
= obj
.func_code
1014 if inspect
.istraceback(obj
): obj
= obj
.tb_frame
1015 if inspect
.isframe(obj
): obj
= obj
.f_code
1016 if inspect
.iscode(obj
):
1017 lineno
= getattr(obj
, 'co_firstlineno', None)-1
1019 # Find the line number where the docstring starts. Assume
1020 # that it's the first line that begins with a quote mark.
1021 # Note: this could be fooled by a multiline function
1022 # signature, where a continuation line begins with a quote
1024 if lineno
is not None:
1025 if source_lines
is None:
1027 pat
= re
.compile('(^|.*:)\s*\w*("|\')')
1028 for lineno
in range(lineno
, len(source_lines
)):
1029 if pat
.match(source_lines
[lineno
]):
1032 # We couldn't find the line number.
1035 ######################################################################
1036 ## 5. DocTest Runner
1037 ######################################################################
1039 class DocTestRunner
:
1041 A class used to run DocTest test cases, and accumulate statistics.
1042 The `run` method is used to process a single DocTest case. It
1043 returns a tuple `(f, t)`, where `t` is the number of test cases
1044 tried, and `f` is the number of test cases that failed.
1046 >>> tests = DocTestFinder().find(_TestClass)
1047 >>> runner = DocTestRunner(verbose=False)
1048 >>> for test in tests:
1049 ... print runner.run(test)
1055 The `summarize` method prints a summary of all the test cases that
1056 have been run by the runner, and returns an aggregated `(f, t)`
1059 >>> runner.summarize(verbose=1)
1060 4 items passed all tests:
1061 2 tests in _TestClass
1062 2 tests in _TestClass.__init__
1063 2 tests in _TestClass.get
1064 1 tests in _TestClass.square
1066 7 passed and 0 failed.
1070 The aggregated number of tried examples and failed examples is
1071 also available via the `tries` and `failures` attributes:
1078 The comparison between expected outputs and actual outputs is done
1079 by an `OutputChecker`. This comparison may be customized with a
1080 number of option flags; see the documentation for `testmod` for
1081 more information. If the option flags are insufficient, then the
1082 comparison may also be customized by passing a subclass of
1083 `OutputChecker` to the constructor.
1085 The test runner's display output can be controlled in two ways.
1086 First, an output function (`out) can be passed to
1087 `TestRunner.run`; this function will be called with strings that
1088 should be displayed. It defaults to `sys.stdout.write`. If
1089 capturing the output is not sufficient, then the display output
1090 can be also customized by subclassing DocTestRunner, and
1091 overriding the methods `report_start`, `report_success`,
1092 `report_unexpected_exception`, and `report_failure`.
1094 # This divider string is used to separate failure messages, and to
1095 # separate sections of the summary.
1098 def __init__(self
, checker
=None, verbose
=None, optionflags
=0):
1100 Create a new test runner.
1102 Optional keyword arg `checker` is the `OutputChecker` that
1103 should be used to compare the expected outputs and actual
1104 outputs of doctest examples.
1106 Optional keyword arg 'verbose' prints lots of stuff if true,
1107 only failures if false; by default, it's true iff '-v' is in
1110 Optional argument `optionflags` can be used to control how the
1111 test runner compares expected output to actual output, and how
1112 it displays failures. See the documentation for `testmod` for
1115 self
._checker
= checker
or OutputChecker()
1117 verbose
= '-v' in sys
.argv
1118 self
._verbose
= verbose
1119 self
.optionflags
= optionflags
1120 self
.original_optionflags
= optionflags
1122 # Keep track of the examples we've run.
1127 # Create a fake output target for capturing doctest output.
1128 self
._fakeout
= _SpoofOut()
1130 #/////////////////////////////////////////////////////////////////
1132 #/////////////////////////////////////////////////////////////////
1134 def report_start(self
, out
, test
, example
):
1136 Report that the test runner is about to process the given
1137 example. (Only displays a message if verbose=True)
1141 out('Trying:\n' + _indent(example
.source
) +
1142 'Expecting:\n' + _indent(example
.want
))
1144 out('Trying:\n' + _indent(example
.source
) +
1145 'Expecting nothing\n')
1147 def report_success(self
, out
, test
, example
, got
):
1149 Report that the given example ran successfully. (Only
1150 displays a message if verbose=True)
1155 def report_failure(self
, out
, test
, example
, got
):
1157 Report that the given example failed.
1159 out(self
._failure
_header
(test
, example
) +
1160 self
._checker
.output_difference(example
, got
, self
.optionflags
))
1162 def report_unexpected_exception(self
, out
, test
, example
, exc_info
):
1164 Report that the given example raised an unexpected exception.
1166 out(self
._failure
_header
(test
, example
) +
1167 'Exception raised:\n' + _indent(_exception_traceback(exc_info
)))
1169 def _failure_header(self
, test
, example
):
1170 out
= [self
.DIVIDER
]
1172 if test
.lineno
is not None and example
.lineno
is not None:
1173 lineno
= test
.lineno
+ example
.lineno
+ 1
1176 out
.append('File "%s", line %s, in %s' %
1177 (test
.filename
, lineno
, test
.name
))
1179 out
.append('Line %s, in %s' % (example
.lineno
+1, test
.name
))
1180 out
.append('Failed example:')
1181 source
= example
.source
1182 out
.append(_indent(source
))
1183 return '\n'.join(out
)
1185 #/////////////////////////////////////////////////////////////////
1187 #/////////////////////////////////////////////////////////////////
1189 def __run(self
, test
, compileflags
, out
):
1191 Run the examples in `test`. Write the outcome of each example
1192 with one of the `DocTestRunner.report_*` methods, using the
1193 writer function `out`. `compileflags` is the set of compiler
1194 flags that should be used to execute examples. Return a tuple
1195 `(f, t)`, where `t` is the number of examples tried, and `f`
1196 is the number of examples that failed. The examples are run
1197 in the namespace `test.globs`.
1199 # Keep track of the number of failures and tries.
1200 failures
= tries
= 0
1202 # Save the option flags (since option directives can be used
1204 original_optionflags
= self
.optionflags
1206 SUCCESS
, FAILURE
, BOOM
= range(3) # `outcome` state
1208 check
= self
._checker
.check_output
1210 # Process each example.
1211 for examplenum
, example
in enumerate(test
.examples
):
1213 # If REPORT_ONLY_FIRST_FAILURE is set, then supress
1214 # reporting after the first failure.
1215 quiet
= (self
.optionflags
& REPORT_ONLY_FIRST_FAILURE
and
1218 # Merge in the example's options.
1219 self
.optionflags
= original_optionflags
1221 for (optionflag
, val
) in example
.options
.items():
1223 self
.optionflags |
= optionflag
1225 self
.optionflags
&= ~optionflag
1227 # Record that we started this example.
1230 self
.report_start(out
, test
, example
)
1232 # Use a special filename for compile(), so we can retrieve
1233 # the source code during interactive debugging (see
1234 # __patched_linecache_getlines).
1235 filename
= '<doctest %s[%d]>' % (test
.name
, examplenum
)
1237 # Run the example in the given context (globs), and record
1238 # any exception that gets raised. (But don't intercept
1239 # keyboard interrupts.)
1241 # Don't blink! This is where the user's code gets run.
1242 exec compile(example
.source
, filename
, "single",
1243 compileflags
, 1) in test
.globs
1244 self
.debugger
.set_continue() # ==== Example Finished ====
1246 except KeyboardInterrupt:
1249 exception
= sys
.exc_info()
1250 self
.debugger
.set_continue() # ==== Example Finished ====
1252 got
= self
._fakeout
.getvalue() # the actual output
1253 self
._fakeout
.truncate(0)
1254 outcome
= FAILURE
# guilty until proved innocent or insane
1256 # If the example executed without raising any exceptions,
1257 # verify its output.
1258 if exception
is None:
1259 if check(example
.want
, got
, self
.optionflags
):
1262 # The example raised an exception: check if it was expected.
1264 exc_info
= sys
.exc_info()
1265 exc_msg
= traceback
.format_exception_only(*exc_info
[:2])[-1]
1267 got
+= _exception_traceback(exc_info
)
1269 # If `example.exc_msg` is None, then we weren't expecting
1271 if example
.exc_msg
is None:
1274 # We expected an exception: see whether it matches.
1275 elif check(example
.exc_msg
, exc_msg
, self
.optionflags
):
1278 # Another chance if they didn't care about the detail.
1279 elif self
.optionflags
& IGNORE_EXCEPTION_DETAIL
:
1280 m1
= re
.match(r
'[^:]*:', example
.exc_msg
)
1281 m2
= re
.match(r
'[^:]*:', exc_msg
)
1282 if m1
and m2
and check(m1
.group(0), m2
.group(0),
1286 # Report the outcome.
1287 if outcome
is SUCCESS
:
1289 self
.report_success(out
, test
, example
, got
)
1290 elif outcome
is FAILURE
:
1292 self
.report_failure(out
, test
, example
, got
)
1294 elif outcome
is BOOM
:
1296 self
.report_unexpected_exception(out
, test
, example
,
1300 assert False, ("unknown outcome", outcome
)
1302 # Restore the option flags (in case they were modified)
1303 self
.optionflags
= original_optionflags
1305 # Record and return the number of failures and tries.
1306 self
.__record
_outcome
(test
, failures
, tries
)
1307 return failures
, tries
1309 def __record_outcome(self
, test
, f
, t
):
1311 Record the fact that the given DocTest (`test`) generated `f`
1312 failures out of `t` tried examples.
1314 f2
, t2
= self
._name
2ft
.get(test
.name
, (0,0))
1315 self
._name
2ft
[test
.name
] = (f
+f2
, t
+t2
)
1319 __LINECACHE_FILENAME_RE
= re
.compile(r
'<doctest '
1320 r
'(?P<name>[\w\.]+)'
1321 r
'\[(?P<examplenum>\d+)\]>$')
1322 def __patched_linecache_getlines(self
, filename
):
1323 m
= self
.__LINECACHE
_FILENAME
_RE
.match(filename
)
1324 if m
and m
.group('name') == self
.test
.name
:
1325 example
= self
.test
.examples
[int(m
.group('examplenum'))]
1326 return example
.source
.splitlines(True)
1328 return self
.save_linecache_getlines(filename
)
1330 def run(self
, test
, compileflags
=None, out
=None, clear_globs
=True):
1332 Run the examples in `test`, and display the results using the
1333 writer function `out`.
1335 The examples are run in the namespace `test.globs`. If
1336 `clear_globs` is true (the default), then this namespace will
1337 be cleared after the test runs, to help with garbage
1338 collection. If you would like to examine the namespace after
1339 the test completes, then use `clear_globs=False`.
1341 `compileflags` gives the set of flags that should be used by
1342 the Python compiler when running the examples. If not
1343 specified, then it will default to the set of future-import
1344 flags that apply to `globs`.
1346 The output of each example is checked using
1347 `DocTestRunner.check_output`, and the results are formatted by
1348 the `DocTestRunner.report_*` methods.
1352 if compileflags
is None:
1353 compileflags
= _extract_future_flags(test
.globs
)
1355 save_stdout
= sys
.stdout
1357 out
= save_stdout
.write
1358 sys
.stdout
= self
._fakeout
1360 # Patch pdb.set_trace to restore sys.stdout during interactive
1361 # debugging (so it's not still redirected to self._fakeout).
1362 # Note that the interactive output will go to *our*
1363 # save_stdout, even if that's not the real sys.stdout; this
1364 # allows us to write test cases for the set_trace behavior.
1365 save_set_trace
= pdb
.set_trace
1366 self
.debugger
= _OutputRedirectingPdb(save_stdout
)
1367 self
.debugger
.reset()
1368 pdb
.set_trace
= self
.debugger
.set_trace
1370 # Patch linecache.getlines, so we can see the example's source
1371 # when we're inside the debugger.
1372 self
.save_linecache_getlines
= linecache
.getlines
1373 linecache
.getlines
= self
.__patched
_linecache
_getlines
1376 return self
.__run
(test
, compileflags
, out
)
1378 sys
.stdout
= save_stdout
1379 pdb
.set_trace
= save_set_trace
1380 linecache
.getlines
= self
.save_linecache_getlines
1384 #/////////////////////////////////////////////////////////////////
1386 #/////////////////////////////////////////////////////////////////
1387 def summarize(self
, verbose
=None):
1389 Print a summary of all the test cases that have been run by
1390 this DocTestRunner, and return a tuple `(f, t)`, where `f` is
1391 the total number of failed examples, and `t` is the total
1392 number of tried examples.
1394 The optional `verbose` argument controls how detailed the
1395 summary is. If the verbosity is not specified, then the
1396 DocTestRunner's verbosity is used.
1399 verbose
= self
._verbose
1404 for x
in self
._name
2ft
.items():
1410 notests
.append(name
)
1412 passed
.append( (name
, t
) )
1417 print len(notests
), "items had no tests:"
1419 for thing
in notests
:
1422 print len(passed
), "items passed all tests:"
1424 for thing
, count
in passed
:
1425 print " %3d tests in %s" % (count
, thing
)
1428 print len(failed
), "items had failures:"
1430 for thing
, (f
, t
) in failed
:
1431 print " %3d of %3d in %s" % (f
, t
, thing
)
1433 print totalt
, "tests in", len(self
._name
2ft
), "items."
1434 print totalt
- totalf
, "passed and", totalf
, "failed."
1436 print "***Test Failed***", totalf
, "failures."
1438 print "Test passed."
1439 return totalf
, totalt
1441 #/////////////////////////////////////////////////////////////////
1442 # Backward compatibility cruft to maintain doctest.master.
1443 #/////////////////////////////////////////////////////////////////
1444 def merge(self
, other
):
1446 for name
, (f
, t
) in other
._name
2ft
.items():
1448 print "*** DocTestRunner.merge: '" + name
+ "' in both" \
1449 " testers; summing outcomes."
1455 class OutputChecker
:
1457 A class used to check the whether the actual output from a doctest
1458 example matches the expected output. `OutputChecker` defines two
1459 methods: `check_output`, which compares a given pair of outputs,
1460 and returns true if they match; and `output_difference`, which
1461 returns a string describing the differences between two outputs.
1463 def check_output(self
, want
, got
, optionflags
):
1465 Return True iff the actual output from an example (`got`)
1466 matches the expected output (`want`). These strings are
1467 always considered to match if they are identical; but
1468 depending on what option flags the test runner is using,
1469 several non-exact match types are also possible. See the
1470 documentation for `TestRunner` for more information about
1473 # Handle the common case first, for efficiency:
1474 # if they're string-identical, always return true.
1478 # The values True and False replaced 1 and 0 as the return
1479 # value for boolean comparisons in Python 2.3.
1480 if not (optionflags
& DONT_ACCEPT_TRUE_FOR_1
):
1481 if (got
,want
) == ("True\n", "1\n"):
1483 if (got
,want
) == ("False\n", "0\n"):
1486 # <BLANKLINE> can be used as a special sequence to signify a
1487 # blank line, unless the DONT_ACCEPT_BLANKLINE flag is used.
1488 if not (optionflags
& DONT_ACCEPT_BLANKLINE
):
1489 # Replace <BLANKLINE> in want with a blank line.
1490 want
= re
.sub('(?m)^%s\s*?$' % re
.escape(BLANKLINE_MARKER
),
1492 # If a line in got contains only spaces, then remove the
1494 got
= re
.sub('(?m)^\s*?$', '', got
)
1498 # This flag causes doctest to ignore any differences in the
1499 # contents of whitespace strings. Note that this can be used
1500 # in conjunction with the ELLIPSIS flag.
1501 if optionflags
& NORMALIZE_WHITESPACE
:
1502 got
= ' '.join(got
.split())
1503 want
= ' '.join(want
.split())
1507 # The ELLIPSIS flag says to let the sequence "..." in `want`
1508 # match any substring in `got`.
1509 if optionflags
& ELLIPSIS
:
1510 if _ellipsis_match(want
, got
):
1513 # We didn't find any match; return false.
1516 # Should we do a fancy diff?
1517 def _do_a_fancy_diff(self
, want
, got
, optionflags
):
1518 # Not unless they asked for a fancy diff.
1519 if not optionflags
& (REPORT_UDIFF |
1524 # If expected output uses ellipsis, a meaningful fancy diff is
1525 # too hard ... or maybe not. In two real-life failures Tim saw,
1526 # a diff was a major help anyway, so this is commented out.
1527 # [todo] _ellipsis_match() knows which pieces do and don't match,
1528 # and could be the basis for a kick-ass diff in this case.
1529 ##if optionflags & ELLIPSIS and ELLIPSIS_MARKER in want:
1532 # ndiff does intraline difference marking, so can be useful even
1533 # for 1-line differences.
1534 if optionflags
& REPORT_NDIFF
:
1537 # The other diff types need at least a few lines to be helpful.
1538 return want
.count('\n') > 2 and got
.count('\n') > 2
1540 def output_difference(self
, example
, got
, optionflags
):
1542 Return a string describing the differences between the
1543 expected output for a given example (`example`) and the actual
1544 output (`got`). `optionflags` is the set of option flags used
1545 to compare `want` and `got`.
1548 # If <BLANKLINE>s are being used, then replace blank lines
1549 # with <BLANKLINE> in the actual output string.
1550 if not (optionflags
& DONT_ACCEPT_BLANKLINE
):
1551 got
= re
.sub('(?m)^[ ]*(?=\n)', BLANKLINE_MARKER
, got
)
1553 # Check if we should use diff.
1554 if self
._do
_a
_fancy
_diff
(want
, got
, optionflags
):
1555 # Split want & got into lines.
1556 want_lines
= want
.splitlines(True) # True == keep line ends
1557 got_lines
= got
.splitlines(True)
1558 # Use difflib to find their differences.
1559 if optionflags
& REPORT_UDIFF
:
1560 diff
= difflib
.unified_diff(want_lines
, got_lines
, n
=2)
1561 diff
= list(diff
)[2:] # strip the diff header
1562 kind
= 'unified diff with -expected +actual'
1563 elif optionflags
& REPORT_CDIFF
:
1564 diff
= difflib
.context_diff(want_lines
, got_lines
, n
=2)
1565 diff
= list(diff
)[2:] # strip the diff header
1566 kind
= 'context diff with expected followed by actual'
1567 elif optionflags
& REPORT_NDIFF
:
1568 engine
= difflib
.Differ(charjunk
=difflib
.IS_CHARACTER_JUNK
)
1569 diff
= list(engine
.compare(want_lines
, got_lines
))
1570 kind
= 'ndiff with -expected +actual'
1572 assert 0, 'Bad diff option'
1573 # Remove trailing whitespace on diff output.
1574 diff
= [line
.rstrip() + '\n' for line
in diff
]
1575 return 'Differences (%s):\n' % kind
+ _indent(''.join(diff
))
1577 # If we're not using diff, then simply list the expected
1578 # output followed by the actual output.
1580 return 'Expected:\n%sGot:\n%s' % (_indent(want
), _indent(got
))
1582 return 'Expected:\n%sGot nothing\n' % _indent(want
)
1584 return 'Expected nothing\nGot:\n%s' % _indent(got
)
1586 return 'Expected nothing\nGot nothing\n'
1588 class DocTestFailure(Exception):
1589 """A DocTest example has failed in debugging mode.
1591 The exception instance has variables:
1593 - test: the DocTest object being run
1595 - excample: the Example object that failed
1597 - got: the actual output
1599 def __init__(self
, test
, example
, got
):
1601 self
.example
= example
1605 return str(self
.test
)
1607 class UnexpectedException(Exception):
1608 """A DocTest example has encountered an unexpected exception
1610 The exception instance has variables:
1612 - test: the DocTest object being run
1614 - excample: the Example object that failed
1616 - exc_info: the exception info
1618 def __init__(self
, test
, example
, exc_info
):
1620 self
.example
= example
1621 self
.exc_info
= exc_info
1624 return str(self
.test
)
1626 class DebugRunner(DocTestRunner
):
1627 r
"""Run doc tests but raise an exception as soon as there is a failure.
1629 If an unexpected exception occurs, an UnexpectedException is raised.
1630 It contains the test, the example, and the original exception:
1632 >>> runner = DebugRunner(verbose=False)
1633 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
1634 ... {}, 'foo', 'foo.py', 0)
1636 ... runner.run(test)
1637 ... except UnexpectedException, failure:
1640 >>> failure.test is test
1643 >>> failure.example.want
1646 >>> exc_info = failure.exc_info
1647 >>> raise exc_info[0], exc_info[1], exc_info[2]
1648 Traceback (most recent call last):
1652 We wrap the original exception to give the calling application
1653 access to the test and example information.
1655 If the output doesn't match, then a DocTestFailure is raised:
1657 >>> test = DocTestParser().get_doctest('''
1661 ... ''', {}, 'foo', 'foo.py', 0)
1664 ... runner.run(test)
1665 ... except DocTestFailure, failure:
1668 DocTestFailure objects provide access to the test:
1670 >>> failure.test is test
1673 As well as to the example:
1675 >>> failure.example.want
1678 and the actual output:
1683 If a failure or error occurs, the globals are left intact:
1685 >>> del test.globs['__builtins__']
1689 >>> test = DocTestParser().get_doctest('''
1691 ... >>> raise KeyError
1692 ... ''', {}, 'foo', 'foo.py', 0)
1694 >>> runner.run(test)
1695 Traceback (most recent call last):
1697 UnexpectedException: <DocTest foo from foo.py:0 (2 examples)>
1699 >>> del test.globs['__builtins__']
1703 But the globals are cleared if there is no error:
1705 >>> test = DocTestParser().get_doctest('''
1707 ... ''', {}, 'foo', 'foo.py', 0)
1709 >>> runner.run(test)
1717 def run(self
, test
, compileflags
=None, out
=None, clear_globs
=True):
1718 r
= DocTestRunner
.run(self
, test
, compileflags
, out
, False)
1723 def report_unexpected_exception(self
, out
, test
, example
, exc_info
):
1724 raise UnexpectedException(test
, example
, exc_info
)
1726 def report_failure(self
, out
, test
, example
, got
):
1727 raise DocTestFailure(test
, example
, got
)
1729 ######################################################################
1730 ## 6. Test Functions
1731 ######################################################################
1732 # These should be backwards compatible.
1734 # For backward compatibility, a global instance of a DocTestRunner
1735 # class, updated by testmod.
1738 def testmod(m
=None, name
=None, globs
=None, verbose
=None, isprivate
=None,
1739 report
=True, optionflags
=0, extraglobs
=None,
1740 raise_on_error
=False, exclude_empty
=False):
1741 """m=None, name=None, globs=None, verbose=None, isprivate=None,
1742 report=True, optionflags=0, extraglobs=None, raise_on_error=False,
1745 Test examples in docstrings in functions and classes reachable
1746 from module m (or the current module if m is not supplied), starting
1747 with m.__doc__. Unless isprivate is specified, private names
1750 Also test examples reachable from dict m.__test__ if it exists and is
1751 not None. m.__test__ maps names to functions, classes and strings;
1752 function and class docstrings are tested even if the name is private;
1753 strings are tested directly, as if they were docstrings.
1755 Return (#failures, #tests).
1757 See doctest.__doc__ for an overview.
1759 Optional keyword arg "name" gives the name of the module; by default
1762 Optional keyword arg "globs" gives a dict to be used as the globals
1763 when executing examples; by default, use m.__dict__. A copy of this
1764 dict is actually used for each docstring, so that each docstring's
1765 examples start with a clean slate.
1767 Optional keyword arg "extraglobs" gives a dictionary that should be
1768 merged into the globals that are used to execute examples. By
1769 default, no extra globals are used. This is new in 2.4.
1771 Optional keyword arg "verbose" prints lots of stuff if true, prints
1772 only failures if false; by default, it's true iff "-v" is in sys.argv.
1774 Optional keyword arg "report" prints a summary at the end when true,
1775 else prints nothing at the end. In verbose mode, the summary is
1776 detailed, else very brief (in fact, empty if all tests passed).
1778 Optional keyword arg "optionflags" or's together module constants,
1779 and defaults to 0. This is new in 2.3. Possible values (see the
1782 DONT_ACCEPT_TRUE_FOR_1
1783 DONT_ACCEPT_BLANKLINE
1784 NORMALIZE_WHITESPACE
1786 IGNORE_EXCEPTION_DETAIL
1790 REPORT_ONLY_FIRST_FAILURE
1792 Optional keyword arg "raise_on_error" raises an exception on the
1793 first unexpected exception or failure. This allows failures to be
1794 post-mortem debugged.
1796 Deprecated in Python 2.4:
1797 Optional keyword arg "isprivate" specifies a function used to
1798 determine whether a name is private. The default function is
1799 treat all functions as public. Optionally, "isprivate" can be
1800 set to doctest.is_private to skip over functions marked as private
1801 using the underscore naming convention; see its docs for details.
1803 Advanced tomfoolery: testmod runs methods of a local instance of
1804 class doctest.Tester, then merges the results into (or creates)
1805 global Tester instance doctest.master. Methods of doctest.master
1806 can be called directly too, if you want to do something unusual.
1807 Passing report=0 to testmod is especially useful then, to delay
1808 displaying a summary. Invoke doctest.master.summarize(verbose)
1809 when you're done fiddling.
1813 if isprivate
is not None:
1814 warnings
.warn("the isprivate argument is deprecated; "
1815 "examine DocTestFinder.find() lists instead",
1818 # If no module was given, then use __main__.
1820 # DWA - m will still be None if this wasn't invoked from the command
1821 # line, in which case the following TypeError is about as good an error
1822 # as we should expect
1823 m
= sys
.modules
.get('__main__')
1825 # Check that we were actually given a module.
1826 if not inspect
.ismodule(m
):
1827 raise TypeError("testmod: module required; %r" % (m
,))
1829 # If no name was given, then use the module's name.
1833 # Find, parse, and run all tests in the given module.
1834 finder
= DocTestFinder(_namefilter
=isprivate
, exclude_empty
=exclude_empty
)
1837 runner
= DebugRunner(verbose
=verbose
, optionflags
=optionflags
)
1839 runner
= DocTestRunner(verbose
=verbose
, optionflags
=optionflags
)
1841 for test
in finder
.find(m
, name
, globs
=globs
, extraglobs
=extraglobs
):
1850 master
.merge(runner
)
1852 return runner
.failures
, runner
.tries
1854 def testfile(filename
, module_relative
=True, name
=None, package
=None,
1855 globs
=None, verbose
=None, report
=True, optionflags
=0,
1856 extraglobs
=None, raise_on_error
=False, parser
=DocTestParser()):
1858 Test examples in the given file. Return (#failures, #tests).
1860 Optional keyword arg "module_relative" specifies how filenames
1861 should be interpreted:
1863 - If "module_relative" is True (the default), then "filename"
1864 specifies a module-relative path. By default, this path is
1865 relative to the calling module's directory; but if the
1866 "package" argument is specified, then it is relative to that
1867 package. To ensure os-independence, "filename" should use
1868 "/" characters to separate path segments, and should not
1869 be an absolute path (i.e., it may not begin with "/").
1871 - If "module_relative" is False, then "filename" specifies an
1872 os-specific path. The path may be absolute or relative (to
1873 the current working directory).
1875 Optional keyword arg "name" gives the name of the test; by default
1876 use the file's basename.
1878 Optional keyword argument "package" is a Python package or the
1879 name of a Python package whose directory should be used as the
1880 base directory for a module relative filename. If no package is
1881 specified, then the calling module's directory is used as the base
1882 directory for module relative filenames. It is an error to
1883 specify "package" if "module_relative" is False.
1885 Optional keyword arg "globs" gives a dict to be used as the globals
1886 when executing examples; by default, use {}. A copy of this dict
1887 is actually used for each docstring, so that each docstring's
1888 examples start with a clean slate.
1890 Optional keyword arg "extraglobs" gives a dictionary that should be
1891 merged into the globals that are used to execute examples. By
1892 default, no extra globals are used.
1894 Optional keyword arg "verbose" prints lots of stuff if true, prints
1895 only failures if false; by default, it's true iff "-v" is in sys.argv.
1897 Optional keyword arg "report" prints a summary at the end when true,
1898 else prints nothing at the end. In verbose mode, the summary is
1899 detailed, else very brief (in fact, empty if all tests passed).
1901 Optional keyword arg "optionflags" or's together module constants,
1902 and defaults to 0. Possible values (see the docs for details):
1904 DONT_ACCEPT_TRUE_FOR_1
1905 DONT_ACCEPT_BLANKLINE
1906 NORMALIZE_WHITESPACE
1908 IGNORE_EXCEPTION_DETAIL
1912 REPORT_ONLY_FIRST_FAILURE
1914 Optional keyword arg "raise_on_error" raises an exception on the
1915 first unexpected exception or failure. This allows failures to be
1916 post-mortem debugged.
1918 Optional keyword arg "parser" specifies a DocTestParser (or
1919 subclass) that should be used to extract tests from the files.
1921 Advanced tomfoolery: testmod runs methods of a local instance of
1922 class doctest.Tester, then merges the results into (or creates)
1923 global Tester instance doctest.master. Methods of doctest.master
1924 can be called directly too, if you want to do something unusual.
1925 Passing report=0 to testmod is especially useful then, to delay
1926 displaying a summary. Invoke doctest.master.summarize(verbose)
1927 when you're done fiddling.
1931 if package
and not module_relative
:
1932 raise ValueError("Package may only be specified for module-"
1935 # Relativize the path
1937 package
= _normalize_module(package
)
1938 filename
= _module_relative_path(package
, filename
)
1940 # If no name was given, then use the file's name.
1942 name
= os
.path
.basename(filename
)
1944 # Assemble the globals.
1948 globs
= globs
.copy()
1949 if extraglobs
is not None:
1950 globs
.update(extraglobs
)
1953 runner
= DebugRunner(verbose
=verbose
, optionflags
=optionflags
)
1955 runner
= DocTestRunner(verbose
=verbose
, optionflags
=optionflags
)
1957 # Read the file, convert it to a test, and run it.
1958 s
= open(filename
).read()
1959 test
= parser
.get_doctest(s
, globs
, name
, filename
, 0)
1968 master
.merge(runner
)
1970 return runner
.failures
, runner
.tries
1972 def run_docstring_examples(f
, globs
, verbose
=False, name
="NoName",
1973 compileflags
=None, optionflags
=0):
1975 Test examples in the given object's docstring (`f`), using `globs`
1976 as globals. Optional argument `name` is used in failure messages.
1977 If the optional argument `verbose` is true, then generate output
1978 even if there are no failures.
1980 `compileflags` gives the set of flags that should be used by the
1981 Python compiler when running the examples. If not specified, then
1982 it will default to the set of future-import flags that apply to
1985 Optional keyword arg `optionflags` specifies options for the
1986 testing and output. See the documentation for `testmod` for more
1989 # Find, parse, and run all tests in the given module.
1990 finder
= DocTestFinder(verbose
=verbose
, recurse
=False)
1991 runner
= DocTestRunner(verbose
=verbose
, optionflags
=optionflags
)
1992 for test
in finder
.find(f
, name
, globs
=globs
):
1993 runner
.run(test
, compileflags
=compileflags
)
1995 ######################################################################
1997 ######################################################################
1998 # This is provided only for backwards compatibility. It's not
1999 # actually used in any way.
2002 def __init__(self
, mod
=None, globs
=None, verbose
=None,
2003 isprivate
=None, optionflags
=0):
2005 warnings
.warn("class Tester is deprecated; "
2006 "use class doctest.DocTestRunner instead",
2007 DeprecationWarning, stacklevel
=2)
2008 if mod
is None and globs
is None:
2009 raise TypeError("Tester.__init__: must specify mod or globs")
2010 if mod
is not None and not inspect
.ismodule(mod
):
2011 raise TypeError("Tester.__init__: mod must be a module; %r" %
2014 globs
= mod
.__dict
__
2017 self
.verbose
= verbose
2018 self
.isprivate
= isprivate
2019 self
.optionflags
= optionflags
2020 self
.testfinder
= DocTestFinder(_namefilter
=isprivate
)
2021 self
.testrunner
= DocTestRunner(verbose
=verbose
,
2022 optionflags
=optionflags
)
2024 def runstring(self
, s
, name
):
2025 test
= DocTestParser().get_doctest(s
, self
.globs
, name
, None, None)
2027 print "Running string", name
2028 (f
,t
) = self
.testrunner
.run(test
)
2030 print f
, "of", t
, "examples failed in string", name
2033 def rundoc(self
, object, name
=None, module
=None):
2035 tests
= self
.testfinder
.find(object, name
, module
=module
,
2038 (f2
, t2
) = self
.testrunner
.run(test
)
2039 (f
,t
) = (f
+f2
, t
+t2
)
2042 def rundict(self
, d
, name
, module
=None):
2044 m
= new
.module(name
)
2045 m
.__dict
__.update(d
)
2048 return self
.rundoc(m
, name
, module
)
2050 def run__test__(self
, d
, name
):
2052 m
= new
.module(name
)
2054 return self
.rundoc(m
, name
)
2056 def summarize(self
, verbose
=None):
2057 return self
.testrunner
.summarize(verbose
)
2059 def merge(self
, other
):
2060 self
.testrunner
.merge(other
.testrunner
)
2062 ######################################################################
2063 ## 8. Unittest Support
2064 ######################################################################
2066 _unittest_reportflags
= 0
2068 def set_unittest_reportflags(flags
):
2069 """Sets the unittest option flags.
2071 The old flag is returned so that a runner could restore the old
2072 value if it wished to:
2075 >>> old = doctest._unittest_reportflags
2076 >>> doctest.set_unittest_reportflags(REPORT_NDIFF |
2077 ... REPORT_ONLY_FIRST_FAILURE) == old
2080 >>> doctest._unittest_reportflags == (REPORT_NDIFF |
2081 ... REPORT_ONLY_FIRST_FAILURE)
2084 Only reporting flags can be set:
2086 >>> doctest.set_unittest_reportflags(ELLIPSIS)
2087 Traceback (most recent call last):
2089 ValueError: ('Only reporting flags allowed', 8)
2091 >>> doctest.set_unittest_reportflags(old) == (REPORT_NDIFF |
2092 ... REPORT_ONLY_FIRST_FAILURE)
2095 global _unittest_reportflags
2097 if (flags
& REPORTING_FLAGS
) != flags
:
2098 raise ValueError("Only reporting flags allowed", flags
)
2099 old
= _unittest_reportflags
2100 _unittest_reportflags
= flags
2104 class DocTestCase(unittest
.TestCase
):
2106 def __init__(self
, test
, optionflags
=0, setUp
=None, tearDown
=None,
2109 unittest
.TestCase
.__init
__(self
)
2110 self
._dt
_optionflags
= optionflags
2111 self
._dt
_checker
= checker
2112 self
._dt
_test
= test
2113 self
._dt
_setUp
= setUp
2114 self
._dt
_tearDown
= tearDown
2117 test
= self
._dt
_test
2119 if self
._dt
_setUp
is not None:
2120 self
._dt
_setUp
(test
)
2123 test
= self
._dt
_test
2125 if self
._dt
_tearDown
is not None:
2126 self
._dt
_tearDown
(test
)
2131 test
= self
._dt
_test
2134 optionflags
= self
._dt
_optionflags
2136 if not (optionflags
& REPORTING_FLAGS
):
2137 # The option flags don't include any reporting flags,
2138 # so add the default reporting flags
2139 optionflags |
= _unittest_reportflags
2141 runner
= DocTestRunner(optionflags
=optionflags
,
2142 checker
=self
._dt
_checker
, verbose
=False)
2145 runner
.DIVIDER
= "-"*70
2146 failures
, tries
= runner
.run(
2147 test
, out
=new
.write
, clear_globs
=False)
2152 raise self
.failureException(self
.format_failure(new
.getvalue()))
2154 def format_failure(self
, err
):
2155 test
= self
._dt
_test
2156 if test
.lineno
is None:
2157 lineno
= 'unknown line number'
2159 lineno
= '%s' % test
.lineno
2160 lname
= '.'.join(test
.name
.split('.')[-1:])
2161 return ('Failed doctest test for %s\n'
2162 ' File "%s", line %s, in %s\n\n%s'
2163 % (test
.name
, test
.filename
, lineno
, lname
, err
)
2167 r
"""Run the test case without results and without catching exceptions
2169 The unit test framework includes a debug method on test cases
2170 and test suites to support post-mortem debugging. The test code
2171 is run in such a way that errors are not caught. This way a
2172 caller can catch the errors and initiate post-mortem debugging.
2174 The DocTestCase provides a debug method that raises
2175 UnexpectedException errors if there is an unexepcted
2178 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
2179 ... {}, 'foo', 'foo.py', 0)
2180 >>> case = DocTestCase(test)
2183 ... except UnexpectedException, failure:
2186 The UnexpectedException contains the test, the example, and
2187 the original exception:
2189 >>> failure.test is test
2192 >>> failure.example.want
2195 >>> exc_info = failure.exc_info
2196 >>> raise exc_info[0], exc_info[1], exc_info[2]
2197 Traceback (most recent call last):
2201 If the output doesn't match, then a DocTestFailure is raised:
2203 >>> test = DocTestParser().get_doctest('''
2207 ... ''', {}, 'foo', 'foo.py', 0)
2208 >>> case = DocTestCase(test)
2212 ... except DocTestFailure, failure:
2215 DocTestFailure objects provide access to the test:
2217 >>> failure.test is test
2220 As well as to the example:
2222 >>> failure.example.want
2225 and the actual output:
2233 runner
= DebugRunner(optionflags
=self
._dt
_optionflags
,
2234 checker
=self
._dt
_checker
, verbose
=False)
2235 runner
.run(self
._dt
_test
)
2239 return self
._dt
_test
.name
2242 name
= self
._dt
_test
.name
.split('.')
2243 return "%s (%s)" % (name
[-1], '.'.join(name
[:-1]))
2247 def shortDescription(self
):
2248 return "Doctest: " + self
._dt
_test
.name
2250 def DocTestSuite(module
=None, globs
=None, extraglobs
=None, test_finder
=None,
2253 Convert doctest tests for a module to a unittest test suite.
2255 This converts each documentation string in a module that
2256 contains doctest tests to a unittest test case. If any of the
2257 tests in a doc string fail, then the test case fails. An exception
2258 is raised showing the name of the file containing the test and a
2259 (sometimes approximate) line number.
2261 The `module` argument provides the module to be tested. The argument
2262 can be either a module or a module name.
2264 If no argument is given, the calling module is used.
2266 A number of options may be provided as keyword arguments:
2269 A set-up function. This is called before running the
2270 tests in each file. The setUp function will be passed a DocTest
2271 object. The setUp function can access the test globals as the
2272 globs attribute of the test passed.
2275 A tear-down function. This is called after running the
2276 tests in each file. The tearDown function will be passed a DocTest
2277 object. The tearDown function can access the test globals as the
2278 globs attribute of the test passed.
2281 A dictionary containing initial global variables for the tests.
2284 A set of doctest option flags expressed as an integer.
2287 if test_finder
is None:
2288 test_finder
= DocTestFinder()
2290 module
= _normalize_module(module
)
2291 tests
= test_finder
.find(module
, globs
=globs
, extraglobs
=extraglobs
)
2293 globs
= module
.__dict
__
2295 # Why do we want to do this? Because it reveals a bug that might
2296 # otherwise be hidden.
2297 raise ValueError(module
, "has no tests")
2300 suite
= unittest
.TestSuite()
2302 if len(test
.examples
) == 0:
2304 if not test
.filename
:
2305 filename
= module
.__file
__
2306 if filename
[-4:] in (".pyc", ".pyo"):
2307 filename
= filename
[:-1]
2308 test
.filename
= filename
2309 suite
.addTest(DocTestCase(test
, **options
))
2313 class DocFileCase(DocTestCase
):
2316 return '_'.join(self
._dt
_test
.name
.split('.'))
2319 return self
._dt
_test
.filename
2322 def format_failure(self
, err
):
2323 return ('Failed doctest test for %s\n File "%s", line 0\n\n%s'
2324 % (self
._dt
_test
.name
, self
._dt
_test
.filename
, err
)
2327 def DocFileTest(path
, module_relative
=True, package
=None,
2328 globs
=None, parser
=DocTestParser(), **options
):
2332 globs
= globs
.copy()
2334 if package
and not module_relative
:
2335 raise ValueError("Package may only be specified for module-"
2338 # Relativize the path.
2340 package
= _normalize_module(package
)
2341 path
= _module_relative_path(package
, path
)
2342 if "__file__" not in globs
:
2343 globs
["__file__"] = path
2345 # Find the file and read it.
2346 name
= os
.path
.basename(path
)
2347 doc
= open(path
).read()
2349 # Convert it to a test, and wrap it in a DocFileCase.
2350 test
= parser
.get_doctest(doc
, globs
, name
, path
, 0)
2351 return DocFileCase(test
, **options
)
2353 def DocFileSuite(*paths
, **kw
):
2354 """A unittest suite for one or more doctest files.
2356 The path to each doctest file is given as a string; the
2357 interpretation of that string depends on the keyword argument
2360 A number of options may be provided as keyword arguments:
2363 If "module_relative" is True, then the given file paths are
2364 interpreted as os-independent module-relative paths. By
2365 default, these paths are relative to the calling module's
2366 directory; but if the "package" argument is specified, then
2367 they are relative to that package. To ensure os-independence,
2368 "filename" should use "/" characters to separate path
2369 segments, and may not be an absolute path (i.e., it may not
2372 If "module_relative" is False, then the given file paths are
2373 interpreted as os-specific paths. These paths may be absolute
2374 or relative (to the current working directory).
2377 A Python package or the name of a Python package whose directory
2378 should be used as the base directory for module relative paths.
2379 If "package" is not specified, then the calling module's
2380 directory is used as the base directory for module relative
2381 filenames. It is an error to specify "package" if
2382 "module_relative" is False.
2385 A set-up function. This is called before running the
2386 tests in each file. The setUp function will be passed a DocTest
2387 object. The setUp function can access the test globals as the
2388 globs attribute of the test passed.
2391 A tear-down function. This is called after running the
2392 tests in each file. The tearDown function will be passed a DocTest
2393 object. The tearDown function can access the test globals as the
2394 globs attribute of the test passed.
2397 A dictionary containing initial global variables for the tests.
2400 A set of doctest option flags expressed as an integer.
2403 A DocTestParser (or subclass) that should be used to extract
2404 tests from the files.
2406 suite
= unittest
.TestSuite()
2408 # We do this here so that _normalize_module is called at the right
2409 # level. If it were called in DocFileTest, then this function
2410 # would be the caller and we might guess the package incorrectly.
2411 if kw
.get('module_relative', True):
2412 kw
['package'] = _normalize_module(kw
.get('package'))
2415 suite
.addTest(DocFileTest(path
, **kw
))
2419 ######################################################################
2420 ## 9. Debugging Support
2421 ######################################################################
2423 def script_from_examples(s
):
2424 r
"""Extract script from text with examples.
2426 Converts text with examples to a Python script. Example input is
2427 converted to regular code. Example output and all other words
2428 are converted to comments:
2431 ... Here are examples of simple math.
2433 ... Python has super accurate integer addition
2438 ... And very friendly error messages:
2445 ... You can use logic if you want:
2455 >>> print script_from_examples(text)
2456 # Here are examples of simple math.
2458 # Python has super accurate integer addition
2464 # And very friendly error messages:
2472 # You can use logic if you want:
2482 for piece
in DocTestParser().parse(s
):
2483 if isinstance(piece
, Example
):
2484 # Add the example's source code (strip trailing NL)
2485 output
.append(piece
.source
[:-1])
2486 # Add the expected output:
2489 output
.append('# Expected:')
2490 output
+= ['## '+l
for l
in want
.split('\n')[:-1]]
2492 # Add non-example text.
2493 output
+= [_comment_line(l
)
2494 for l
in piece
.split('\n')[:-1]]
2496 # Trim junk on both ends.
2497 while output
and output
[-1] == '#':
2499 while output
and output
[0] == '#':
2501 # Combine the output, and return it.
2502 # Add a courtesy newline to prevent exec from choking (see bug #1172785)
2503 return '\n'.join(output
) + '\n'
2505 def testsource(module
, name
):
2506 """Extract the test sources from a doctest docstring as a script.
2508 Provide the module (or dotted name of the module) containing the
2509 test to be debugged and the name (within the module) of the object
2510 with the doc string with tests to be debugged.
2512 module
= _normalize_module(module
)
2513 tests
= DocTestFinder().find(module
)
2514 test
= [t
for t
in tests
if t
.name
== name
]
2516 raise ValueError(name
, "not found in tests")
2518 testsrc
= script_from_examples(test
.docstring
)
2521 def debug_src(src
, pm
=False, globs
=None):
2522 """Debug a single doctest docstring, in argument `src`'"""
2523 testsrc
= script_from_examples(src
)
2524 debug_script(testsrc
, pm
, globs
)
2526 def debug_script(src
, pm
=False, globs
=None):
2527 "Debug a test script. `src` is the script, as a string."
2530 # Note that tempfile.NameTemporaryFile() cannot be used. As the
2531 # docs say, a file so created cannot be opened by name a second time
2532 # on modern Windows boxes, and execfile() needs to open it.
2533 srcfilename
= tempfile
.mktemp(".py", "doctestdebug")
2534 f
= open(srcfilename
, 'w')
2540 globs
= globs
.copy()
2546 execfile(srcfilename
, globs
, globs
)
2548 print sys
.exc_info()[1]
2549 pdb
.post_mortem(sys
.exc_info()[2])
2551 # Note that %r is vital here. '%s' instead can, e.g., cause
2552 # backslashes to get treated as metacharacters on Windows.
2553 pdb
.run("execfile(%r)" % srcfilename
, globs
, globs
)
2556 os
.remove(srcfilename
)
2558 def debug(module
, name
, pm
=False):
2559 """Debug a single doctest docstring.
2561 Provide the module (or dotted name of the module) containing the
2562 test to be debugged and the name (within the module) of the object
2563 with the docstring with tests to be debugged.
2565 module
= _normalize_module(module
)
2566 testsrc
= testsource(module
, name
)
2567 debug_script(testsrc
, pm
, module
.__dict
__)
2569 ######################################################################
2570 ## 10. Example Usage
2571 ######################################################################
2574 A pointless class, for sanity-checking of docstring testing.
2580 >>> _TestClass(13).get() + _TestClass(-12).get()
2582 >>> hex(_TestClass(13).square().get())
2586 def __init__(self
, val
):
2587 """val -> _TestClass object with associated value val.
2589 >>> t = _TestClass(123)
2597 """square() -> square TestClass's associated value
2599 >>> _TestClass(13).square().get()
2603 self
.val
= self
.val
** 2
2607 """get() -> return TestClass's associated value.
2609 >>> x = _TestClass(-42)
2616 __test__
= {"_TestClass": _TestClass
,
2618 Example of a string object, searched as-is.
2624 "bool-int equivalence": r
"""
2625 In 2.2, boolean expressions displayed
2626 0 or 1. By default, we still accept
2627 them. This can be disabled by passing
2628 DONT_ACCEPT_TRUE_FOR_1 to the new
2629 optionflags argument.
2641 Blank lines can be marked with <BLANKLINE>:
2642 >>> print 'foo\n\nbar\n'
2650 If the ellipsis flag is used, then '...' can be used to
2651 elide substrings in the desired output:
2652 >>> print range(1000) #doctest: +ELLIPSIS
2656 "whitespace normalization": r
"""
2657 If the whitespace normalization flag is used, then
2658 differences in whitespace are ignored.
2659 >>> print range(30) #doctest: +NORMALIZE_WHITESPACE
2660 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
2661 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,
2667 r
= unittest
.TextTestRunner()
2668 r
.run(DocTestSuite())
2670 if __name__
== "__main__":