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
67 # 2. Example & DocTest
78 'UnexpectedException',
83 'run_docstring_examples',
89 'set_unittest_reportflags',
90 # 9. Debugging Support
91 'script_from_examples',
99 import sys
, traceback
, inspect
, linecache
, os
, re
, types
100 import unittest
, difflib
, pdb
, tempfile
102 from StringIO
import StringIO
104 # Don't whine about the deprecated is_private function in this
106 warnings
.filterwarnings("ignore", "is_private", DeprecationWarning,
109 # There are 4 basic classes:
110 # - Example: a <source, want> pair, plus an intra-docstring line number.
111 # - DocTest: a collection of examples, parsed from a docstring, plus
112 # info about where the docstring came from (name, filename, lineno).
113 # - DocTestFinder: extracts DocTests from a given object's docstring and
114 # its contained objects' docstrings.
115 # - DocTestRunner: runs DocTest cases, and accumulates statistics.
117 # So the basic picture is:
120 # +------+ +---------+ +-------+
121 # |object| --DocTestFinder-> | DocTest | --DocTestRunner-> |results|
122 # +------+ +---------+ +-------+
130 OPTIONFLAGS_BY_NAME
= {}
131 def register_optionflag(name
):
132 # Create a new flag unless `name` is already known.
133 return OPTIONFLAGS_BY_NAME
.setdefault(name
, 1 << len(OPTIONFLAGS_BY_NAME
))
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 SKIP
= register_optionflag('SKIP')
140 IGNORE_EXCEPTION_DETAIL
= register_optionflag('IGNORE_EXCEPTION_DETAIL')
142 COMPARISON_FLAGS
= (DONT_ACCEPT_TRUE_FOR_1 |
143 DONT_ACCEPT_BLANKLINE |
144 NORMALIZE_WHITESPACE |
147 IGNORE_EXCEPTION_DETAIL
)
149 REPORT_UDIFF
= register_optionflag('REPORT_UDIFF')
150 REPORT_CDIFF
= register_optionflag('REPORT_CDIFF')
151 REPORT_NDIFF
= register_optionflag('REPORT_NDIFF')
152 REPORT_ONLY_FIRST_FAILURE
= register_optionflag('REPORT_ONLY_FIRST_FAILURE')
154 REPORTING_FLAGS
= (REPORT_UDIFF |
157 REPORT_ONLY_FIRST_FAILURE
)
159 # Special string markers for use in `want` strings:
160 BLANKLINE_MARKER
= '<BLANKLINE>'
161 ELLIPSIS_MARKER
= '...'
163 ######################################################################
165 ######################################################################
166 # 1. Utility Functions
167 # 2. Example & DocTest -- store test cases
168 # 3. DocTest Parser -- extracts examples from strings
169 # 4. DocTest Finder -- extracts test cases from objects
170 # 5. DocTest Runner -- runs test cases
171 # 6. Test Functions -- convenient wrappers for testing
172 # 7. Tester Class -- for backwards compatibility
173 # 8. Unittest Support
174 # 9. Debugging Support
177 ######################################################################
178 ## 1. Utility Functions
179 ######################################################################
181 def is_private(prefix
, base
):
182 """prefix, base -> true iff name prefix + "." + base is "private".
184 Prefix may be an empty string, and base does not contain a period.
185 Prefix is ignored (although functions you write conforming to this
186 protocol may make use of it).
187 Return true iff base begins with an (at least one) underscore, but
188 does not both begin and end with (at least) two underscores.
190 >>> is_private("a.b", "my_func")
192 >>> is_private("____", "_my_func")
194 >>> is_private("someclass", "__init__")
196 >>> is_private("sometypo", "__init_")
198 >>> is_private("x.y.z", "_")
200 >>> is_private("_x.y.z", "__")
202 >>> is_private("", "") # senseless but consistent
205 warnings
.warn("is_private is deprecated; it wasn't useful; "
206 "examine DocTestFinder.find() lists instead",
207 DeprecationWarning, stacklevel
=2)
208 return base
[:1] == "_" and not base
[:2] == "__" == base
[-2:]
210 def _extract_future_flags(globs
):
212 Return the compiler-flags associated with the future features that
213 have been imported into the given namespace (globs).
216 for fname
in __future__
.all_feature_names
:
217 feature
= globs
.get(fname
, None)
218 if feature
is getattr(__future__
, fname
):
219 flags |
= feature
.compiler_flag
222 def _normalize_module(module
, depth
=2):
224 Return the module specified by `module`. In particular:
225 - If `module` is a module, then return module.
226 - If `module` is a string, then import and return the
227 module with that name.
228 - If `module` is None, then return the calling module.
229 The calling module is assumed to be the module of
230 the stack frame at the given depth in the call stack.
232 if inspect
.ismodule(module
):
234 elif isinstance(module
, (str, unicode)):
235 return __import__(module
, globals(), locals(), ["*"])
237 return sys
.modules
[sys
._getframe
(depth
).f_globals
['__name__']]
239 raise TypeError("Expected a module, string, or None")
241 def _load_testfile(filename
, package
, module_relative
):
243 package
= _normalize_module(package
, 3)
244 filename
= _module_relative_path(package
, filename
)
245 if hasattr(package
, '__loader__'):
246 if hasattr(package
.__loader
__, 'get_data'):
247 return package
.__loader
__.get_data(filename
), filename
248 return open(filename
).read(), filename
250 def _indent(s
, indent
=4):
252 Add the given number of space characters to the beginning every
253 non-blank line in `s`, and return the result.
255 # This regexp matches the start of non-blank lines:
256 return re
.sub('(?m)^(?!$)', indent
*' ', s
)
258 def _exception_traceback(exc_info
):
260 Return a string containing a traceback message for the given
261 exc_info tuple (as returned by sys.exc_info()).
263 # Get a traceback message.
265 exc_type
, exc_val
, exc_tb
= exc_info
266 traceback
.print_exception(exc_type
, exc_val
, exc_tb
, file=excout
)
267 return excout
.getvalue()
269 # Override some StringIO methods.
270 class _SpoofOut(StringIO
):
272 result
= StringIO
.getvalue(self
)
273 # If anything at all was written, make sure there's a trailing
274 # newline. There's no way for the expected output to indicate
275 # that a trailing newline is missing.
276 if result
and not result
.endswith("\n"):
278 # Prevent softspace from screwing up the next test case, in
279 # case they used print with a trailing comma in an example.
280 if hasattr(self
, "softspace"):
284 def truncate(self
, size
=None):
285 StringIO
.truncate(self
, size
)
286 if hasattr(self
, "softspace"):
289 # Worst-case linear-time ellipsis matching.
290 def _ellipsis_match(want
, got
):
292 Essentially the only subtle case:
293 >>> _ellipsis_match('aa...aa', 'aaa')
296 if ELLIPSIS_MARKER
not in want
:
299 # Find "the real" strings.
300 ws
= want
.split(ELLIPSIS_MARKER
)
303 # Deal with exact matches possibly needed at one or both ends.
304 startpos
, endpos
= 0, len(got
)
306 if w
: # starts with exact match
307 if got
.startswith(w
):
313 if w
: # ends with exact match
320 if startpos
> endpos
:
321 # Exact end matches required more characters than we have, as in
322 # _ellipsis_match('aa...aa', 'aaa')
325 # For the rest, we only need to find the leftmost non-overlapping
326 # match for each piece. If there's no overall match that way alone,
327 # there's no overall match period.
329 # w may be '' at times, if there are consecutive ellipses, or
330 # due to an ellipsis at the start or end of `want`. That's OK.
331 # Search for an empty string succeeds, and doesn't change startpos.
332 startpos
= got
.find(w
, startpos
, endpos
)
339 def _comment_line(line
):
340 "Return a commented form of the given line"
347 class _OutputRedirectingPdb(pdb
.Pdb
):
349 A specialized version of the python debugger that redirects stdout
350 to a given stream when interacting with the user. Stdout is *not*
351 redirected when traced code is executed.
353 def __init__(self
, out
):
355 pdb
.Pdb
.__init
__(self
, stdout
=out
)
357 def trace_dispatch(self
, *args
):
358 # Redirect stdout to the given stream.
359 save_stdout
= sys
.stdout
360 sys
.stdout
= self
.__out
361 # Call Pdb's trace dispatch method.
363 return pdb
.Pdb
.trace_dispatch(self
, *args
)
365 sys
.stdout
= save_stdout
367 # [XX] Normalize with respect to os.path.pardir?
368 def _module_relative_path(module
, path
):
369 if not inspect
.ismodule(module
):
370 raise TypeError, 'Expected a module: %r' % module
371 if path
.startswith('/'):
372 raise ValueError, 'Module-relative files may not have absolute paths'
374 # Find the base directory for the path.
375 if hasattr(module
, '__file__'):
376 # A normal module/package
377 basedir
= os
.path
.split(module
.__file
__)[0]
378 elif module
.__name
__ == '__main__':
379 # An interactive session.
380 if len(sys
.argv
)>0 and sys
.argv
[0] != '':
381 basedir
= os
.path
.split(sys
.argv
[0])[0]
385 # A module w/o __file__ (this includes builtins)
386 raise ValueError("Can't resolve paths relative to the module " +
387 module
+ " (it has no __file__)")
389 # Combine the base directory and the path.
390 return os
.path
.join(basedir
, *(path
.split('/')))
392 ######################################################################
393 ## 2. Example & DocTest
394 ######################################################################
395 ## - An "example" is a <source, want> pair, where "source" is a
396 ## fragment of source code, and "want" is the expected output for
397 ## "source." The Example class also includes information about
398 ## where the example was extracted from.
400 ## - A "doctest" is a collection of examples, typically extracted from
401 ## a string (such as an object's docstring). The DocTest class also
402 ## includes information about where the string was extracted from.
406 A single doctest example, consisting of source code and expected
407 output. `Example` defines the following attributes:
409 - source: A single Python statement, always ending with a newline.
410 The constructor adds a newline if needed.
412 - want: The expected output from running the source code (either
413 from stdout, or a traceback in case of exception). `want` ends
414 with a newline unless it's empty, in which case it's an empty
415 string. The constructor adds a newline if needed.
417 - exc_msg: The exception message generated by the example, if
418 the example is expected to generate an exception; or `None` if
419 it is not expected to generate an exception. This exception
420 message is compared against the return value of
421 `traceback.format_exception_only()`. `exc_msg` ends with a
422 newline unless it's `None`. The constructor adds a newline
425 - lineno: The line number within the DocTest string containing
426 this Example where the Example begins. This line number is
427 zero-based, with respect to the beginning of the DocTest.
429 - indent: The example's indentation in the DocTest string.
430 I.e., the number of space characters that preceed the
431 example's first prompt.
433 - options: A dictionary mapping from option flags to True or
434 False, which is used to override default options for this
435 example. Any option flags not contained in this dictionary
436 are left at their default value (as specified by the
437 DocTestRunner's optionflags). By default, no options are set.
439 def __init__(self
, source
, want
, exc_msg
=None, lineno
=0, indent
=0,
442 if not source
.endswith('\n'):
444 if want
and not want
.endswith('\n'):
446 if exc_msg
is not None and not exc_msg
.endswith('\n'):
453 if options
is None: options
= {}
454 self
.options
= options
455 self
.exc_msg
= exc_msg
459 A collection of doctest examples that should be run in a single
460 namespace. Each `DocTest` defines the following attributes:
462 - examples: the list of examples.
464 - globs: The namespace (aka globals) that the examples should
467 - name: A name identifying the DocTest (typically, the name of
468 the object whose docstring this DocTest was extracted from).
470 - filename: The name of the file that this DocTest was extracted
471 from, or `None` if the filename is unknown.
473 - lineno: The line number within filename where this DocTest
474 begins, or `None` if the line number is unavailable. This
475 line number is zero-based, with respect to the beginning of
478 - docstring: The string that the examples were extracted from,
479 or `None` if the string is unavailable.
481 def __init__(self
, examples
, globs
, name
, filename
, lineno
, docstring
):
483 Create a new DocTest containing the given examples. The
484 DocTest's globals are initialized with a copy of `globs`.
486 assert not isinstance(examples
, basestring
), \
487 "DocTest no longer accepts str; use DocTestParser instead"
488 self
.examples
= examples
489 self
.docstring
= docstring
490 self
.globs
= globs
.copy()
492 self
.filename
= filename
496 if len(self
.examples
) == 0:
497 examples
= 'no examples'
498 elif len(self
.examples
) == 1:
499 examples
= '1 example'
501 examples
= '%d examples' % len(self
.examples
)
502 return ('<DocTest %s from %s:%s (%s)>' %
503 (self
.name
, self
.filename
, self
.lineno
, examples
))
506 # This lets us sort tests by name:
507 def __cmp__(self
, other
):
508 if not isinstance(other
, DocTest
):
510 return cmp((self
.name
, self
.filename
, self
.lineno
, id(self
)),
511 (other
.name
, other
.filename
, other
.lineno
, id(other
)))
513 ######################################################################
515 ######################################################################
519 A class used to parse strings containing doctest examples.
521 # This regular expression is used to find doctest examples in a
522 # string. It defines three groups: `source` is the source code
523 # (including leading indentation and prompts); `indent` is the
524 # indentation of the first (PS1) line of the source code; and
525 # `want` is the expected output (including leading indentation).
526 _EXAMPLE_RE
= re
.compile(r
'''
527 # Source consists of a PS1 line followed by zero or more PS2 lines.
529 (?:^(?P<indent> [ ]*) >>> .*) # PS1 line
530 (?:\n [ ]* \.\.\. .*)*) # PS2 lines
532 # Want consists of any non-blank lines that do not start with PS1.
533 (?P<want> (?:(?![ ]*$) # Not a blank line
534 (?![ ]*>>>) # Not a line starting with PS1
535 .*$\n? # But any other line
537 ''', re
.MULTILINE | re
.VERBOSE
)
539 # A regular expression for handling `want` strings that contain
540 # expected exceptions. It divides `want` into three pieces:
541 # - the traceback header line (`hdr`)
542 # - the traceback stack (`stack`)
543 # - the exception message (`msg`), as generated by
544 # traceback.format_exception_only()
545 # `msg` may have multiple lines. We assume/require that the
546 # exception message is the first non-indented line starting with a word
547 # character following the traceback header line.
548 _EXCEPTION_RE
= re
.compile(r
"""
549 # Grab the traceback header. Different versions of Python have
550 # said different things on the first traceback line.
551 ^(?P<hdr> Traceback\ \(
552 (?: most\ recent\ call\ last
556 \s* $ # toss trailing whitespace on the header.
557 (?P<stack> .*?) # don't blink: absorb stuff until...
558 ^ (?P<msg> \w+ .*) # a line *starts* with alphanum.
559 """, re
.VERBOSE | re
.MULTILINE | re
.DOTALL
)
561 # A callable returning a true value iff its argument is a blank line
562 # or contains a single comment.
563 _IS_BLANK_OR_COMMENT
= re
.compile(r
'^[ ]*(#.*)?$').match
565 def parse(self
, string
, name
='<string>'):
567 Divide the given string into examples and intervening text,
568 and return them as a list of alternating Examples and strings.
569 Line numbers for the Examples are 0-based. The optional
570 argument `name` is a name identifying this string, and is only
571 used for error messages.
573 string
= string
.expandtabs()
574 # If all lines begin with the same indentation, then strip it.
575 min_indent
= self
._min
_indent
(string
)
577 string
= '\n'.join([l
[min_indent
:] for l
in string
.split('\n')])
580 charno
, lineno
= 0, 0
581 # Find all doctest examples in the string:
582 for m
in self
._EXAMPLE
_RE
.finditer(string
):
583 # Add the pre-example text to `output`.
584 output
.append(string
[charno
:m
.start()])
585 # Update lineno (lines before this example)
586 lineno
+= string
.count('\n', charno
, m
.start())
587 # Extract info from the regexp match.
588 (source
, options
, want
, exc_msg
) = \
589 self
._parse
_example
(m
, name
, lineno
)
590 # Create an Example, and add it to the list.
591 if not self
._IS
_BLANK
_OR
_COMMENT
(source
):
592 output
.append( Example(source
, want
, exc_msg
,
594 indent
=min_indent
+len(m
.group('indent')),
596 # Update lineno (lines inside this example)
597 lineno
+= string
.count('\n', m
.start(), m
.end())
600 # Add any remaining post-example text to `output`.
601 output
.append(string
[charno
:])
604 def get_doctest(self
, string
, globs
, name
, filename
, lineno
):
606 Extract all doctest examples from the given string, and
607 collect them into a `DocTest` object.
609 `globs`, `name`, `filename`, and `lineno` are attributes for
610 the new `DocTest` object. See the documentation for `DocTest`
611 for more information.
613 return DocTest(self
.get_examples(string
, name
), globs
,
614 name
, filename
, lineno
, string
)
616 def get_examples(self
, string
, name
='<string>'):
618 Extract all doctest examples from the given string, and return
619 them as a list of `Example` objects. Line numbers are
620 0-based, because it's most common in doctests that nothing
621 interesting appears on the same line as opening triple-quote,
622 and so the first interesting line is called \"line 1\" then.
624 The optional argument `name` is a name identifying this
625 string, and is only used for error messages.
627 return [x
for x
in self
.parse(string
, name
)
628 if isinstance(x
, Example
)]
630 def _parse_example(self
, m
, name
, lineno
):
632 Given a regular expression match from `_EXAMPLE_RE` (`m`),
633 return a pair `(source, want)`, where `source` is the matched
634 example's source code (with prompts and indentation stripped);
635 and `want` is the example's expected output (with indentation
638 `name` is the string's name, and `lineno` is the line number
639 where the example starts; both are used for error messages.
641 # Get the example's indentation level.
642 indent
= len(m
.group('indent'))
644 # Divide source into lines; check that they're properly
645 # indented; and then strip their indentation & prompts.
646 source_lines
= m
.group('source').split('\n')
647 self
._check
_prompt
_blank
(source_lines
, indent
, name
, lineno
)
648 self
._check
_prefix
(source_lines
[1:], ' '*indent
+ '.', name
, lineno
)
649 source
= '\n'.join([sl
[indent
+4:] for sl
in source_lines
])
651 # Divide want into lines; check that it's properly indented; and
652 # then strip the indentation. Spaces before the last newline should
653 # be preserved, so plain rstrip() isn't good enough.
654 want
= m
.group('want')
655 want_lines
= want
.split('\n')
656 if len(want_lines
) > 1 and re
.match(r
' *$', want_lines
[-1]):
657 del want_lines
[-1] # forget final newline & spaces after it
658 self
._check
_prefix
(want_lines
, ' '*indent
, name
,
659 lineno
+ len(source_lines
))
660 want
= '\n'.join([wl
[indent
:] for wl
in want_lines
])
662 # If `want` contains a traceback message, then extract it.
663 m
= self
._EXCEPTION
_RE
.match(want
)
665 exc_msg
= m
.group('msg')
669 # Extract options from the source.
670 options
= self
._find
_options
(source
, name
, lineno
)
672 return source
, options
, want
, exc_msg
674 # This regular expression looks for option directives in the
675 # source code of an example. Option directives are comments
676 # starting with "doctest:". Warning: this may give false
677 # positives for string-literals that contain the string
678 # "#doctest:". Eliminating these false positives would require
679 # actually parsing the string; but we limit them by ignoring any
680 # line containing "#doctest:" that is *followed* by a quote mark.
681 _OPTION_DIRECTIVE_RE
= re
.compile(r
'#\s*doctest:\s*([^\n\'"]*)$',
684 def _find_options(self, source, name, lineno):
686 Return a dictionary containing option overrides extracted from
687 option directives in the given source string.
689 `name` is the string's name, and `lineno` is the line number
690 where the example starts; both are used for error messages.
693 # (note: with the current regexp, this will match at most once:)
694 for m in self._OPTION_DIRECTIVE_RE.finditer(source):
695 option_strings = m.group(1).replace(',', ' ').split()
696 for option in option_strings:
697 if (option[0] not in '+-' or
698 option[1:] not in OPTIONFLAGS_BY_NAME):
699 raise ValueError('line %r of the doctest for %s '
700 'has an invalid option: %r' %
701 (lineno+1, name, option))
702 flag = OPTIONFLAGS_BY_NAME[option[1:]]
703 options[flag] = (option[0] == '+')
704 if options and self._IS_BLANK_OR_COMMENT(source):
705 raise ValueError('line %r of the doctest for %s has an option '
706 'directive on a line with no example: %r' %
707 (lineno, name, source))
710 # This regular expression finds the indentation of every non-blank
712 _INDENT_RE = re.compile('^([ ]*)(?=\S)', re.MULTILINE)
714 def _min_indent(self, s):
715 "Return the minimum indentation of any non
-blank line
in `s`
"
716 indents = [len(indent) for indent in self._INDENT_RE.findall(s)]
722 def _check_prompt_blank(self, lines, indent, name, lineno):
724 Given the lines of a source string (including prompts and
725 leading indentation), check to make sure that every prompt is
726 followed by a space character. If any line is not followed by
727 a space character, then raise ValueError.
729 for i, line in enumerate(lines):
730 if len(line) >= indent+4 and line[indent+3] != ' ':
731 raise ValueError('line %r of the docstring for %s '
732 'lacks blank after %s: %r' %
734 line[indent:indent+3], line))
736 def _check_prefix(self, lines, prefix, name, lineno):
738 Check that every line in the given list starts with the given
739 prefix; if any line does not, then raise a ValueError.
741 for i, line in enumerate(lines):
742 if line and not line.startswith(prefix):
743 raise ValueError('line %r of the docstring for %s has '
744 'inconsistent leading whitespace: %r' %
745 (lineno+i+1, name, line))
748 ######################################################################
750 ######################################################################
754 A class used to extract the DocTests that are relevant to a given
755 object, from its docstring and the docstrings of its contained
756 objects. Doctests can currently be extracted from the following
757 object types: modules, functions, classes, methods, staticmethods,
758 classmethods, and properties.
761 def __init__(self, verbose=False, parser=DocTestParser(),
762 recurse=True, _namefilter=None, exclude_empty=True):
764 Create a new doctest finder.
766 The optional argument `parser` specifies a class or
767 function that should be used to create new DocTest objects (or
768 objects that implement the same interface as DocTest). The
769 signature for this factory function should match the signature
770 of the DocTest constructor.
772 If the optional argument `recurse` is false, then `find` will
773 only examine the given object, and not any contained objects.
775 If the optional argument `exclude_empty` is false, then `find`
776 will include tests for objects with empty docstrings.
778 self._parser = parser
779 self._verbose = verbose
780 self._recurse = recurse
781 self._exclude_empty = exclude_empty
782 # _namefilter is undocumented, and exists only for temporary backward-
783 # compatibility support of testmod's deprecated isprivate mess.
784 self._namefilter = _namefilter
786 def find(self, obj, name=None, module=None, globs=None,
789 Return a list of the DocTests that are defined by the given
790 object's docstring, or by any of its contained objects'
793 The optional parameter `module` is the module that contains
794 the given object. If the module is not specified or is None, then
795 the test finder will attempt to automatically determine the
796 correct module. The object's module is used:
798 - As a default namespace, if `globs` is not specified.
799 - To prevent the DocTestFinder from extracting DocTests
800 from objects that are imported from other modules.
801 - To find the name of the file containing the object.
802 - To help find the line number of the object within its
805 Contained objects whose module does not match `module` are ignored.
807 If `module` is False, no attempt to find the module will be made.
808 This is obscure, of use mostly in tests: if `module` is False, or
809 is None but cannot be found automatically, then all objects are
810 considered to belong to the (non-existent) module, so all contained
811 objects will (recursively) be searched for doctests.
813 The globals for each DocTest is formed by combining `globs`
814 and `extraglobs` (bindings in `extraglobs` override bindings
815 in `globs`). A new copy of the globals dictionary is created
816 for each DocTest. If `globs` is not specified, then it
817 defaults to the module's `__dict__`, if specified, or {}
818 otherwise. If `extraglobs` is not specified, then it defaults
822 # If name was not specified, then extract it from the object.
824 name = getattr(obj, '__name__', None)
826 raise ValueError("DocTestFinder
.find
: name must be given
"
827 "when obj
.__name
__ doesn
't exist: %r" %
830 # Find the module that contains the given object (if obj is
831 # a module, then module=obj.). Note: this may fail, in which
832 # case module will be None.
836 module = inspect.getmodule(obj)
838 # Read the module's source code
. This
is used by
839 # DocTestFinder._find_lineno to find the line number for a
840 # given object's docstring.
842 file = inspect
.getsourcefile(obj
) or inspect
.getfile(obj
)
843 source_lines
= linecache
.getlines(file)
849 # Initialize globals, and merge in extraglobs.
854 globs
= module
.__dict
__.copy()
857 if extraglobs
is not None:
858 globs
.update(extraglobs
)
860 # Recursively expore `obj`, extracting DocTests.
862 self
._find
(tests
, obj
, name
, module
, source_lines
, globs
, {})
865 def _filter(self
, obj
, prefix
, base
):
867 Return true if the given object should not be examined.
869 return (self
._namefilter
is not None and
870 self
._namefilter
(prefix
, base
))
872 def _from_module(self
, module
, object):
874 Return true if the given object is defined in the given
879 elif inspect
.isfunction(object):
880 return module
.__dict
__ is object.func_globals
881 elif inspect
.isclass(object):
882 return module
.__name
__ == object.__module
__
883 elif inspect
.getmodule(object) is not None:
884 return module
is inspect
.getmodule(object)
885 elif hasattr(object, '__module__'):
886 return module
.__name
__ == object.__module
__
887 elif isinstance(object, property):
888 return True # [XX] no way not be sure.
890 raise ValueError("object must be a class or function")
892 def _find(self
, tests
, obj
, name
, module
, source_lines
, globs
, seen
):
894 Find tests for the given object and any contained objects, and
898 print 'Finding tests in %s' % name
900 # If we've already processed this object, then ignore it.
905 # Find a test for this object, and add it to the list of tests.
906 test
= self
._get
_test
(obj
, name
, module
, globs
, source_lines
)
910 # Look for tests in a module's contained objects.
911 if inspect
.ismodule(obj
) and self
._recurse
:
912 for valname
, val
in obj
.__dict
__.items():
913 # Check if this contained object should be ignored.
914 if self
._filter
(val
, name
, valname
):
916 valname
= '%s.%s' % (name
, valname
)
917 # Recurse to functions & classes.
918 if ((inspect
.isfunction(val
) or inspect
.isclass(val
)) and
919 self
._from
_module
(module
, val
)):
920 self
._find
(tests
, val
, valname
, module
, source_lines
,
923 # Look for tests in a module's __test__ dictionary.
924 if inspect
.ismodule(obj
) and self
._recurse
:
925 for valname
, val
in getattr(obj
, '__test__', {}).items():
926 if not isinstance(valname
, basestring
):
927 raise ValueError("DocTestFinder.find: __test__ keys "
928 "must be strings: %r" %
930 if not (inspect
.isfunction(val
) or inspect
.isclass(val
) or
931 inspect
.ismethod(val
) or inspect
.ismodule(val
) or
932 isinstance(val
, basestring
)):
933 raise ValueError("DocTestFinder.find: __test__ values "
934 "must be strings, functions, methods, "
935 "classes, or modules: %r" %
937 valname
= '%s.__test__.%s' % (name
, valname
)
938 self
._find
(tests
, val
, valname
, module
, source_lines
,
941 # Look for tests in a class's contained objects.
942 if inspect
.isclass(obj
) and self
._recurse
:
943 for valname
, val
in obj
.__dict
__.items():
944 # Check if this contained object should be ignored.
945 if self
._filter
(val
, name
, valname
):
947 # Special handling for staticmethod/classmethod.
948 if isinstance(val
, staticmethod):
949 val
= getattr(obj
, valname
)
950 if isinstance(val
, classmethod):
951 val
= getattr(obj
, valname
).im_func
953 # Recurse to methods, properties, and nested classes.
954 if ((inspect
.isfunction(val
) or inspect
.isclass(val
) or
955 isinstance(val
, property)) and
956 self
._from
_module
(module
, val
)):
957 valname
= '%s.%s' % (name
, valname
)
958 self
._find
(tests
, val
, valname
, module
, source_lines
,
961 def _get_test(self
, obj
, name
, module
, globs
, source_lines
):
963 Return a DocTest for the given object, if it defines a docstring;
964 otherwise, return None.
966 # Extract the object's docstring. If it doesn't have one,
967 # then return None (no test for this object).
968 if isinstance(obj
, basestring
):
972 if obj
.__doc
__ is None:
975 docstring
= obj
.__doc
__
976 if not isinstance(docstring
, basestring
):
977 docstring
= str(docstring
)
978 except (TypeError, AttributeError):
981 # Find the docstring's location in the file.
982 lineno
= self
._find
_lineno
(obj
, source_lines
)
984 # Don't bother if the docstring is empty.
985 if self
._exclude
_empty
and not docstring
:
988 # Return a DocTest for this object.
992 filename
= getattr(module
, '__file__', module
.__name
__)
993 if filename
[-4:] in (".pyc", ".pyo"):
994 filename
= filename
[:-1]
995 return self
._parser
.get_doctest(docstring
, globs
, name
,
998 def _find_lineno(self
, obj
, source_lines
):
1000 Return a line number of the given object's docstring. Note:
1001 this method assumes that the object has a docstring.
1005 # Find the line number for modules.
1006 if inspect
.ismodule(obj
):
1009 # Find the line number for classes.
1010 # Note: this could be fooled if a class is defined multiple
1011 # times in a single file.
1012 if inspect
.isclass(obj
):
1013 if source_lines
is None:
1015 pat
= re
.compile(r
'^\s*class\s*%s\b' %
1016 getattr(obj
, '__name__', '-'))
1017 for i
, line
in enumerate(source_lines
):
1022 # Find the line number for functions & methods.
1023 if inspect
.ismethod(obj
): obj
= obj
.im_func
1024 if inspect
.isfunction(obj
): obj
= obj
.func_code
1025 if inspect
.istraceback(obj
): obj
= obj
.tb_frame
1026 if inspect
.isframe(obj
): obj
= obj
.f_code
1027 if inspect
.iscode(obj
):
1028 lineno
= getattr(obj
, 'co_firstlineno', None)-1
1030 # Find the line number where the docstring starts. Assume
1031 # that it's the first line that begins with a quote mark.
1032 # Note: this could be fooled by a multiline function
1033 # signature, where a continuation line begins with a quote
1035 if lineno
is not None:
1036 if source_lines
is None:
1038 pat
= re
.compile('(^|.*:)\s*\w*("|\')')
1039 for lineno
in range(lineno
, len(source_lines
)):
1040 if pat
.match(source_lines
[lineno
]):
1043 # We couldn't find the line number.
1046 ######################################################################
1047 ## 5. DocTest Runner
1048 ######################################################################
1050 class DocTestRunner
:
1052 A class used to run DocTest test cases, and accumulate statistics.
1053 The `run` method is used to process a single DocTest case. It
1054 returns a tuple `(f, t)`, where `t` is the number of test cases
1055 tried, and `f` is the number of test cases that failed.
1057 >>> tests = DocTestFinder().find(_TestClass)
1058 >>> runner = DocTestRunner(verbose=False)
1059 >>> tests.sort(key = lambda test: test.name)
1060 >>> for test in tests:
1061 ... print test.name, '->', runner.run(test)
1062 _TestClass -> (0, 2)
1063 _TestClass.__init__ -> (0, 2)
1064 _TestClass.get -> (0, 2)
1065 _TestClass.square -> (0, 1)
1067 The `summarize` method prints a summary of all the test cases that
1068 have been run by the runner, and returns an aggregated `(f, t)`
1071 >>> runner.summarize(verbose=1)
1072 4 items passed all tests:
1073 2 tests in _TestClass
1074 2 tests in _TestClass.__init__
1075 2 tests in _TestClass.get
1076 1 tests in _TestClass.square
1078 7 passed and 0 failed.
1082 The aggregated number of tried examples and failed examples is
1083 also available via the `tries` and `failures` attributes:
1090 The comparison between expected outputs and actual outputs is done
1091 by an `OutputChecker`. This comparison may be customized with a
1092 number of option flags; see the documentation for `testmod` for
1093 more information. If the option flags are insufficient, then the
1094 comparison may also be customized by passing a subclass of
1095 `OutputChecker` to the constructor.
1097 The test runner's display output can be controlled in two ways.
1098 First, an output function (`out) can be passed to
1099 `TestRunner.run`; this function will be called with strings that
1100 should be displayed. It defaults to `sys.stdout.write`. If
1101 capturing the output is not sufficient, then the display output
1102 can be also customized by subclassing DocTestRunner, and
1103 overriding the methods `report_start`, `report_success`,
1104 `report_unexpected_exception`, and `report_failure`.
1106 # This divider string is used to separate failure messages, and to
1107 # separate sections of the summary.
1110 def __init__(self
, checker
=None, verbose
=None, optionflags
=0):
1112 Create a new test runner.
1114 Optional keyword arg `checker` is the `OutputChecker` that
1115 should be used to compare the expected outputs and actual
1116 outputs of doctest examples.
1118 Optional keyword arg 'verbose' prints lots of stuff if true,
1119 only failures if false; by default, it's true iff '-v' is in
1122 Optional argument `optionflags` can be used to control how the
1123 test runner compares expected output to actual output, and how
1124 it displays failures. See the documentation for `testmod` for
1127 self
._checker
= checker
or OutputChecker()
1129 verbose
= '-v' in sys
.argv
1130 self
._verbose
= verbose
1131 self
.optionflags
= optionflags
1132 self
.original_optionflags
= optionflags
1134 # Keep track of the examples we've run.
1139 # Create a fake output target for capturing doctest output.
1140 self
._fakeout
= _SpoofOut()
1142 #/////////////////////////////////////////////////////////////////
1144 #/////////////////////////////////////////////////////////////////
1146 def report_start(self
, out
, test
, example
):
1148 Report that the test runner is about to process the given
1149 example. (Only displays a message if verbose=True)
1153 out('Trying:\n' + _indent(example
.source
) +
1154 'Expecting:\n' + _indent(example
.want
))
1156 out('Trying:\n' + _indent(example
.source
) +
1157 'Expecting nothing\n')
1159 def report_success(self
, out
, test
, example
, got
):
1161 Report that the given example ran successfully. (Only
1162 displays a message if verbose=True)
1167 def report_failure(self
, out
, test
, example
, got
):
1169 Report that the given example failed.
1171 out(self
._failure
_header
(test
, example
) +
1172 self
._checker
.output_difference(example
, got
, self
.optionflags
))
1174 def report_unexpected_exception(self
, out
, test
, example
, exc_info
):
1176 Report that the given example raised an unexpected exception.
1178 out(self
._failure
_header
(test
, example
) +
1179 'Exception raised:\n' + _indent(_exception_traceback(exc_info
)))
1181 def _failure_header(self
, test
, example
):
1182 out
= [self
.DIVIDER
]
1184 if test
.lineno
is not None and example
.lineno
is not None:
1185 lineno
= test
.lineno
+ example
.lineno
+ 1
1188 out
.append('File "%s", line %s, in %s' %
1189 (test
.filename
, lineno
, test
.name
))
1191 out
.append('Line %s, in %s' % (example
.lineno
+1, test
.name
))
1192 out
.append('Failed example:')
1193 source
= example
.source
1194 out
.append(_indent(source
))
1195 return '\n'.join(out
)
1197 #/////////////////////////////////////////////////////////////////
1199 #/////////////////////////////////////////////////////////////////
1201 def __run(self
, test
, compileflags
, out
):
1203 Run the examples in `test`. Write the outcome of each example
1204 with one of the `DocTestRunner.report_*` methods, using the
1205 writer function `out`. `compileflags` is the set of compiler
1206 flags that should be used to execute examples. Return a tuple
1207 `(f, t)`, where `t` is the number of examples tried, and `f`
1208 is the number of examples that failed. The examples are run
1209 in the namespace `test.globs`.
1211 # Keep track of the number of failures and tries.
1212 failures
= tries
= 0
1214 # Save the option flags (since option directives can be used
1216 original_optionflags
= self
.optionflags
1218 SUCCESS
, FAILURE
, BOOM
= range(3) # `outcome` state
1220 check
= self
._checker
.check_output
1222 # Process each example.
1223 for examplenum
, example
in enumerate(test
.examples
):
1225 # If REPORT_ONLY_FIRST_FAILURE is set, then supress
1226 # reporting after the first failure.
1227 quiet
= (self
.optionflags
& REPORT_ONLY_FIRST_FAILURE
and
1230 # Merge in the example's options.
1231 self
.optionflags
= original_optionflags
1233 for (optionflag
, val
) in example
.options
.items():
1235 self
.optionflags |
= optionflag
1237 self
.optionflags
&= ~optionflag
1239 # If 'SKIP' is set, then skip this example.
1240 if self
.optionflags
& SKIP
:
1243 # Record that we started this example.
1246 self
.report_start(out
, test
, example
)
1248 # Use a special filename for compile(), so we can retrieve
1249 # the source code during interactive debugging (see
1250 # __patched_linecache_getlines).
1251 filename
= '<doctest %s[%d]>' % (test
.name
, examplenum
)
1253 # Run the example in the given context (globs), and record
1254 # any exception that gets raised. (But don't intercept
1255 # keyboard interrupts.)
1257 # Don't blink! This is where the user's code gets run.
1258 exec compile(example
.source
, filename
, "single",
1259 compileflags
, 1) in test
.globs
1260 self
.debugger
.set_continue() # ==== Example Finished ====
1262 except KeyboardInterrupt:
1265 exception
= sys
.exc_info()
1266 self
.debugger
.set_continue() # ==== Example Finished ====
1268 got
= self
._fakeout
.getvalue() # the actual output
1269 self
._fakeout
.truncate(0)
1270 outcome
= FAILURE
# guilty until proved innocent or insane
1272 # If the example executed without raising any exceptions,
1273 # verify its output.
1274 if exception
is None:
1275 if check(example
.want
, got
, self
.optionflags
):
1278 # The example raised an exception: check if it was expected.
1280 exc_info
= sys
.exc_info()
1281 exc_msg
= traceback
.format_exception_only(*exc_info
[:2])[-1]
1283 got
+= _exception_traceback(exc_info
)
1285 # If `example.exc_msg` is None, then we weren't expecting
1287 if example
.exc_msg
is None:
1290 # We expected an exception: see whether it matches.
1291 elif check(example
.exc_msg
, exc_msg
, self
.optionflags
):
1294 # Another chance if they didn't care about the detail.
1295 elif self
.optionflags
& IGNORE_EXCEPTION_DETAIL
:
1296 m1
= re
.match(r
'[^:]*:', example
.exc_msg
)
1297 m2
= re
.match(r
'[^:]*:', exc_msg
)
1298 if m1
and m2
and check(m1
.group(0), m2
.group(0),
1302 # Report the outcome.
1303 if outcome
is SUCCESS
:
1305 self
.report_success(out
, test
, example
, got
)
1306 elif outcome
is FAILURE
:
1308 self
.report_failure(out
, test
, example
, got
)
1310 elif outcome
is BOOM
:
1312 self
.report_unexpected_exception(out
, test
, example
,
1316 assert False, ("unknown outcome", outcome
)
1318 # Restore the option flags (in case they were modified)
1319 self
.optionflags
= original_optionflags
1321 # Record and return the number of failures and tries.
1322 self
.__record
_outcome
(test
, failures
, tries
)
1323 return failures
, tries
1325 def __record_outcome(self
, test
, f
, t
):
1327 Record the fact that the given DocTest (`test`) generated `f`
1328 failures out of `t` tried examples.
1330 f2
, t2
= self
._name
2ft
.get(test
.name
, (0,0))
1331 self
._name
2ft
[test
.name
] = (f
+f2
, t
+t2
)
1335 __LINECACHE_FILENAME_RE
= re
.compile(r
'<doctest '
1336 r
'(?P<name>[\w\.]+)'
1337 r
'\[(?P<examplenum>\d+)\]>$')
1338 def __patched_linecache_getlines(self
, filename
, module_globals
=None):
1339 m
= self
.__LINECACHE
_FILENAME
_RE
.match(filename
)
1340 if m
and m
.group('name') == self
.test
.name
:
1341 example
= self
.test
.examples
[int(m
.group('examplenum'))]
1342 return example
.source
.splitlines(True)
1344 return self
.save_linecache_getlines(filename
, module_globals
)
1346 def run(self
, test
, compileflags
=None, out
=None, clear_globs
=True):
1348 Run the examples in `test`, and display the results using the
1349 writer function `out`.
1351 The examples are run in the namespace `test.globs`. If
1352 `clear_globs` is true (the default), then this namespace will
1353 be cleared after the test runs, to help with garbage
1354 collection. If you would like to examine the namespace after
1355 the test completes, then use `clear_globs=False`.
1357 `compileflags` gives the set of flags that should be used by
1358 the Python compiler when running the examples. If not
1359 specified, then it will default to the set of future-import
1360 flags that apply to `globs`.
1362 The output of each example is checked using
1363 `DocTestRunner.check_output`, and the results are formatted by
1364 the `DocTestRunner.report_*` methods.
1368 if compileflags
is None:
1369 compileflags
= _extract_future_flags(test
.globs
)
1371 save_stdout
= sys
.stdout
1373 out
= save_stdout
.write
1374 sys
.stdout
= self
._fakeout
1376 # Patch pdb.set_trace to restore sys.stdout during interactive
1377 # debugging (so it's not still redirected to self._fakeout).
1378 # Note that the interactive output will go to *our*
1379 # save_stdout, even if that's not the real sys.stdout; this
1380 # allows us to write test cases for the set_trace behavior.
1381 save_set_trace
= pdb
.set_trace
1382 self
.debugger
= _OutputRedirectingPdb(save_stdout
)
1383 self
.debugger
.reset()
1384 pdb
.set_trace
= self
.debugger
.set_trace
1386 # Patch linecache.getlines, so we can see the example's source
1387 # when we're inside the debugger.
1388 self
.save_linecache_getlines
= linecache
.getlines
1389 linecache
.getlines
= self
.__patched
_linecache
_getlines
1392 return self
.__run
(test
, compileflags
, out
)
1394 sys
.stdout
= save_stdout
1395 pdb
.set_trace
= save_set_trace
1396 linecache
.getlines
= self
.save_linecache_getlines
1400 #/////////////////////////////////////////////////////////////////
1402 #/////////////////////////////////////////////////////////////////
1403 def summarize(self
, verbose
=None):
1405 Print a summary of all the test cases that have been run by
1406 this DocTestRunner, and return a tuple `(f, t)`, where `f` is
1407 the total number of failed examples, and `t` is the total
1408 number of tried examples.
1410 The optional `verbose` argument controls how detailed the
1411 summary is. If the verbosity is not specified, then the
1412 DocTestRunner's verbosity is used.
1415 verbose
= self
._verbose
1420 for x
in self
._name
2ft
.items():
1426 notests
.append(name
)
1428 passed
.append( (name
, t
) )
1433 print len(notests
), "items had no tests:"
1435 for thing
in notests
:
1438 print len(passed
), "items passed all tests:"
1440 for thing
, count
in passed
:
1441 print " %3d tests in %s" % (count
, thing
)
1444 print len(failed
), "items had failures:"
1446 for thing
, (f
, t
) in failed
:
1447 print " %3d of %3d in %s" % (f
, t
, thing
)
1449 print totalt
, "tests in", len(self
._name
2ft
), "items."
1450 print totalt
- totalf
, "passed and", totalf
, "failed."
1452 print "***Test Failed***", totalf
, "failures."
1454 print "Test passed."
1455 return totalf
, totalt
1457 #/////////////////////////////////////////////////////////////////
1458 # Backward compatibility cruft to maintain doctest.master.
1459 #/////////////////////////////////////////////////////////////////
1460 def merge(self
, other
):
1462 for name
, (f
, t
) in other
._name
2ft
.items():
1464 print "*** DocTestRunner.merge: '" + name
+ "' in both" \
1465 " testers; summing outcomes."
1471 class OutputChecker
:
1473 A class used to check the whether the actual output from a doctest
1474 example matches the expected output. `OutputChecker` defines two
1475 methods: `check_output`, which compares a given pair of outputs,
1476 and returns true if they match; and `output_difference`, which
1477 returns a string describing the differences between two outputs.
1479 def check_output(self
, want
, got
, optionflags
):
1481 Return True iff the actual output from an example (`got`)
1482 matches the expected output (`want`). These strings are
1483 always considered to match if they are identical; but
1484 depending on what option flags the test runner is using,
1485 several non-exact match types are also possible. See the
1486 documentation for `TestRunner` for more information about
1489 # Handle the common case first, for efficiency:
1490 # if they're string-identical, always return true.
1494 # The values True and False replaced 1 and 0 as the return
1495 # value for boolean comparisons in Python 2.3.
1496 if not (optionflags
& DONT_ACCEPT_TRUE_FOR_1
):
1497 if (got
,want
) == ("True\n", "1\n"):
1499 if (got
,want
) == ("False\n", "0\n"):
1502 # <BLANKLINE> can be used as a special sequence to signify a
1503 # blank line, unless the DONT_ACCEPT_BLANKLINE flag is used.
1504 if not (optionflags
& DONT_ACCEPT_BLANKLINE
):
1505 # Replace <BLANKLINE> in want with a blank line.
1506 want
= re
.sub('(?m)^%s\s*?$' % re
.escape(BLANKLINE_MARKER
),
1508 # If a line in got contains only spaces, then remove the
1510 got
= re
.sub('(?m)^\s*?$', '', got
)
1514 # This flag causes doctest to ignore any differences in the
1515 # contents of whitespace strings. Note that this can be used
1516 # in conjunction with the ELLIPSIS flag.
1517 if optionflags
& NORMALIZE_WHITESPACE
:
1518 got
= ' '.join(got
.split())
1519 want
= ' '.join(want
.split())
1523 # The ELLIPSIS flag says to let the sequence "..." in `want`
1524 # match any substring in `got`.
1525 if optionflags
& ELLIPSIS
:
1526 if _ellipsis_match(want
, got
):
1529 # We didn't find any match; return false.
1532 # Should we do a fancy diff?
1533 def _do_a_fancy_diff(self
, want
, got
, optionflags
):
1534 # Not unless they asked for a fancy diff.
1535 if not optionflags
& (REPORT_UDIFF |
1540 # If expected output uses ellipsis, a meaningful fancy diff is
1541 # too hard ... or maybe not. In two real-life failures Tim saw,
1542 # a diff was a major help anyway, so this is commented out.
1543 # [todo] _ellipsis_match() knows which pieces do and don't match,
1544 # and could be the basis for a kick-ass diff in this case.
1545 ##if optionflags & ELLIPSIS and ELLIPSIS_MARKER in want:
1548 # ndiff does intraline difference marking, so can be useful even
1549 # for 1-line differences.
1550 if optionflags
& REPORT_NDIFF
:
1553 # The other diff types need at least a few lines to be helpful.
1554 return want
.count('\n') > 2 and got
.count('\n') > 2
1556 def output_difference(self
, example
, got
, optionflags
):
1558 Return a string describing the differences between the
1559 expected output for a given example (`example`) and the actual
1560 output (`got`). `optionflags` is the set of option flags used
1561 to compare `want` and `got`.
1564 # If <BLANKLINE>s are being used, then replace blank lines
1565 # with <BLANKLINE> in the actual output string.
1566 if not (optionflags
& DONT_ACCEPT_BLANKLINE
):
1567 got
= re
.sub('(?m)^[ ]*(?=\n)', BLANKLINE_MARKER
, got
)
1569 # Check if we should use diff.
1570 if self
._do
_a
_fancy
_diff
(want
, got
, optionflags
):
1571 # Split want & got into lines.
1572 want_lines
= want
.splitlines(True) # True == keep line ends
1573 got_lines
= got
.splitlines(True)
1574 # Use difflib to find their differences.
1575 if optionflags
& REPORT_UDIFF
:
1576 diff
= difflib
.unified_diff(want_lines
, got_lines
, n
=2)
1577 diff
= list(diff
)[2:] # strip the diff header
1578 kind
= 'unified diff with -expected +actual'
1579 elif optionflags
& REPORT_CDIFF
:
1580 diff
= difflib
.context_diff(want_lines
, got_lines
, n
=2)
1581 diff
= list(diff
)[2:] # strip the diff header
1582 kind
= 'context diff with expected followed by actual'
1583 elif optionflags
& REPORT_NDIFF
:
1584 engine
= difflib
.Differ(charjunk
=difflib
.IS_CHARACTER_JUNK
)
1585 diff
= list(engine
.compare(want_lines
, got_lines
))
1586 kind
= 'ndiff with -expected +actual'
1588 assert 0, 'Bad diff option'
1589 # Remove trailing whitespace on diff output.
1590 diff
= [line
.rstrip() + '\n' for line
in diff
]
1591 return 'Differences (%s):\n' % kind
+ _indent(''.join(diff
))
1593 # If we're not using diff, then simply list the expected
1594 # output followed by the actual output.
1596 return 'Expected:\n%sGot:\n%s' % (_indent(want
), _indent(got
))
1598 return 'Expected:\n%sGot nothing\n' % _indent(want
)
1600 return 'Expected nothing\nGot:\n%s' % _indent(got
)
1602 return 'Expected nothing\nGot nothing\n'
1604 class DocTestFailure(Exception):
1605 """A DocTest example has failed in debugging mode.
1607 The exception instance has variables:
1609 - test: the DocTest object being run
1611 - excample: the Example object that failed
1613 - got: the actual output
1615 def __init__(self
, test
, example
, got
):
1617 self
.example
= example
1621 return str(self
.test
)
1623 class UnexpectedException(Exception):
1624 """A DocTest example has encountered an unexpected exception
1626 The exception instance has variables:
1628 - test: the DocTest object being run
1630 - excample: the Example object that failed
1632 - exc_info: the exception info
1634 def __init__(self
, test
, example
, exc_info
):
1636 self
.example
= example
1637 self
.exc_info
= exc_info
1640 return str(self
.test
)
1642 class DebugRunner(DocTestRunner
):
1643 r
"""Run doc tests but raise an exception as soon as there is a failure.
1645 If an unexpected exception occurs, an UnexpectedException is raised.
1646 It contains the test, the example, and the original exception:
1648 >>> runner = DebugRunner(verbose=False)
1649 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
1650 ... {}, 'foo', 'foo.py', 0)
1652 ... runner.run(test)
1653 ... except UnexpectedException, failure:
1656 >>> failure.test is test
1659 >>> failure.example.want
1662 >>> exc_info = failure.exc_info
1663 >>> raise exc_info[0], exc_info[1], exc_info[2]
1664 Traceback (most recent call last):
1668 We wrap the original exception to give the calling application
1669 access to the test and example information.
1671 If the output doesn't match, then a DocTestFailure is raised:
1673 >>> test = DocTestParser().get_doctest('''
1677 ... ''', {}, 'foo', 'foo.py', 0)
1680 ... runner.run(test)
1681 ... except DocTestFailure, failure:
1684 DocTestFailure objects provide access to the test:
1686 >>> failure.test is test
1689 As well as to the example:
1691 >>> failure.example.want
1694 and the actual output:
1699 If a failure or error occurs, the globals are left intact:
1701 >>> del test.globs['__builtins__']
1705 >>> test = DocTestParser().get_doctest('''
1707 ... >>> raise KeyError
1708 ... ''', {}, 'foo', 'foo.py', 0)
1710 >>> runner.run(test)
1711 Traceback (most recent call last):
1713 UnexpectedException: <DocTest foo from foo.py:0 (2 examples)>
1715 >>> del test.globs['__builtins__']
1719 But the globals are cleared if there is no error:
1721 >>> test = DocTestParser().get_doctest('''
1723 ... ''', {}, 'foo', 'foo.py', 0)
1725 >>> runner.run(test)
1733 def run(self
, test
, compileflags
=None, out
=None, clear_globs
=True):
1734 r
= DocTestRunner
.run(self
, test
, compileflags
, out
, False)
1739 def report_unexpected_exception(self
, out
, test
, example
, exc_info
):
1740 raise UnexpectedException(test
, example
, exc_info
)
1742 def report_failure(self
, out
, test
, example
, got
):
1743 raise DocTestFailure(test
, example
, got
)
1745 ######################################################################
1746 ## 6. Test Functions
1747 ######################################################################
1748 # These should be backwards compatible.
1750 # For backward compatibility, a global instance of a DocTestRunner
1751 # class, updated by testmod.
1754 def testmod(m
=None, name
=None, globs
=None, verbose
=None, isprivate
=None,
1755 report
=True, optionflags
=0, extraglobs
=None,
1756 raise_on_error
=False, exclude_empty
=False):
1757 """m=None, name=None, globs=None, verbose=None, isprivate=None,
1758 report=True, optionflags=0, extraglobs=None, raise_on_error=False,
1761 Test examples in docstrings in functions and classes reachable
1762 from module m (or the current module if m is not supplied), starting
1763 with m.__doc__. Unless isprivate is specified, private names
1766 Also test examples reachable from dict m.__test__ if it exists and is
1767 not None. m.__test__ maps names to functions, classes and strings;
1768 function and class docstrings are tested even if the name is private;
1769 strings are tested directly, as if they were docstrings.
1771 Return (#failures, #tests).
1773 See doctest.__doc__ for an overview.
1775 Optional keyword arg "name" gives the name of the module; by default
1778 Optional keyword arg "globs" gives a dict to be used as the globals
1779 when executing examples; by default, use m.__dict__. A copy of this
1780 dict is actually used for each docstring, so that each docstring's
1781 examples start with a clean slate.
1783 Optional keyword arg "extraglobs" gives a dictionary that should be
1784 merged into the globals that are used to execute examples. By
1785 default, no extra globals are used. This is new in 2.4.
1787 Optional keyword arg "verbose" prints lots of stuff if true, prints
1788 only failures if false; by default, it's true iff "-v" is in sys.argv.
1790 Optional keyword arg "report" prints a summary at the end when true,
1791 else prints nothing at the end. In verbose mode, the summary is
1792 detailed, else very brief (in fact, empty if all tests passed).
1794 Optional keyword arg "optionflags" or's together module constants,
1795 and defaults to 0. This is new in 2.3. Possible values (see the
1798 DONT_ACCEPT_TRUE_FOR_1
1799 DONT_ACCEPT_BLANKLINE
1800 NORMALIZE_WHITESPACE
1803 IGNORE_EXCEPTION_DETAIL
1807 REPORT_ONLY_FIRST_FAILURE
1809 Optional keyword arg "raise_on_error" raises an exception on the
1810 first unexpected exception or failure. This allows failures to be
1811 post-mortem debugged.
1813 Deprecated in Python 2.4:
1814 Optional keyword arg "isprivate" specifies a function used to
1815 determine whether a name is private. The default function is
1816 treat all functions as public. Optionally, "isprivate" can be
1817 set to doctest.is_private to skip over functions marked as private
1818 using the underscore naming convention; see its docs for details.
1820 Advanced tomfoolery: testmod runs methods of a local instance of
1821 class doctest.Tester, then merges the results into (or creates)
1822 global Tester instance doctest.master. Methods of doctest.master
1823 can be called directly too, if you want to do something unusual.
1824 Passing report=0 to testmod is especially useful then, to delay
1825 displaying a summary. Invoke doctest.master.summarize(verbose)
1826 when you're done fiddling.
1830 if isprivate
is not None:
1831 warnings
.warn("the isprivate argument is deprecated; "
1832 "examine DocTestFinder.find() lists instead",
1835 # If no module was given, then use __main__.
1837 # DWA - m will still be None if this wasn't invoked from the command
1838 # line, in which case the following TypeError is about as good an error
1839 # as we should expect
1840 m
= sys
.modules
.get('__main__')
1842 # Check that we were actually given a module.
1843 if not inspect
.ismodule(m
):
1844 raise TypeError("testmod: module required; %r" % (m
,))
1846 # If no name was given, then use the module's name.
1850 # Find, parse, and run all tests in the given module.
1851 finder
= DocTestFinder(_namefilter
=isprivate
, exclude_empty
=exclude_empty
)
1854 runner
= DebugRunner(verbose
=verbose
, optionflags
=optionflags
)
1856 runner
= DocTestRunner(verbose
=verbose
, optionflags
=optionflags
)
1858 for test
in finder
.find(m
, name
, globs
=globs
, extraglobs
=extraglobs
):
1867 master
.merge(runner
)
1869 return runner
.failures
, runner
.tries
1871 def testfile(filename
, module_relative
=True, name
=None, package
=None,
1872 globs
=None, verbose
=None, report
=True, optionflags
=0,
1873 extraglobs
=None, raise_on_error
=False, parser
=DocTestParser(),
1876 Test examples in the given file. Return (#failures, #tests).
1878 Optional keyword arg "module_relative" specifies how filenames
1879 should be interpreted:
1881 - If "module_relative" is True (the default), then "filename"
1882 specifies a module-relative path. By default, this path is
1883 relative to the calling module's directory; but if the
1884 "package" argument is specified, then it is relative to that
1885 package. To ensure os-independence, "filename" should use
1886 "/" characters to separate path segments, and should not
1887 be an absolute path (i.e., it may not begin with "/").
1889 - If "module_relative" is False, then "filename" specifies an
1890 os-specific path. The path may be absolute or relative (to
1891 the current working directory).
1893 Optional keyword arg "name" gives the name of the test; by default
1894 use the file's basename.
1896 Optional keyword argument "package" is a Python package or the
1897 name of a Python package whose directory should be used as the
1898 base directory for a module relative filename. If no package is
1899 specified, then the calling module's directory is used as the base
1900 directory for module relative filenames. It is an error to
1901 specify "package" if "module_relative" is False.
1903 Optional keyword arg "globs" gives a dict to be used as the globals
1904 when executing examples; by default, use {}. A copy of this dict
1905 is actually used for each docstring, so that each docstring's
1906 examples start with a clean slate.
1908 Optional keyword arg "extraglobs" gives a dictionary that should be
1909 merged into the globals that are used to execute examples. By
1910 default, no extra globals are used.
1912 Optional keyword arg "verbose" prints lots of stuff if true, prints
1913 only failures if false; by default, it's true iff "-v" is in sys.argv.
1915 Optional keyword arg "report" prints a summary at the end when true,
1916 else prints nothing at the end. In verbose mode, the summary is
1917 detailed, else very brief (in fact, empty if all tests passed).
1919 Optional keyword arg "optionflags" or's together module constants,
1920 and defaults to 0. Possible values (see the docs for details):
1922 DONT_ACCEPT_TRUE_FOR_1
1923 DONT_ACCEPT_BLANKLINE
1924 NORMALIZE_WHITESPACE
1927 IGNORE_EXCEPTION_DETAIL
1931 REPORT_ONLY_FIRST_FAILURE
1933 Optional keyword arg "raise_on_error" raises an exception on the
1934 first unexpected exception or failure. This allows failures to be
1935 post-mortem debugged.
1937 Optional keyword arg "parser" specifies a DocTestParser (or
1938 subclass) that should be used to extract tests from the files.
1940 Optional keyword arg "encoding" specifies an encoding that should
1941 be used to convert the file to unicode.
1943 Advanced tomfoolery: testmod runs methods of a local instance of
1944 class doctest.Tester, then merges the results into (or creates)
1945 global Tester instance doctest.master. Methods of doctest.master
1946 can be called directly too, if you want to do something unusual.
1947 Passing report=0 to testmod is especially useful then, to delay
1948 displaying a summary. Invoke doctest.master.summarize(verbose)
1949 when you're done fiddling.
1953 if package
and not module_relative
:
1954 raise ValueError("Package may only be specified for module-"
1957 # Relativize the path
1958 text
, filename
= _load_testfile(filename
, package
, module_relative
)
1960 # If no name was given, then use the file's name.
1962 name
= os
.path
.basename(filename
)
1964 # Assemble the globals.
1968 globs
= globs
.copy()
1969 if extraglobs
is not None:
1970 globs
.update(extraglobs
)
1973 runner
= DebugRunner(verbose
=verbose
, optionflags
=optionflags
)
1975 runner
= DocTestRunner(verbose
=verbose
, optionflags
=optionflags
)
1977 if encoding
is not None:
1978 text
= text
.decode(encoding
)
1980 # Read the file, convert it to a test, and run it.
1981 test
= parser
.get_doctest(text
, globs
, name
, filename
, 0)
1990 master
.merge(runner
)
1992 return runner
.failures
, runner
.tries
1994 def run_docstring_examples(f
, globs
, verbose
=False, name
="NoName",
1995 compileflags
=None, optionflags
=0):
1997 Test examples in the given object's docstring (`f`), using `globs`
1998 as globals. Optional argument `name` is used in failure messages.
1999 If the optional argument `verbose` is true, then generate output
2000 even if there are no failures.
2002 `compileflags` gives the set of flags that should be used by the
2003 Python compiler when running the examples. If not specified, then
2004 it will default to the set of future-import flags that apply to
2007 Optional keyword arg `optionflags` specifies options for the
2008 testing and output. See the documentation for `testmod` for more
2011 # Find, parse, and run all tests in the given module.
2012 finder
= DocTestFinder(verbose
=verbose
, recurse
=False)
2013 runner
= DocTestRunner(verbose
=verbose
, optionflags
=optionflags
)
2014 for test
in finder
.find(f
, name
, globs
=globs
):
2015 runner
.run(test
, compileflags
=compileflags
)
2017 ######################################################################
2019 ######################################################################
2020 # This is provided only for backwards compatibility. It's not
2021 # actually used in any way.
2024 def __init__(self
, mod
=None, globs
=None, verbose
=None,
2025 isprivate
=None, optionflags
=0):
2027 warnings
.warn("class Tester is deprecated; "
2028 "use class doctest.DocTestRunner instead",
2029 DeprecationWarning, stacklevel
=2)
2030 if mod
is None and globs
is None:
2031 raise TypeError("Tester.__init__: must specify mod or globs")
2032 if mod
is not None and not inspect
.ismodule(mod
):
2033 raise TypeError("Tester.__init__: mod must be a module; %r" %
2036 globs
= mod
.__dict
__
2039 self
.verbose
= verbose
2040 self
.isprivate
= isprivate
2041 self
.optionflags
= optionflags
2042 self
.testfinder
= DocTestFinder(_namefilter
=isprivate
)
2043 self
.testrunner
= DocTestRunner(verbose
=verbose
,
2044 optionflags
=optionflags
)
2046 def runstring(self
, s
, name
):
2047 test
= DocTestParser().get_doctest(s
, self
.globs
, name
, None, None)
2049 print "Running string", name
2050 (f
,t
) = self
.testrunner
.run(test
)
2052 print f
, "of", t
, "examples failed in string", name
2055 def rundoc(self
, object, name
=None, module
=None):
2057 tests
= self
.testfinder
.find(object, name
, module
=module
,
2060 (f2
, t2
) = self
.testrunner
.run(test
)
2061 (f
,t
) = (f
+f2
, t
+t2
)
2064 def rundict(self
, d
, name
, module
=None):
2066 m
= new
.module(name
)
2067 m
.__dict
__.update(d
)
2070 return self
.rundoc(m
, name
, module
)
2072 def run__test__(self
, d
, name
):
2074 m
= new
.module(name
)
2076 return self
.rundoc(m
, name
)
2078 def summarize(self
, verbose
=None):
2079 return self
.testrunner
.summarize(verbose
)
2081 def merge(self
, other
):
2082 self
.testrunner
.merge(other
.testrunner
)
2084 ######################################################################
2085 ## 8. Unittest Support
2086 ######################################################################
2088 _unittest_reportflags
= 0
2090 def set_unittest_reportflags(flags
):
2091 """Sets the unittest option flags.
2093 The old flag is returned so that a runner could restore the old
2094 value if it wished to:
2097 >>> old = doctest._unittest_reportflags
2098 >>> doctest.set_unittest_reportflags(REPORT_NDIFF |
2099 ... REPORT_ONLY_FIRST_FAILURE) == old
2102 >>> doctest._unittest_reportflags == (REPORT_NDIFF |
2103 ... REPORT_ONLY_FIRST_FAILURE)
2106 Only reporting flags can be set:
2108 >>> doctest.set_unittest_reportflags(ELLIPSIS)
2109 Traceback (most recent call last):
2111 ValueError: ('Only reporting flags allowed', 8)
2113 >>> doctest.set_unittest_reportflags(old) == (REPORT_NDIFF |
2114 ... REPORT_ONLY_FIRST_FAILURE)
2117 global _unittest_reportflags
2119 if (flags
& REPORTING_FLAGS
) != flags
:
2120 raise ValueError("Only reporting flags allowed", flags
)
2121 old
= _unittest_reportflags
2122 _unittest_reportflags
= flags
2126 class DocTestCase(unittest
.TestCase
):
2128 def __init__(self
, test
, optionflags
=0, setUp
=None, tearDown
=None,
2131 unittest
.TestCase
.__init
__(self
)
2132 self
._dt
_optionflags
= optionflags
2133 self
._dt
_checker
= checker
2134 self
._dt
_test
= test
2135 self
._dt
_setUp
= setUp
2136 self
._dt
_tearDown
= tearDown
2139 test
= self
._dt
_test
2141 if self
._dt
_setUp
is not None:
2142 self
._dt
_setUp
(test
)
2145 test
= self
._dt
_test
2147 if self
._dt
_tearDown
is not None:
2148 self
._dt
_tearDown
(test
)
2153 test
= self
._dt
_test
2156 optionflags
= self
._dt
_optionflags
2158 if not (optionflags
& REPORTING_FLAGS
):
2159 # The option flags don't include any reporting flags,
2160 # so add the default reporting flags
2161 optionflags |
= _unittest_reportflags
2163 runner
= DocTestRunner(optionflags
=optionflags
,
2164 checker
=self
._dt
_checker
, verbose
=False)
2167 runner
.DIVIDER
= "-"*70
2168 failures
, tries
= runner
.run(
2169 test
, out
=new
.write
, clear_globs
=False)
2174 raise self
.failureException(self
.format_failure(new
.getvalue()))
2176 def format_failure(self
, err
):
2177 test
= self
._dt
_test
2178 if test
.lineno
is None:
2179 lineno
= 'unknown line number'
2181 lineno
= '%s' % test
.lineno
2182 lname
= '.'.join(test
.name
.split('.')[-1:])
2183 return ('Failed doctest test for %s\n'
2184 ' File "%s", line %s, in %s\n\n%s'
2185 % (test
.name
, test
.filename
, lineno
, lname
, err
)
2189 r
"""Run the test case without results and without catching exceptions
2191 The unit test framework includes a debug method on test cases
2192 and test suites to support post-mortem debugging. The test code
2193 is run in such a way that errors are not caught. This way a
2194 caller can catch the errors and initiate post-mortem debugging.
2196 The DocTestCase provides a debug method that raises
2197 UnexpectedException errors if there is an unexepcted
2200 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
2201 ... {}, 'foo', 'foo.py', 0)
2202 >>> case = DocTestCase(test)
2205 ... except UnexpectedException, failure:
2208 The UnexpectedException contains the test, the example, and
2209 the original exception:
2211 >>> failure.test is test
2214 >>> failure.example.want
2217 >>> exc_info = failure.exc_info
2218 >>> raise exc_info[0], exc_info[1], exc_info[2]
2219 Traceback (most recent call last):
2223 If the output doesn't match, then a DocTestFailure is raised:
2225 >>> test = DocTestParser().get_doctest('''
2229 ... ''', {}, 'foo', 'foo.py', 0)
2230 >>> case = DocTestCase(test)
2234 ... except DocTestFailure, failure:
2237 DocTestFailure objects provide access to the test:
2239 >>> failure.test is test
2242 As well as to the example:
2244 >>> failure.example.want
2247 and the actual output:
2255 runner
= DebugRunner(optionflags
=self
._dt
_optionflags
,
2256 checker
=self
._dt
_checker
, verbose
=False)
2257 runner
.run(self
._dt
_test
)
2261 return self
._dt
_test
.name
2264 name
= self
._dt
_test
.name
.split('.')
2265 return "%s (%s)" % (name
[-1], '.'.join(name
[:-1]))
2269 def shortDescription(self
):
2270 return "Doctest: " + self
._dt
_test
.name
2272 def DocTestSuite(module
=None, globs
=None, extraglobs
=None, test_finder
=None,
2275 Convert doctest tests for a module to a unittest test suite.
2277 This converts each documentation string in a module that
2278 contains doctest tests to a unittest test case. If any of the
2279 tests in a doc string fail, then the test case fails. An exception
2280 is raised showing the name of the file containing the test and a
2281 (sometimes approximate) line number.
2283 The `module` argument provides the module to be tested. The argument
2284 can be either a module or a module name.
2286 If no argument is given, the calling module is used.
2288 A number of options may be provided as keyword arguments:
2291 A set-up function. This is called before running the
2292 tests in each file. The setUp function will be passed a DocTest
2293 object. The setUp function can access the test globals as the
2294 globs attribute of the test passed.
2297 A tear-down function. This is called after running the
2298 tests in each file. The tearDown function will be passed a DocTest
2299 object. The tearDown function can access the test globals as the
2300 globs attribute of the test passed.
2303 A dictionary containing initial global variables for the tests.
2306 A set of doctest option flags expressed as an integer.
2309 if test_finder
is None:
2310 test_finder
= DocTestFinder()
2312 module
= _normalize_module(module
)
2313 tests
= test_finder
.find(module
, globs
=globs
, extraglobs
=extraglobs
)
2315 globs
= module
.__dict
__
2317 # Why do we want to do this? Because it reveals a bug that might
2318 # otherwise be hidden.
2319 raise ValueError(module
, "has no tests")
2322 suite
= unittest
.TestSuite()
2324 if len(test
.examples
) == 0:
2326 if not test
.filename
:
2327 filename
= module
.__file
__
2328 if filename
[-4:] in (".pyc", ".pyo"):
2329 filename
= filename
[:-1]
2330 test
.filename
= filename
2331 suite
.addTest(DocTestCase(test
, **options
))
2335 class DocFileCase(DocTestCase
):
2338 return '_'.join(self
._dt
_test
.name
.split('.'))
2341 return self
._dt
_test
.filename
2344 def format_failure(self
, err
):
2345 return ('Failed doctest test for %s\n File "%s", line 0\n\n%s'
2346 % (self
._dt
_test
.name
, self
._dt
_test
.filename
, err
)
2349 def DocFileTest(path
, module_relative
=True, package
=None,
2350 globs
=None, parser
=DocTestParser(),
2351 encoding
=None, **options
):
2355 globs
= globs
.copy()
2357 if package
and not module_relative
:
2358 raise ValueError("Package may only be specified for module-"
2361 # Relativize the path.
2362 doc
, path
= _load_testfile(path
, package
, module_relative
)
2364 if "__file__" not in globs
:
2365 globs
["__file__"] = path
2367 # Find the file and read it.
2368 name
= os
.path
.basename(path
)
2370 # If an encoding is specified, use it to convert the file to unicode
2371 if encoding
is not None:
2372 doc
= doc
.decode(encoding
)
2374 # Convert it to a test, and wrap it in a DocFileCase.
2375 test
= parser
.get_doctest(doc
, globs
, name
, path
, 0)
2376 return DocFileCase(test
, **options
)
2378 def DocFileSuite(*paths
, **kw
):
2379 """A unittest suite for one or more doctest files.
2381 The path to each doctest file is given as a string; the
2382 interpretation of that string depends on the keyword argument
2385 A number of options may be provided as keyword arguments:
2388 If "module_relative" is True, then the given file paths are
2389 interpreted as os-independent module-relative paths. By
2390 default, these paths are relative to the calling module's
2391 directory; but if the "package" argument is specified, then
2392 they are relative to that package. To ensure os-independence,
2393 "filename" should use "/" characters to separate path
2394 segments, and may not be an absolute path (i.e., it may not
2397 If "module_relative" is False, then the given file paths are
2398 interpreted as os-specific paths. These paths may be absolute
2399 or relative (to the current working directory).
2402 A Python package or the name of a Python package whose directory
2403 should be used as the base directory for module relative paths.
2404 If "package" is not specified, then the calling module's
2405 directory is used as the base directory for module relative
2406 filenames. It is an error to specify "package" if
2407 "module_relative" is False.
2410 A set-up function. This is called before running the
2411 tests in each file. The setUp function will be passed a DocTest
2412 object. The setUp function can access the test globals as the
2413 globs attribute of the test passed.
2416 A tear-down function. This is called after running the
2417 tests in each file. The tearDown function will be passed a DocTest
2418 object. The tearDown function can access the test globals as the
2419 globs attribute of the test passed.
2422 A dictionary containing initial global variables for the tests.
2425 A set of doctest option flags expressed as an integer.
2428 A DocTestParser (or subclass) that should be used to extract
2429 tests from the files.
2432 An encoding that will be used to convert the files to unicode.
2434 suite
= unittest
.TestSuite()
2436 # We do this here so that _normalize_module is called at the right
2437 # level. If it were called in DocFileTest, then this function
2438 # would be the caller and we might guess the package incorrectly.
2439 if kw
.get('module_relative', True):
2440 kw
['package'] = _normalize_module(kw
.get('package'))
2443 suite
.addTest(DocFileTest(path
, **kw
))
2447 ######################################################################
2448 ## 9. Debugging Support
2449 ######################################################################
2451 def script_from_examples(s
):
2452 r
"""Extract script from text with examples.
2454 Converts text with examples to a Python script. Example input is
2455 converted to regular code. Example output and all other words
2456 are converted to comments:
2459 ... Here are examples of simple math.
2461 ... Python has super accurate integer addition
2466 ... And very friendly error messages:
2473 ... You can use logic if you want:
2483 >>> print script_from_examples(text)
2484 # Here are examples of simple math.
2486 # Python has super accurate integer addition
2492 # And very friendly error messages:
2500 # You can use logic if you want:
2510 for piece
in DocTestParser().parse(s
):
2511 if isinstance(piece
, Example
):
2512 # Add the example's source code (strip trailing NL)
2513 output
.append(piece
.source
[:-1])
2514 # Add the expected output:
2517 output
.append('# Expected:')
2518 output
+= ['## '+l
for l
in want
.split('\n')[:-1]]
2520 # Add non-example text.
2521 output
+= [_comment_line(l
)
2522 for l
in piece
.split('\n')[:-1]]
2524 # Trim junk on both ends.
2525 while output
and output
[-1] == '#':
2527 while output
and output
[0] == '#':
2529 # Combine the output, and return it.
2530 # Add a courtesy newline to prevent exec from choking (see bug #1172785)
2531 return '\n'.join(output
) + '\n'
2533 def testsource(module
, name
):
2534 """Extract the test sources from a doctest docstring as a script.
2536 Provide the module (or dotted name of the module) containing the
2537 test to be debugged and the name (within the module) of the object
2538 with the doc string with tests to be debugged.
2540 module
= _normalize_module(module
)
2541 tests
= DocTestFinder().find(module
)
2542 test
= [t
for t
in tests
if t
.name
== name
]
2544 raise ValueError(name
, "not found in tests")
2546 testsrc
= script_from_examples(test
.docstring
)
2549 def debug_src(src
, pm
=False, globs
=None):
2550 """Debug a single doctest docstring, in argument `src`'"""
2551 testsrc
= script_from_examples(src
)
2552 debug_script(testsrc
, pm
, globs
)
2554 def debug_script(src
, pm
=False, globs
=None):
2555 "Debug a test script. `src` is the script, as a string."
2558 # Note that tempfile.NameTemporaryFile() cannot be used. As the
2559 # docs say, a file so created cannot be opened by name a second time
2560 # on modern Windows boxes, and execfile() needs to open it.
2561 srcfilename
= tempfile
.mktemp(".py", "doctestdebug")
2562 f
= open(srcfilename
, 'w')
2568 globs
= globs
.copy()
2574 execfile(srcfilename
, globs
, globs
)
2576 print sys
.exc_info()[1]
2577 pdb
.post_mortem(sys
.exc_info()[2])
2579 # Note that %r is vital here. '%s' instead can, e.g., cause
2580 # backslashes to get treated as metacharacters on Windows.
2581 pdb
.run("execfile(%r)" % srcfilename
, globs
, globs
)
2584 os
.remove(srcfilename
)
2586 def debug(module
, name
, pm
=False):
2587 """Debug a single doctest docstring.
2589 Provide the module (or dotted name of the module) containing the
2590 test to be debugged and the name (within the module) of the object
2591 with the docstring with tests to be debugged.
2593 module
= _normalize_module(module
)
2594 testsrc
= testsource(module
, name
)
2595 debug_script(testsrc
, pm
, module
.__dict
__)
2597 ######################################################################
2598 ## 10. Example Usage
2599 ######################################################################
2602 A pointless class, for sanity-checking of docstring testing.
2608 >>> _TestClass(13).get() + _TestClass(-12).get()
2610 >>> hex(_TestClass(13).square().get())
2614 def __init__(self
, val
):
2615 """val -> _TestClass object with associated value val.
2617 >>> t = _TestClass(123)
2625 """square() -> square TestClass's associated value
2627 >>> _TestClass(13).square().get()
2631 self
.val
= self
.val
** 2
2635 """get() -> return TestClass's associated value.
2637 >>> x = _TestClass(-42)
2644 __test__
= {"_TestClass": _TestClass
,
2646 Example of a string object, searched as-is.
2652 "bool-int equivalence": r
"""
2653 In 2.2, boolean expressions displayed
2654 0 or 1. By default, we still accept
2655 them. This can be disabled by passing
2656 DONT_ACCEPT_TRUE_FOR_1 to the new
2657 optionflags argument.
2669 Blank lines can be marked with <BLANKLINE>:
2670 >>> print 'foo\n\nbar\n'
2678 If the ellipsis flag is used, then '...' can be used to
2679 elide substrings in the desired output:
2680 >>> print range(1000) #doctest: +ELLIPSIS
2684 "whitespace normalization": r
"""
2685 If the whitespace normalization flag is used, then
2686 differences in whitespace are ignored.
2687 >>> print range(30) #doctest: +NORMALIZE_WHITESPACE
2688 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
2689 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,
2695 r
= unittest
.TextTestRunner()
2696 r
.run(DocTestSuite())
2698 if __name__
== "__main__":