2 # Released to the public domain 16-Jan-2001, by Tim Peters (tim@python.org).
3 # Major enhancements and refactoring by:
7 # Provided as-is; use at your own risk; no warranty; no promises; enjoy!
9 r
"""Module doctest -- a framework for running examples in docstrings.
11 In simplest use, end each module M to be tested with:
17 if __name__ == "__main__":
20 Then running the module as a script will cause the examples in the
21 docstrings to get executed and verified:
25 This won't display anything unless an example fails, in which case the
26 failing example(s) and the cause(s) of the failure(s) are printed to stdout
27 (why not stderr? because stderr is a lame hack <0.2 wink>), and the final
28 line of output is "Test failed.".
30 Run it with the -v switch instead:
34 and a detailed report of all examples tried is printed to stdout, along
35 with assorted summaries at the end.
37 You can force verbose mode by passing "verbose=True" to testmod, or prohibit
38 it by passing "verbose=False". In either of those cases, sys.argv is not
41 There are a variety of other ways to run doctests, including integration
42 with the unittest framework, and support for running non-Python text
43 files containing doctests. There are also many ways to override parts
44 of doctest's default behaviors. See the Library Reference Manual for
48 __docformat__
= 'reStructuredText en'
52 'register_optionflag',
53 'DONT_ACCEPT_TRUE_FOR_1',
54 'DONT_ACCEPT_BLANKLINE',
55 'NORMALIZE_WHITESPACE',
58 'IGNORE_EXCEPTION_DETAIL',
63 'REPORT_ONLY_FIRST_FAILURE',
65 # 1. Utility Functions
66 # 2. Example & DocTest
77 'UnexpectedException',
82 'run_docstring_examples',
88 'set_unittest_reportflags',
89 # 9. Debugging Support
90 'script_from_examples',
98 import sys
, traceback
, inspect
, linecache
, os
, re
99 import unittest
, difflib
, pdb
, tempfile
101 from StringIO
import StringIO
102 from collections
import namedtuple
104 TestResults
= namedtuple('TestResults', 'failed attempted')
106 # There are 4 basic classes:
107 # - Example: a <source, want> pair, plus an intra-docstring line number.
108 # - DocTest: a collection of examples, parsed from a docstring, plus
109 # info about where the docstring came from (name, filename, lineno).
110 # - DocTestFinder: extracts DocTests from a given object's docstring and
111 # its contained objects' docstrings.
112 # - DocTestRunner: runs DocTest cases, and accumulates statistics.
114 # So the basic picture is:
117 # +------+ +---------+ +-------+
118 # |object| --DocTestFinder-> | DocTest | --DocTestRunner-> |results|
119 # +------+ +---------+ +-------+
127 OPTIONFLAGS_BY_NAME
= {}
128 def register_optionflag(name
):
129 # Create a new flag unless `name` is already known.
130 return OPTIONFLAGS_BY_NAME
.setdefault(name
, 1 << len(OPTIONFLAGS_BY_NAME
))
132 DONT_ACCEPT_TRUE_FOR_1
= register_optionflag('DONT_ACCEPT_TRUE_FOR_1')
133 DONT_ACCEPT_BLANKLINE
= register_optionflag('DONT_ACCEPT_BLANKLINE')
134 NORMALIZE_WHITESPACE
= register_optionflag('NORMALIZE_WHITESPACE')
135 ELLIPSIS
= register_optionflag('ELLIPSIS')
136 SKIP
= register_optionflag('SKIP')
137 IGNORE_EXCEPTION_DETAIL
= register_optionflag('IGNORE_EXCEPTION_DETAIL')
139 COMPARISON_FLAGS
= (DONT_ACCEPT_TRUE_FOR_1 |
140 DONT_ACCEPT_BLANKLINE |
141 NORMALIZE_WHITESPACE |
144 IGNORE_EXCEPTION_DETAIL
)
146 REPORT_UDIFF
= register_optionflag('REPORT_UDIFF')
147 REPORT_CDIFF
= register_optionflag('REPORT_CDIFF')
148 REPORT_NDIFF
= register_optionflag('REPORT_NDIFF')
149 REPORT_ONLY_FIRST_FAILURE
= register_optionflag('REPORT_ONLY_FIRST_FAILURE')
151 REPORTING_FLAGS
= (REPORT_UDIFF |
154 REPORT_ONLY_FIRST_FAILURE
)
156 # Special string markers for use in `want` strings:
157 BLANKLINE_MARKER
= '<BLANKLINE>'
158 ELLIPSIS_MARKER
= '...'
160 ######################################################################
162 ######################################################################
163 # 1. Utility Functions
164 # 2. Example & DocTest -- store test cases
165 # 3. DocTest Parser -- extracts examples from strings
166 # 4. DocTest Finder -- extracts test cases from objects
167 # 5. DocTest Runner -- runs test cases
168 # 6. Test Functions -- convenient wrappers for testing
169 # 7. Tester Class -- for backwards compatibility
170 # 8. Unittest Support
171 # 9. Debugging Support
174 ######################################################################
175 ## 1. Utility Functions
176 ######################################################################
178 def _extract_future_flags(globs
):
180 Return the compiler-flags associated with the future features that
181 have been imported into the given namespace (globs).
184 for fname
in __future__
.all_feature_names
:
185 feature
= globs
.get(fname
, None)
186 if feature
is getattr(__future__
, fname
):
187 flags |
= feature
.compiler_flag
190 def _normalize_module(module
, depth
=2):
192 Return the module specified by `module`. In particular:
193 - If `module` is a module, then return module.
194 - If `module` is a string, then import and return the
195 module with that name.
196 - If `module` is None, then return the calling module.
197 The calling module is assumed to be the module of
198 the stack frame at the given depth in the call stack.
200 if inspect
.ismodule(module
):
202 elif isinstance(module
, (str, unicode)):
203 return __import__(module
, globals(), locals(), ["*"])
205 return sys
.modules
[sys
._getframe
(depth
).f_globals
['__name__']]
207 raise TypeError("Expected a module, string, or None")
209 def _load_testfile(filename
, package
, module_relative
):
211 package
= _normalize_module(package
, 3)
212 filename
= _module_relative_path(package
, filename
)
213 if hasattr(package
, '__loader__'):
214 if hasattr(package
.__loader
__, 'get_data'):
215 file_contents
= package
.__loader
__.get_data(filename
)
216 # get_data() opens files as 'rb', so one must do the equivalent
217 # conversion as universal newlines would do.
218 return file_contents
.replace(os
.linesep
, '\n'), filename
219 with
open(filename
) as f
:
220 return f
.read(), filename
222 # Use sys.stdout encoding for ouput.
223 _encoding
= getattr(sys
.__stdout
__, 'encoding', None) or 'utf-8'
225 def _indent(s
, indent
=4):
227 Add the given number of space characters to the beginning of
228 every non-blank line in `s`, and return the result.
229 If the string `s` is Unicode, it is encoded using the stdout
230 encoding and the `backslashreplace` error handler.
232 if isinstance(s
, unicode):
233 s
= s
.encode(_encoding
, 'backslashreplace')
234 # This regexp matches the start of non-blank lines:
235 return re
.sub('(?m)^(?!$)', indent
*' ', s
)
237 def _exception_traceback(exc_info
):
239 Return a string containing a traceback message for the given
240 exc_info tuple (as returned by sys.exc_info()).
242 # Get a traceback message.
244 exc_type
, exc_val
, exc_tb
= exc_info
245 traceback
.print_exception(exc_type
, exc_val
, exc_tb
, file=excout
)
246 return excout
.getvalue()
248 # Override some StringIO methods.
249 class _SpoofOut(StringIO
):
251 result
= StringIO
.getvalue(self
)
252 # If anything at all was written, make sure there's a trailing
253 # newline. There's no way for the expected output to indicate
254 # that a trailing newline is missing.
255 if result
and not result
.endswith("\n"):
257 # Prevent softspace from screwing up the next test case, in
258 # case they used print with a trailing comma in an example.
259 if hasattr(self
, "softspace"):
263 def truncate(self
, size
=None):
264 StringIO
.truncate(self
, size
)
265 if hasattr(self
, "softspace"):
268 # Reset it to an empty string, to make sure it's not unicode.
271 # Worst-case linear-time ellipsis matching.
272 def _ellipsis_match(want
, got
):
274 Essentially the only subtle case:
275 >>> _ellipsis_match('aa...aa', 'aaa')
278 if ELLIPSIS_MARKER
not in want
:
281 # Find "the real" strings.
282 ws
= want
.split(ELLIPSIS_MARKER
)
285 # Deal with exact matches possibly needed at one or both ends.
286 startpos
, endpos
= 0, len(got
)
288 if w
: # starts with exact match
289 if got
.startswith(w
):
295 if w
: # ends with exact match
302 if startpos
> endpos
:
303 # Exact end matches required more characters than we have, as in
304 # _ellipsis_match('aa...aa', 'aaa')
307 # For the rest, we only need to find the leftmost non-overlapping
308 # match for each piece. If there's no overall match that way alone,
309 # there's no overall match period.
311 # w may be '' at times, if there are consecutive ellipses, or
312 # due to an ellipsis at the start or end of `want`. That's OK.
313 # Search for an empty string succeeds, and doesn't change startpos.
314 startpos
= got
.find(w
, startpos
, endpos
)
321 def _comment_line(line
):
322 "Return a commented form of the given line"
329 class _OutputRedirectingPdb(pdb
.Pdb
):
331 A specialized version of the python debugger that redirects stdout
332 to a given stream when interacting with the user. Stdout is *not*
333 redirected when traced code is executed.
335 def __init__(self
, out
):
337 self
.__debugger
_used
= False
338 pdb
.Pdb
.__init
__(self
, stdout
=out
)
339 # still use input() to get user input
340 self
.use_rawinput
= 1
342 def set_trace(self
, frame
=None):
343 self
.__debugger
_used
= True
345 frame
= sys
._getframe
().f_back
346 pdb
.Pdb
.set_trace(self
, frame
)
348 def set_continue(self
):
349 # Calling set_continue unconditionally would break unit test
350 # coverage reporting, as Bdb.set_continue calls sys.settrace(None).
351 if self
.__debugger
_used
:
352 pdb
.Pdb
.set_continue(self
)
354 def trace_dispatch(self
, *args
):
355 # Redirect stdout to the given stream.
356 save_stdout
= sys
.stdout
357 sys
.stdout
= self
.__out
358 # Call Pdb's trace dispatch method.
360 return pdb
.Pdb
.trace_dispatch(self
, *args
)
362 sys
.stdout
= save_stdout
364 # [XX] Normalize with respect to os.path.pardir?
365 def _module_relative_path(module
, path
):
366 if not inspect
.ismodule(module
):
367 raise TypeError, 'Expected a module: %r' % module
368 if path
.startswith('/'):
369 raise ValueError, 'Module-relative files may not have absolute paths'
371 # Find the base directory for the path.
372 if hasattr(module
, '__file__'):
373 # A normal module/package
374 basedir
= os
.path
.split(module
.__file
__)[0]
375 elif module
.__name
__ == '__main__':
376 # An interactive session.
377 if len(sys
.argv
)>0 and sys
.argv
[0] != '':
378 basedir
= os
.path
.split(sys
.argv
[0])[0]
382 # A module w/o __file__ (this includes builtins)
383 raise ValueError("Can't resolve paths relative to the module " +
384 module
+ " (it has no __file__)")
386 # Combine the base directory and the path.
387 return os
.path
.join(basedir
, *(path
.split('/')))
389 ######################################################################
390 ## 2. Example & DocTest
391 ######################################################################
392 ## - An "example" is a <source, want> pair, where "source" is a
393 ## fragment of source code, and "want" is the expected output for
394 ## "source." The Example class also includes information about
395 ## where the example was extracted from.
397 ## - A "doctest" is a collection of examples, typically extracted from
398 ## a string (such as an object's docstring). The DocTest class also
399 ## includes information about where the string was extracted from.
403 A single doctest example, consisting of source code and expected
404 output. `Example` defines the following attributes:
406 - source: A single Python statement, always ending with a newline.
407 The constructor adds a newline if needed.
409 - want: The expected output from running the source code (either
410 from stdout, or a traceback in case of exception). `want` ends
411 with a newline unless it's empty, in which case it's an empty
412 string. The constructor adds a newline if needed.
414 - exc_msg: The exception message generated by the example, if
415 the example is expected to generate an exception; or `None` if
416 it is not expected to generate an exception. This exception
417 message is compared against the return value of
418 `traceback.format_exception_only()`. `exc_msg` ends with a
419 newline unless it's `None`. The constructor adds a newline
422 - lineno: The line number within the DocTest string containing
423 this Example where the Example begins. This line number is
424 zero-based, with respect to the beginning of the DocTest.
426 - indent: The example's indentation in the DocTest string.
427 I.e., the number of space characters that preceed the
428 example's first prompt.
430 - options: A dictionary mapping from option flags to True or
431 False, which is used to override default options for this
432 example. Any option flags not contained in this dictionary
433 are left at their default value (as specified by the
434 DocTestRunner's optionflags). By default, no options are set.
436 def __init__(self
, source
, want
, exc_msg
=None, lineno
=0, indent
=0,
439 if not source
.endswith('\n'):
441 if want
and not want
.endswith('\n'):
443 if exc_msg
is not None and not exc_msg
.endswith('\n'):
450 if options
is None: options
= {}
451 self
.options
= options
452 self
.exc_msg
= exc_msg
456 A collection of doctest examples that should be run in a single
457 namespace. Each `DocTest` defines the following attributes:
459 - examples: the list of examples.
461 - globs: The namespace (aka globals) that the examples should
464 - name: A name identifying the DocTest (typically, the name of
465 the object whose docstring this DocTest was extracted from).
467 - filename: The name of the file that this DocTest was extracted
468 from, or `None` if the filename is unknown.
470 - lineno: The line number within filename where this DocTest
471 begins, or `None` if the line number is unavailable. This
472 line number is zero-based, with respect to the beginning of
475 - docstring: The string that the examples were extracted from,
476 or `None` if the string is unavailable.
478 def __init__(self
, examples
, globs
, name
, filename
, lineno
, docstring
):
480 Create a new DocTest containing the given examples. The
481 DocTest's globals are initialized with a copy of `globs`.
483 assert not isinstance(examples
, basestring
), \
484 "DocTest no longer accepts str; use DocTestParser instead"
485 self
.examples
= examples
486 self
.docstring
= docstring
487 self
.globs
= globs
.copy()
489 self
.filename
= filename
493 if len(self
.examples
) == 0:
494 examples
= 'no examples'
495 elif len(self
.examples
) == 1:
496 examples
= '1 example'
498 examples
= '%d examples' % len(self
.examples
)
499 return ('<DocTest %s from %s:%s (%s)>' %
500 (self
.name
, self
.filename
, self
.lineno
, examples
))
503 # This lets us sort tests by name:
504 def __cmp__(self
, other
):
505 if not isinstance(other
, DocTest
):
507 return cmp((self
.name
, self
.filename
, self
.lineno
, id(self
)),
508 (other
.name
, other
.filename
, other
.lineno
, id(other
)))
510 ######################################################################
512 ######################################################################
516 A class used to parse strings containing doctest examples.
518 # This regular expression is used to find doctest examples in a
519 # string. It defines three groups: `source` is the source code
520 # (including leading indentation and prompts); `indent` is the
521 # indentation of the first (PS1) line of the source code; and
522 # `want` is the expected output (including leading indentation).
523 _EXAMPLE_RE
= re
.compile(r
'''
524 # Source consists of a PS1 line followed by zero or more PS2 lines.
526 (?:^(?P<indent> [ ]*) >>> .*) # PS1 line
527 (?:\n [ ]* \.\.\. .*)*) # PS2 lines
529 # Want consists of any non-blank lines that do not start with PS1.
530 (?P<want> (?:(?![ ]*$) # Not a blank line
531 (?![ ]*>>>) # Not a line starting with PS1
532 .*$\n? # But any other line
534 ''', re
.MULTILINE | re
.VERBOSE
)
536 # A regular expression for handling `want` strings that contain
537 # expected exceptions. It divides `want` into three pieces:
538 # - the traceback header line (`hdr`)
539 # - the traceback stack (`stack`)
540 # - the exception message (`msg`), as generated by
541 # traceback.format_exception_only()
542 # `msg` may have multiple lines. We assume/require that the
543 # exception message is the first non-indented line starting with a word
544 # character following the traceback header line.
545 _EXCEPTION_RE
= re
.compile(r
"""
546 # Grab the traceback header. Different versions of Python have
547 # said different things on the first traceback line.
548 ^(?P<hdr> Traceback\ \(
549 (?: most\ recent\ call\ last
553 \s* $ # toss trailing whitespace on the header.
554 (?P<stack> .*?) # don't blink: absorb stuff until...
555 ^ (?P<msg> \w+ .*) # a line *starts* with alphanum.
556 """, re
.VERBOSE | re
.MULTILINE | re
.DOTALL
)
558 # A callable returning a true value iff its argument is a blank line
559 # or contains a single comment.
560 _IS_BLANK_OR_COMMENT
= re
.compile(r
'^[ ]*(#.*)?$').match
562 def parse(self
, string
, name
='<string>'):
564 Divide the given string into examples and intervening text,
565 and return them as a list of alternating Examples and strings.
566 Line numbers for the Examples are 0-based. The optional
567 argument `name` is a name identifying this string, and is only
568 used for error messages.
570 string
= string
.expandtabs()
571 # If all lines begin with the same indentation, then strip it.
572 min_indent
= self
._min
_indent
(string
)
574 string
= '\n'.join([l
[min_indent
:] for l
in string
.split('\n')])
577 charno
, lineno
= 0, 0
578 # Find all doctest examples in the string:
579 for m
in self
._EXAMPLE
_RE
.finditer(string
):
580 # Add the pre-example text to `output`.
581 output
.append(string
[charno
:m
.start()])
582 # Update lineno (lines before this example)
583 lineno
+= string
.count('\n', charno
, m
.start())
584 # Extract info from the regexp match.
585 (source
, options
, want
, exc_msg
) = \
586 self
._parse
_example
(m
, name
, lineno
)
587 # Create an Example, and add it to the list.
588 if not self
._IS
_BLANK
_OR
_COMMENT
(source
):
589 output
.append( Example(source
, want
, exc_msg
,
591 indent
=min_indent
+len(m
.group('indent')),
593 # Update lineno (lines inside this example)
594 lineno
+= string
.count('\n', m
.start(), m
.end())
597 # Add any remaining post-example text to `output`.
598 output
.append(string
[charno
:])
601 def get_doctest(self
, string
, globs
, name
, filename
, lineno
):
603 Extract all doctest examples from the given string, and
604 collect them into a `DocTest` object.
606 `globs`, `name`, `filename`, and `lineno` are attributes for
607 the new `DocTest` object. See the documentation for `DocTest`
608 for more information.
610 return DocTest(self
.get_examples(string
, name
), globs
,
611 name
, filename
, lineno
, string
)
613 def get_examples(self
, string
, name
='<string>'):
615 Extract all doctest examples from the given string, and return
616 them as a list of `Example` objects. Line numbers are
617 0-based, because it's most common in doctests that nothing
618 interesting appears on the same line as opening triple-quote,
619 and so the first interesting line is called \"line 1\" then.
621 The optional argument `name` is a name identifying this
622 string, and is only used for error messages.
624 return [x
for x
in self
.parse(string
, name
)
625 if isinstance(x
, Example
)]
627 def _parse_example(self
, m
, name
, lineno
):
629 Given a regular expression match from `_EXAMPLE_RE` (`m`),
630 return a pair `(source, want)`, where `source` is the matched
631 example's source code (with prompts and indentation stripped);
632 and `want` is the example's expected output (with indentation
635 `name` is the string's name, and `lineno` is the line number
636 where the example starts; both are used for error messages.
638 # Get the example's indentation level.
639 indent
= len(m
.group('indent'))
641 # Divide source into lines; check that they're properly
642 # indented; and then strip their indentation & prompts.
643 source_lines
= m
.group('source').split('\n')
644 self
._check
_prompt
_blank
(source_lines
, indent
, name
, lineno
)
645 self
._check
_prefix
(source_lines
[1:], ' '*indent
+ '.', name
, lineno
)
646 source
= '\n'.join([sl
[indent
+4:] for sl
in source_lines
])
648 # Divide want into lines; check that it's properly indented; and
649 # then strip the indentation. Spaces before the last newline should
650 # be preserved, so plain rstrip() isn't good enough.
651 want
= m
.group('want')
652 want_lines
= want
.split('\n')
653 if len(want_lines
) > 1 and re
.match(r
' *$', want_lines
[-1]):
654 del want_lines
[-1] # forget final newline & spaces after it
655 self
._check
_prefix
(want_lines
, ' '*indent
, name
,
656 lineno
+ len(source_lines
))
657 want
= '\n'.join([wl
[indent
:] for wl
in want_lines
])
659 # If `want` contains a traceback message, then extract it.
660 m
= self
._EXCEPTION
_RE
.match(want
)
662 exc_msg
= m
.group('msg')
666 # Extract options from the source.
667 options
= self
._find
_options
(source
, name
, lineno
)
669 return source
, options
, want
, exc_msg
671 # This regular expression looks for option directives in the
672 # source code of an example. Option directives are comments
673 # starting with "doctest:". Warning: this may give false
674 # positives for string-literals that contain the string
675 # "#doctest:". Eliminating these false positives would require
676 # actually parsing the string; but we limit them by ignoring any
677 # line containing "#doctest:" that is *followed* by a quote mark.
678 _OPTION_DIRECTIVE_RE
= re
.compile(r
'#\s*doctest:\s*([^\n\'"]*)$',
681 def _find_options(self, source, name, lineno):
683 Return a dictionary containing option overrides extracted from
684 option directives in the given source string.
686 `name` is the string's name, and `lineno` is the line number
687 where the example starts; both are used for error messages.
690 # (note: with the current regexp, this will match at most once:)
691 for m in self._OPTION_DIRECTIVE_RE.finditer(source):
692 option_strings = m.group(1).replace(',', ' ').split()
693 for option in option_strings:
694 if (option[0] not in '+-' or
695 option[1:] not in OPTIONFLAGS_BY_NAME):
696 raise ValueError('line %r of the doctest for %s '
697 'has an invalid option: %r' %
698 (lineno+1, name, option))
699 flag = OPTIONFLAGS_BY_NAME[option[1:]]
700 options[flag] = (option[0] == '+')
701 if options and self._IS_BLANK_OR_COMMENT(source):
702 raise ValueError('line %r of the doctest for %s has an option '
703 'directive on a line with no example: %r' %
704 (lineno, name, source))
707 # This regular expression finds the indentation of every non-blank
709 _INDENT_RE = re.compile('^([ ]*)(?=\S)', re.MULTILINE)
711 def _min_indent(self, s):
712 "Return the minimum indentation of any non
-blank line
in `s`
"
713 indents = [len(indent) for indent in self._INDENT_RE.findall(s)]
719 def _check_prompt_blank(self, lines, indent, name, lineno):
721 Given the lines of a source string (including prompts and
722 leading indentation), check to make sure that every prompt is
723 followed by a space character. If any line is not followed by
724 a space character, then raise ValueError.
726 for i, line in enumerate(lines):
727 if len(line) >= indent+4 and line[indent+3] != ' ':
728 raise ValueError('line %r of the docstring for %s '
729 'lacks blank after %s: %r' %
731 line[indent:indent+3], line))
733 def _check_prefix(self, lines, prefix, name, lineno):
735 Check that every line in the given list starts with the given
736 prefix; if any line does not, then raise a ValueError.
738 for i, line in enumerate(lines):
739 if line and not line.startswith(prefix):
740 raise ValueError('line %r of the docstring for %s has '
741 'inconsistent leading whitespace: %r' %
742 (lineno+i+1, name, line))
745 ######################################################################
747 ######################################################################
751 A class used to extract the DocTests that are relevant to a given
752 object, from its docstring and the docstrings of its contained
753 objects. Doctests can currently be extracted from the following
754 object types: modules, functions, classes, methods, staticmethods,
755 classmethods, and properties.
758 def __init__(self, verbose=False, parser=DocTestParser(),
759 recurse=True, exclude_empty=True):
761 Create a new doctest finder.
763 The optional argument `parser` specifies a class or
764 function that should be used to create new DocTest objects (or
765 objects that implement the same interface as DocTest). The
766 signature for this factory function should match the signature
767 of the DocTest constructor.
769 If the optional argument `recurse` is false, then `find` will
770 only examine the given object, and not any contained objects.
772 If the optional argument `exclude_empty` is false, then `find`
773 will include tests for objects with empty docstrings.
775 self._parser = parser
776 self._verbose = verbose
777 self._recurse = recurse
778 self._exclude_empty = exclude_empty
780 def find(self, obj, name=None, module=None, globs=None, extraglobs=None):
782 Return a list of the DocTests that are defined by the given
783 object's docstring, or by any of its contained objects'
786 The optional parameter `module` is the module that contains
787 the given object. If the module is not specified or is None, then
788 the test finder will attempt to automatically determine the
789 correct module. The object's module is used:
791 - As a default namespace, if `globs` is not specified.
792 - To prevent the DocTestFinder from extracting DocTests
793 from objects that are imported from other modules.
794 - To find the name of the file containing the object.
795 - To help find the line number of the object within its
798 Contained objects whose module does not match `module` are ignored.
800 If `module` is False, no attempt to find the module will be made.
801 This is obscure, of use mostly in tests: if `module` is False, or
802 is None but cannot be found automatically, then all objects are
803 considered to belong to the (non-existent) module, so all contained
804 objects will (recursively) be searched for doctests.
806 The globals for each DocTest is formed by combining `globs`
807 and `extraglobs` (bindings in `extraglobs` override bindings
808 in `globs`). A new copy of the globals dictionary is created
809 for each DocTest. If `globs` is not specified, then it
810 defaults to the module's `__dict__`, if specified, or {}
811 otherwise. If `extraglobs` is not specified, then it defaults
815 # If name was not specified, then extract it from the object.
817 name = getattr(obj, '__name__', None)
819 raise ValueError("DocTestFinder
.find
: name must be given
"
820 "when obj
.__name
__ doesn
't exist: %r" %
823 # Find the module that contains the given object (if obj is
824 # a module, then module=obj.). Note: this may fail, in which
825 # case module will be None.
829 module = inspect.getmodule(obj)
831 # Read the module's source code
. This
is used by
832 # DocTestFinder._find_lineno to find the line number for a
833 # given object's docstring.
835 file = inspect
.getsourcefile(obj
) or inspect
.getfile(obj
)
836 if module
is not None:
837 # Supply the module globals in case the module was
838 # originally loaded via a PEP 302 loader and
839 # file is not a valid filesystem path
840 source_lines
= linecache
.getlines(file, module
.__dict
__)
842 # No access to a loader, so assume it's a normal
844 source_lines
= linecache
.getlines(file)
850 # Initialize globals, and merge in extraglobs.
855 globs
= module
.__dict
__.copy()
858 if extraglobs
is not None:
859 globs
.update(extraglobs
)
860 if '__name__' not in globs
:
861 globs
['__name__'] = '__main__' # provide a default module name
863 # Recursively expore `obj`, extracting DocTests.
865 self
._find
(tests
, obj
, name
, module
, source_lines
, globs
, {})
866 # Sort the tests by alpha order of names, for consistency in
867 # verbose-mode output. This was a feature of doctest in Pythons
868 # <= 2.3 that got lost by accident in 2.4. It was repaired in
873 def _from_module(self
, module
, object):
875 Return true if the given object is defined in the given
880 elif inspect
.getmodule(object) is not None:
881 return module
is inspect
.getmodule(object)
882 elif inspect
.isfunction(object):
883 return module
.__dict
__ is object.func_globals
884 elif inspect
.isclass(object):
885 return module
.__name
__ == object.__module
__
886 elif hasattr(object, '__module__'):
887 return module
.__name
__ == object.__module
__
888 elif isinstance(object, property):
889 return True # [XX] no way not be sure.
891 raise ValueError("object must be a class or function")
893 def _find(self
, tests
, obj
, name
, module
, source_lines
, globs
, seen
):
895 Find tests for the given object and any contained objects, and
899 print 'Finding tests in %s' % name
901 # If we've already processed this object, then ignore it.
906 # Find a test for this object, and add it to the list of tests.
907 test
= self
._get
_test
(obj
, name
, module
, globs
, source_lines
)
911 # Look for tests in a module's contained objects.
912 if inspect
.ismodule(obj
) and self
._recurse
:
913 for valname
, val
in obj
.__dict
__.items():
914 valname
= '%s.%s' % (name
, valname
)
915 # Recurse to functions & classes.
916 if ((inspect
.isfunction(val
) or inspect
.isclass(val
)) and
917 self
._from
_module
(module
, val
)):
918 self
._find
(tests
, val
, valname
, module
, source_lines
,
921 # Look for tests in a module's __test__ dictionary.
922 if inspect
.ismodule(obj
) and self
._recurse
:
923 for valname
, val
in getattr(obj
, '__test__', {}).items():
924 if not isinstance(valname
, basestring
):
925 raise ValueError("DocTestFinder.find: __test__ keys "
926 "must be strings: %r" %
928 if not (inspect
.isfunction(val
) or inspect
.isclass(val
) or
929 inspect
.ismethod(val
) or inspect
.ismodule(val
) or
930 isinstance(val
, basestring
)):
931 raise ValueError("DocTestFinder.find: __test__ values "
932 "must be strings, functions, methods, "
933 "classes, or modules: %r" %
935 valname
= '%s.__test__.%s' % (name
, valname
)
936 self
._find
(tests
, val
, valname
, module
, source_lines
,
939 # Look for tests in a class's contained objects.
940 if inspect
.isclass(obj
) and self
._recurse
:
941 for valname
, val
in obj
.__dict
__.items():
942 # Special handling for staticmethod/classmethod.
943 if isinstance(val
, staticmethod):
944 val
= getattr(obj
, valname
)
945 if isinstance(val
, classmethod):
946 val
= getattr(obj
, valname
).im_func
948 # Recurse to methods, properties, and nested classes.
949 if ((inspect
.isfunction(val
) or inspect
.isclass(val
) or
950 isinstance(val
, property)) and
951 self
._from
_module
(module
, val
)):
952 valname
= '%s.%s' % (name
, valname
)
953 self
._find
(tests
, val
, valname
, module
, source_lines
,
956 def _get_test(self
, obj
, name
, module
, globs
, source_lines
):
958 Return a DocTest for the given object, if it defines a docstring;
959 otherwise, return None.
961 # Extract the object's docstring. If it doesn't have one,
962 # then return None (no test for this object).
963 if isinstance(obj
, basestring
):
967 if obj
.__doc
__ is None:
970 docstring
= obj
.__doc
__
971 if not isinstance(docstring
, basestring
):
972 docstring
= str(docstring
)
973 except (TypeError, AttributeError):
976 # Find the docstring's location in the file.
977 lineno
= self
._find
_lineno
(obj
, source_lines
)
979 # Don't bother if the docstring is empty.
980 if self
._exclude
_empty
and not docstring
:
983 # Return a DocTest for this object.
987 filename
= getattr(module
, '__file__', module
.__name
__)
988 if filename
[-4:] in (".pyc", ".pyo"):
989 filename
= filename
[:-1]
990 return self
._parser
.get_doctest(docstring
, globs
, name
,
993 def _find_lineno(self
, obj
, source_lines
):
995 Return a line number of the given object's docstring. Note:
996 this method assumes that the object has a docstring.
1000 # Find the line number for modules.
1001 if inspect
.ismodule(obj
):
1004 # Find the line number for classes.
1005 # Note: this could be fooled if a class is defined multiple
1006 # times in a single file.
1007 if inspect
.isclass(obj
):
1008 if source_lines
is None:
1010 pat
= re
.compile(r
'^\s*class\s*%s\b' %
1011 getattr(obj
, '__name__', '-'))
1012 for i
, line
in enumerate(source_lines
):
1017 # Find the line number for functions & methods.
1018 if inspect
.ismethod(obj
): obj
= obj
.im_func
1019 if inspect
.isfunction(obj
): obj
= obj
.func_code
1020 if inspect
.istraceback(obj
): obj
= obj
.tb_frame
1021 if inspect
.isframe(obj
): obj
= obj
.f_code
1022 if inspect
.iscode(obj
):
1023 lineno
= getattr(obj
, 'co_firstlineno', None)-1
1025 # Find the line number where the docstring starts. Assume
1026 # that it's the first line that begins with a quote mark.
1027 # Note: this could be fooled by a multiline function
1028 # signature, where a continuation line begins with a quote
1030 if lineno
is not None:
1031 if source_lines
is None:
1033 pat
= re
.compile('(^|.*:)\s*\w*("|\')')
1034 for lineno
in range(lineno
, len(source_lines
)):
1035 if pat
.match(source_lines
[lineno
]):
1038 # We couldn't find the line number.
1041 ######################################################################
1042 ## 5. DocTest Runner
1043 ######################################################################
1045 class DocTestRunner
:
1047 A class used to run DocTest test cases, and accumulate statistics.
1048 The `run` method is used to process a single DocTest case. It
1049 returns a tuple `(f, t)`, where `t` is the number of test cases
1050 tried, and `f` is the number of test cases that failed.
1052 >>> tests = DocTestFinder().find(_TestClass)
1053 >>> runner = DocTestRunner(verbose=False)
1054 >>> tests.sort(key = lambda test: test.name)
1055 >>> for test in tests:
1056 ... print test.name, '->', runner.run(test)
1057 _TestClass -> TestResults(failed=0, attempted=2)
1058 _TestClass.__init__ -> TestResults(failed=0, attempted=2)
1059 _TestClass.get -> TestResults(failed=0, attempted=2)
1060 _TestClass.square -> TestResults(failed=0, attempted=1)
1062 The `summarize` method prints a summary of all the test cases that
1063 have been run by the runner, and returns an aggregated `(f, t)`
1066 >>> runner.summarize(verbose=1)
1067 4 items passed all tests:
1068 2 tests in _TestClass
1069 2 tests in _TestClass.__init__
1070 2 tests in _TestClass.get
1071 1 tests in _TestClass.square
1073 7 passed and 0 failed.
1075 TestResults(failed=0, attempted=7)
1077 The aggregated number of tried examples and failed examples is
1078 also available via the `tries` and `failures` attributes:
1085 The comparison between expected outputs and actual outputs is done
1086 by an `OutputChecker`. This comparison may be customized with a
1087 number of option flags; see the documentation for `testmod` for
1088 more information. If the option flags are insufficient, then the
1089 comparison may also be customized by passing a subclass of
1090 `OutputChecker` to the constructor.
1092 The test runner's display output can be controlled in two ways.
1093 First, an output function (`out) can be passed to
1094 `TestRunner.run`; this function will be called with strings that
1095 should be displayed. It defaults to `sys.stdout.write`. If
1096 capturing the output is not sufficient, then the display output
1097 can be also customized by subclassing DocTestRunner, and
1098 overriding the methods `report_start`, `report_success`,
1099 `report_unexpected_exception`, and `report_failure`.
1101 # This divider string is used to separate failure messages, and to
1102 # separate sections of the summary.
1105 def __init__(self
, checker
=None, verbose
=None, optionflags
=0):
1107 Create a new test runner.
1109 Optional keyword arg `checker` is the `OutputChecker` that
1110 should be used to compare the expected outputs and actual
1111 outputs of doctest examples.
1113 Optional keyword arg 'verbose' prints lots of stuff if true,
1114 only failures if false; by default, it's true iff '-v' is in
1117 Optional argument `optionflags` can be used to control how the
1118 test runner compares expected output to actual output, and how
1119 it displays failures. See the documentation for `testmod` for
1122 self
._checker
= checker
or OutputChecker()
1124 verbose
= '-v' in sys
.argv
1125 self
._verbose
= verbose
1126 self
.optionflags
= optionflags
1127 self
.original_optionflags
= optionflags
1129 # Keep track of the examples we've run.
1134 # Create a fake output target for capturing doctest output.
1135 self
._fakeout
= _SpoofOut()
1137 #/////////////////////////////////////////////////////////////////
1139 #/////////////////////////////////////////////////////////////////
1141 def report_start(self
, out
, test
, example
):
1143 Report that the test runner is about to process the given
1144 example. (Only displays a message if verbose=True)
1148 out('Trying:\n' + _indent(example
.source
) +
1149 'Expecting:\n' + _indent(example
.want
))
1151 out('Trying:\n' + _indent(example
.source
) +
1152 'Expecting nothing\n')
1154 def report_success(self
, out
, test
, example
, got
):
1156 Report that the given example ran successfully. (Only
1157 displays a message if verbose=True)
1162 def report_failure(self
, out
, test
, example
, got
):
1164 Report that the given example failed.
1166 out(self
._failure
_header
(test
, example
) +
1167 self
._checker
.output_difference(example
, got
, self
.optionflags
))
1169 def report_unexpected_exception(self
, out
, test
, example
, exc_info
):
1171 Report that the given example raised an unexpected exception.
1173 out(self
._failure
_header
(test
, example
) +
1174 'Exception raised:\n' + _indent(_exception_traceback(exc_info
)))
1176 def _failure_header(self
, test
, example
):
1177 out
= [self
.DIVIDER
]
1179 if test
.lineno
is not None and example
.lineno
is not None:
1180 lineno
= test
.lineno
+ example
.lineno
+ 1
1183 out
.append('File "%s", line %s, in %s' %
1184 (test
.filename
, lineno
, test
.name
))
1186 out
.append('Line %s, in %s' % (example
.lineno
+1, test
.name
))
1187 out
.append('Failed example:')
1188 source
= example
.source
1189 out
.append(_indent(source
))
1190 return '\n'.join(out
)
1192 #/////////////////////////////////////////////////////////////////
1194 #/////////////////////////////////////////////////////////////////
1196 def __run(self
, test
, compileflags
, out
):
1198 Run the examples in `test`. Write the outcome of each example
1199 with one of the `DocTestRunner.report_*` methods, using the
1200 writer function `out`. `compileflags` is the set of compiler
1201 flags that should be used to execute examples. Return a tuple
1202 `(f, t)`, where `t` is the number of examples tried, and `f`
1203 is the number of examples that failed. The examples are run
1204 in the namespace `test.globs`.
1206 # Keep track of the number of failures and tries.
1207 failures
= tries
= 0
1209 # Save the option flags (since option directives can be used
1211 original_optionflags
= self
.optionflags
1213 SUCCESS
, FAILURE
, BOOM
= range(3) # `outcome` state
1215 check
= self
._checker
.check_output
1217 # Process each example.
1218 for examplenum
, example
in enumerate(test
.examples
):
1220 # If REPORT_ONLY_FIRST_FAILURE is set, then suppress
1221 # reporting after the first failure.
1222 quiet
= (self
.optionflags
& REPORT_ONLY_FIRST_FAILURE
and
1225 # Merge in the example's options.
1226 self
.optionflags
= original_optionflags
1228 for (optionflag
, val
) in example
.options
.items():
1230 self
.optionflags |
= optionflag
1232 self
.optionflags
&= ~optionflag
1234 # If 'SKIP' is set, then skip this example.
1235 if self
.optionflags
& SKIP
:
1238 # Record that we started this example.
1241 self
.report_start(out
, test
, example
)
1243 # Use a special filename for compile(), so we can retrieve
1244 # the source code during interactive debugging (see
1245 # __patched_linecache_getlines).
1246 filename
= '<doctest %s[%d]>' % (test
.name
, examplenum
)
1248 # Run the example in the given context (globs), and record
1249 # any exception that gets raised. (But don't intercept
1250 # keyboard interrupts.)
1252 # Don't blink! This is where the user's code gets run.
1253 exec compile(example
.source
, filename
, "single",
1254 compileflags
, 1) in test
.globs
1255 self
.debugger
.set_continue() # ==== Example Finished ====
1257 except KeyboardInterrupt:
1260 exception
= sys
.exc_info()
1261 self
.debugger
.set_continue() # ==== Example Finished ====
1263 got
= self
._fakeout
.getvalue() # the actual output
1264 self
._fakeout
.truncate(0)
1265 outcome
= FAILURE
# guilty until proved innocent or insane
1267 # If the example executed without raising any exceptions,
1268 # verify its output.
1269 if exception
is None:
1270 if check(example
.want
, got
, self
.optionflags
):
1273 # The example raised an exception: check if it was expected.
1275 exc_info
= sys
.exc_info()
1276 exc_msg
= traceback
.format_exception_only(*exc_info
[:2])[-1]
1278 got
+= _exception_traceback(exc_info
)
1280 # If `example.exc_msg` is None, then we weren't expecting
1282 if example
.exc_msg
is None:
1285 # We expected an exception: see whether it matches.
1286 elif check(example
.exc_msg
, exc_msg
, self
.optionflags
):
1289 # Another chance if they didn't care about the detail.
1290 elif self
.optionflags
& IGNORE_EXCEPTION_DETAIL
:
1291 m1
= re
.match(r
'(?:[^:]*\.)?([^:]*:)', example
.exc_msg
)
1292 m2
= re
.match(r
'(?:[^:]*\.)?([^:]*:)', exc_msg
)
1293 if m1
and m2
and check(m1
.group(1), m2
.group(1),
1297 # Report the outcome.
1298 if outcome
is SUCCESS
:
1300 self
.report_success(out
, test
, example
, got
)
1301 elif outcome
is FAILURE
:
1303 self
.report_failure(out
, test
, example
, got
)
1305 elif outcome
is BOOM
:
1307 self
.report_unexpected_exception(out
, test
, example
,
1311 assert False, ("unknown outcome", outcome
)
1313 # Restore the option flags (in case they were modified)
1314 self
.optionflags
= original_optionflags
1316 # Record and return the number of failures and tries.
1317 self
.__record
_outcome
(test
, failures
, tries
)
1318 return TestResults(failures
, tries
)
1320 def __record_outcome(self
, test
, f
, t
):
1322 Record the fact that the given DocTest (`test`) generated `f`
1323 failures out of `t` tried examples.
1325 f2
, t2
= self
._name
2ft
.get(test
.name
, (0,0))
1326 self
._name
2ft
[test
.name
] = (f
+f2
, t
+t2
)
1330 __LINECACHE_FILENAME_RE
= re
.compile(r
'<doctest '
1332 r
'\[(?P<examplenum>\d+)\]>$')
1333 def __patched_linecache_getlines(self
, filename
, module_globals
=None):
1334 m
= self
.__LINECACHE
_FILENAME
_RE
.match(filename
)
1335 if m
and m
.group('name') == self
.test
.name
:
1336 example
= self
.test
.examples
[int(m
.group('examplenum'))]
1337 source
= example
.source
1338 if isinstance(source
, unicode):
1339 source
= source
.encode('ascii', 'backslashreplace')
1340 return source
.splitlines(True)
1342 return self
.save_linecache_getlines(filename
, module_globals
)
1344 def run(self
, test
, compileflags
=None, out
=None, clear_globs
=True):
1346 Run the examples in `test`, and display the results using the
1347 writer function `out`.
1349 The examples are run in the namespace `test.globs`. If
1350 `clear_globs` is true (the default), then this namespace will
1351 be cleared after the test runs, to help with garbage
1352 collection. If you would like to examine the namespace after
1353 the test completes, then use `clear_globs=False`.
1355 `compileflags` gives the set of flags that should be used by
1356 the Python compiler when running the examples. If not
1357 specified, then it will default to the set of future-import
1358 flags that apply to `globs`.
1360 The output of each example is checked using
1361 `DocTestRunner.check_output`, and the results are formatted by
1362 the `DocTestRunner.report_*` methods.
1366 if compileflags
is None:
1367 compileflags
= _extract_future_flags(test
.globs
)
1369 save_stdout
= sys
.stdout
1371 out
= save_stdout
.write
1372 sys
.stdout
= self
._fakeout
1374 # Patch pdb.set_trace to restore sys.stdout during interactive
1375 # debugging (so it's not still redirected to self._fakeout).
1376 # Note that the interactive output will go to *our*
1377 # save_stdout, even if that's not the real sys.stdout; this
1378 # allows us to write test cases for the set_trace behavior.
1379 save_set_trace
= pdb
.set_trace
1380 self
.debugger
= _OutputRedirectingPdb(save_stdout
)
1381 self
.debugger
.reset()
1382 pdb
.set_trace
= self
.debugger
.set_trace
1384 # Patch linecache.getlines, so we can see the example's source
1385 # when we're inside the debugger.
1386 self
.save_linecache_getlines
= linecache
.getlines
1387 linecache
.getlines
= self
.__patched
_linecache
_getlines
1389 # Make sure sys.displayhook just prints the value to stdout
1390 save_displayhook
= sys
.displayhook
1391 sys
.displayhook
= sys
.__displayhook
__
1394 return self
.__run
(test
, compileflags
, out
)
1396 sys
.stdout
= save_stdout
1397 pdb
.set_trace
= save_set_trace
1398 linecache
.getlines
= self
.save_linecache_getlines
1399 sys
.displayhook
= save_displayhook
1403 #/////////////////////////////////////////////////////////////////
1405 #/////////////////////////////////////////////////////////////////
1406 def summarize(self
, verbose
=None):
1408 Print a summary of all the test cases that have been run by
1409 this DocTestRunner, and return a tuple `(f, t)`, where `f` is
1410 the total number of failed examples, and `t` is the total
1411 number of tried examples.
1413 The optional `verbose` argument controls how detailed the
1414 summary is. If the verbosity is not specified, then the
1415 DocTestRunner's verbosity is used.
1418 verbose
= self
._verbose
1423 for x
in self
._name
2ft
.items():
1429 notests
.append(name
)
1431 passed
.append( (name
, t
) )
1436 print len(notests
), "items had no tests:"
1438 for thing
in notests
:
1441 print len(passed
), "items passed all tests:"
1443 for thing
, count
in passed
:
1444 print " %3d tests in %s" % (count
, thing
)
1447 print len(failed
), "items had failures:"
1449 for thing
, (f
, t
) in failed
:
1450 print " %3d of %3d in %s" % (f
, t
, thing
)
1452 print totalt
, "tests in", len(self
._name
2ft
), "items."
1453 print totalt
- totalf
, "passed and", totalf
, "failed."
1455 print "***Test Failed***", totalf
, "failures."
1457 print "Test passed."
1458 return TestResults(totalf
, totalt
)
1460 #/////////////////////////////////////////////////////////////////
1461 # Backward compatibility cruft to maintain doctest.master.
1462 #/////////////////////////////////////////////////////////////////
1463 def merge(self
, other
):
1465 for name
, (f
, t
) in other
._name
2ft
.items():
1467 # Don't print here by default, since doing
1468 # so breaks some of the buildbots
1469 #print "*** DocTestRunner.merge: '" + name + "' in both" \
1470 # " testers; summing outcomes."
1476 class OutputChecker
:
1478 A class used to check the whether the actual output from a doctest
1479 example matches the expected output. `OutputChecker` defines two
1480 methods: `check_output`, which compares a given pair of outputs,
1481 and returns true if they match; and `output_difference`, which
1482 returns a string describing the differences between two outputs.
1484 def check_output(self
, want
, got
, optionflags
):
1486 Return True iff the actual output from an example (`got`)
1487 matches the expected output (`want`). These strings are
1488 always considered to match if they are identical; but
1489 depending on what option flags the test runner is using,
1490 several non-exact match types are also possible. See the
1491 documentation for `TestRunner` for more information about
1494 # Handle the common case first, for efficiency:
1495 # if they're string-identical, always return true.
1499 # The values True and False replaced 1 and 0 as the return
1500 # value for boolean comparisons in Python 2.3.
1501 if not (optionflags
& DONT_ACCEPT_TRUE_FOR_1
):
1502 if (got
,want
) == ("True\n", "1\n"):
1504 if (got
,want
) == ("False\n", "0\n"):
1507 # <BLANKLINE> can be used as a special sequence to signify a
1508 # blank line, unless the DONT_ACCEPT_BLANKLINE flag is used.
1509 if not (optionflags
& DONT_ACCEPT_BLANKLINE
):
1510 # Replace <BLANKLINE> in want with a blank line.
1511 want
= re
.sub('(?m)^%s\s*?$' % re
.escape(BLANKLINE_MARKER
),
1513 # If a line in got contains only spaces, then remove the
1515 got
= re
.sub('(?m)^\s*?$', '', got
)
1519 # This flag causes doctest to ignore any differences in the
1520 # contents of whitespace strings. Note that this can be used
1521 # in conjunction with the ELLIPSIS flag.
1522 if optionflags
& NORMALIZE_WHITESPACE
:
1523 got
= ' '.join(got
.split())
1524 want
= ' '.join(want
.split())
1528 # The ELLIPSIS flag says to let the sequence "..." in `want`
1529 # match any substring in `got`.
1530 if optionflags
& ELLIPSIS
:
1531 if _ellipsis_match(want
, got
):
1534 # We didn't find any match; return false.
1537 # Should we do a fancy diff?
1538 def _do_a_fancy_diff(self
, want
, got
, optionflags
):
1539 # Not unless they asked for a fancy diff.
1540 if not optionflags
& (REPORT_UDIFF |
1545 # If expected output uses ellipsis, a meaningful fancy diff is
1546 # too hard ... or maybe not. In two real-life failures Tim saw,
1547 # a diff was a major help anyway, so this is commented out.
1548 # [todo] _ellipsis_match() knows which pieces do and don't match,
1549 # and could be the basis for a kick-ass diff in this case.
1550 ##if optionflags & ELLIPSIS and ELLIPSIS_MARKER in want:
1553 # ndiff does intraline difference marking, so can be useful even
1554 # for 1-line differences.
1555 if optionflags
& REPORT_NDIFF
:
1558 # The other diff types need at least a few lines to be helpful.
1559 return want
.count('\n') > 2 and got
.count('\n') > 2
1561 def output_difference(self
, example
, got
, optionflags
):
1563 Return a string describing the differences between the
1564 expected output for a given example (`example`) and the actual
1565 output (`got`). `optionflags` is the set of option flags used
1566 to compare `want` and `got`.
1569 # If <BLANKLINE>s are being used, then replace blank lines
1570 # with <BLANKLINE> in the actual output string.
1571 if not (optionflags
& DONT_ACCEPT_BLANKLINE
):
1572 got
= re
.sub('(?m)^[ ]*(?=\n)', BLANKLINE_MARKER
, got
)
1574 # Check if we should use diff.
1575 if self
._do
_a
_fancy
_diff
(want
, got
, optionflags
):
1576 # Split want & got into lines.
1577 want_lines
= want
.splitlines(True) # True == keep line ends
1578 got_lines
= got
.splitlines(True)
1579 # Use difflib to find their differences.
1580 if optionflags
& REPORT_UDIFF
:
1581 diff
= difflib
.unified_diff(want_lines
, got_lines
, n
=2)
1582 diff
= list(diff
)[2:] # strip the diff header
1583 kind
= 'unified diff with -expected +actual'
1584 elif optionflags
& REPORT_CDIFF
:
1585 diff
= difflib
.context_diff(want_lines
, got_lines
, n
=2)
1586 diff
= list(diff
)[2:] # strip the diff header
1587 kind
= 'context diff with expected followed by actual'
1588 elif optionflags
& REPORT_NDIFF
:
1589 engine
= difflib
.Differ(charjunk
=difflib
.IS_CHARACTER_JUNK
)
1590 diff
= list(engine
.compare(want_lines
, got_lines
))
1591 kind
= 'ndiff with -expected +actual'
1593 assert 0, 'Bad diff option'
1594 # Remove trailing whitespace on diff output.
1595 diff
= [line
.rstrip() + '\n' for line
in diff
]
1596 return 'Differences (%s):\n' % kind
+ _indent(''.join(diff
))
1598 # If we're not using diff, then simply list the expected
1599 # output followed by the actual output.
1601 return 'Expected:\n%sGot:\n%s' % (_indent(want
), _indent(got
))
1603 return 'Expected:\n%sGot nothing\n' % _indent(want
)
1605 return 'Expected nothing\nGot:\n%s' % _indent(got
)
1607 return 'Expected nothing\nGot nothing\n'
1609 class DocTestFailure(Exception):
1610 """A DocTest example has failed in debugging mode.
1612 The exception instance has variables:
1614 - test: the DocTest object being run
1616 - example: the Example object that failed
1618 - got: the actual output
1620 def __init__(self
, test
, example
, got
):
1622 self
.example
= example
1626 return str(self
.test
)
1628 class UnexpectedException(Exception):
1629 """A DocTest example has encountered an unexpected exception
1631 The exception instance has variables:
1633 - test: the DocTest object being run
1635 - example: the Example object that failed
1637 - exc_info: the exception info
1639 def __init__(self
, test
, example
, exc_info
):
1641 self
.example
= example
1642 self
.exc_info
= exc_info
1645 return str(self
.test
)
1647 class DebugRunner(DocTestRunner
):
1648 r
"""Run doc tests but raise an exception as soon as there is a failure.
1650 If an unexpected exception occurs, an UnexpectedException is raised.
1651 It contains the test, the example, and the original exception:
1653 >>> runner = DebugRunner(verbose=False)
1654 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
1655 ... {}, 'foo', 'foo.py', 0)
1657 ... runner.run(test)
1658 ... except UnexpectedException, failure:
1661 >>> failure.test is test
1664 >>> failure.example.want
1667 >>> exc_info = failure.exc_info
1668 >>> raise exc_info[0], exc_info[1], exc_info[2]
1669 Traceback (most recent call last):
1673 We wrap the original exception to give the calling application
1674 access to the test and example information.
1676 If the output doesn't match, then a DocTestFailure is raised:
1678 >>> test = DocTestParser().get_doctest('''
1682 ... ''', {}, 'foo', 'foo.py', 0)
1685 ... runner.run(test)
1686 ... except DocTestFailure, failure:
1689 DocTestFailure objects provide access to the test:
1691 >>> failure.test is test
1694 As well as to the example:
1696 >>> failure.example.want
1699 and the actual output:
1704 If a failure or error occurs, the globals are left intact:
1706 >>> del test.globs['__builtins__']
1710 >>> test = DocTestParser().get_doctest('''
1712 ... >>> raise KeyError
1713 ... ''', {}, 'foo', 'foo.py', 0)
1715 >>> runner.run(test)
1716 Traceback (most recent call last):
1718 UnexpectedException: <DocTest foo from foo.py:0 (2 examples)>
1720 >>> del test.globs['__builtins__']
1724 But the globals are cleared if there is no error:
1726 >>> test = DocTestParser().get_doctest('''
1728 ... ''', {}, 'foo', 'foo.py', 0)
1730 >>> runner.run(test)
1731 TestResults(failed=0, attempted=1)
1738 def run(self
, test
, compileflags
=None, out
=None, clear_globs
=True):
1739 r
= DocTestRunner
.run(self
, test
, compileflags
, out
, False)
1744 def report_unexpected_exception(self
, out
, test
, example
, exc_info
):
1745 raise UnexpectedException(test
, example
, exc_info
)
1747 def report_failure(self
, out
, test
, example
, got
):
1748 raise DocTestFailure(test
, example
, got
)
1750 ######################################################################
1751 ## 6. Test Functions
1752 ######################################################################
1753 # These should be backwards compatible.
1755 # For backward compatibility, a global instance of a DocTestRunner
1756 # class, updated by testmod.
1759 def testmod(m
=None, name
=None, globs
=None, verbose
=None,
1760 report
=True, optionflags
=0, extraglobs
=None,
1761 raise_on_error
=False, exclude_empty
=False):
1762 """m=None, name=None, globs=None, verbose=None, report=True,
1763 optionflags=0, extraglobs=None, raise_on_error=False,
1766 Test examples in docstrings in functions and classes reachable
1767 from module m (or the current module if m is not supplied), starting
1770 Also test examples reachable from dict m.__test__ if it exists and is
1771 not None. m.__test__ maps names to functions, classes and strings;
1772 function and class docstrings are tested even if the name is private;
1773 strings are tested directly, as if they were docstrings.
1775 Return (#failures, #tests).
1777 See help(doctest) for an overview.
1779 Optional keyword arg "name" gives the name of the module; by default
1782 Optional keyword arg "globs" gives a dict to be used as the globals
1783 when executing examples; by default, use m.__dict__. A copy of this
1784 dict is actually used for each docstring, so that each docstring's
1785 examples start with a clean slate.
1787 Optional keyword arg "extraglobs" gives a dictionary that should be
1788 merged into the globals that are used to execute examples. By
1789 default, no extra globals are used. This is new in 2.4.
1791 Optional keyword arg "verbose" prints lots of stuff if true, prints
1792 only failures if false; by default, it's true iff "-v" is in sys.argv.
1794 Optional keyword arg "report" prints a summary at the end when true,
1795 else prints nothing at the end. In verbose mode, the summary is
1796 detailed, else very brief (in fact, empty if all tests passed).
1798 Optional keyword arg "optionflags" or's together module constants,
1799 and defaults to 0. This is new in 2.3. Possible values (see the
1802 DONT_ACCEPT_TRUE_FOR_1
1803 DONT_ACCEPT_BLANKLINE
1804 NORMALIZE_WHITESPACE
1807 IGNORE_EXCEPTION_DETAIL
1811 REPORT_ONLY_FIRST_FAILURE
1813 Optional keyword arg "raise_on_error" raises an exception on the
1814 first unexpected exception or failure. This allows failures to be
1815 post-mortem debugged.
1817 Advanced tomfoolery: testmod runs methods of a local instance of
1818 class doctest.Tester, then merges the results into (or creates)
1819 global Tester instance doctest.master. Methods of doctest.master
1820 can be called directly too, if you want to do something unusual.
1821 Passing report=0 to testmod is especially useful then, to delay
1822 displaying a summary. Invoke doctest.master.summarize(verbose)
1823 when you're done fiddling.
1827 # If no module was given, then use __main__.
1829 # DWA - m will still be None if this wasn't invoked from the command
1830 # line, in which case the following TypeError is about as good an error
1831 # as we should expect
1832 m
= sys
.modules
.get('__main__')
1834 # Check that we were actually given a module.
1835 if not inspect
.ismodule(m
):
1836 raise TypeError("testmod: module required; %r" % (m
,))
1838 # If no name was given, then use the module's name.
1842 # Find, parse, and run all tests in the given module.
1843 finder
= DocTestFinder(exclude_empty
=exclude_empty
)
1846 runner
= DebugRunner(verbose
=verbose
, optionflags
=optionflags
)
1848 runner
= DocTestRunner(verbose
=verbose
, optionflags
=optionflags
)
1850 for test
in finder
.find(m
, name
, globs
=globs
, extraglobs
=extraglobs
):
1859 master
.merge(runner
)
1861 return TestResults(runner
.failures
, runner
.tries
)
1863 def testfile(filename
, module_relative
=True, name
=None, package
=None,
1864 globs
=None, verbose
=None, report
=True, optionflags
=0,
1865 extraglobs
=None, raise_on_error
=False, parser
=DocTestParser(),
1868 Test examples in the given file. Return (#failures, #tests).
1870 Optional keyword arg "module_relative" specifies how filenames
1871 should be interpreted:
1873 - If "module_relative" is True (the default), then "filename"
1874 specifies a module-relative path. By default, this path is
1875 relative to the calling module's directory; but if the
1876 "package" argument is specified, then it is relative to that
1877 package. To ensure os-independence, "filename" should use
1878 "/" characters to separate path segments, and should not
1879 be an absolute path (i.e., it may not begin with "/").
1881 - If "module_relative" is False, then "filename" specifies an
1882 os-specific path. The path may be absolute or relative (to
1883 the current working directory).
1885 Optional keyword arg "name" gives the name of the test; by default
1886 use the file's basename.
1888 Optional keyword argument "package" is a Python package or the
1889 name of a Python package whose directory should be used as the
1890 base directory for a module relative filename. If no package is
1891 specified, then the calling module's directory is used as the base
1892 directory for module relative filenames. It is an error to
1893 specify "package" if "module_relative" is False.
1895 Optional keyword arg "globs" gives a dict to be used as the globals
1896 when executing examples; by default, use {}. A copy of this dict
1897 is actually used for each docstring, so that each docstring's
1898 examples start with a clean slate.
1900 Optional keyword arg "extraglobs" gives a dictionary that should be
1901 merged into the globals that are used to execute examples. By
1902 default, no extra globals are used.
1904 Optional keyword arg "verbose" prints lots of stuff if true, prints
1905 only failures if false; by default, it's true iff "-v" is in sys.argv.
1907 Optional keyword arg "report" prints a summary at the end when true,
1908 else prints nothing at the end. In verbose mode, the summary is
1909 detailed, else very brief (in fact, empty if all tests passed).
1911 Optional keyword arg "optionflags" or's together module constants,
1912 and defaults to 0. Possible values (see the docs for details):
1914 DONT_ACCEPT_TRUE_FOR_1
1915 DONT_ACCEPT_BLANKLINE
1916 NORMALIZE_WHITESPACE
1919 IGNORE_EXCEPTION_DETAIL
1923 REPORT_ONLY_FIRST_FAILURE
1925 Optional keyword arg "raise_on_error" raises an exception on the
1926 first unexpected exception or failure. This allows failures to be
1927 post-mortem debugged.
1929 Optional keyword arg "parser" specifies a DocTestParser (or
1930 subclass) that should be used to extract tests from the files.
1932 Optional keyword arg "encoding" specifies an encoding that should
1933 be used to convert the file to unicode.
1935 Advanced tomfoolery: testmod runs methods of a local instance of
1936 class doctest.Tester, then merges the results into (or creates)
1937 global Tester instance doctest.master. Methods of doctest.master
1938 can be called directly too, if you want to do something unusual.
1939 Passing report=0 to testmod is especially useful then, to delay
1940 displaying a summary. Invoke doctest.master.summarize(verbose)
1941 when you're done fiddling.
1945 if package
and not module_relative
:
1946 raise ValueError("Package may only be specified for module-"
1949 # Relativize the path
1950 text
, filename
= _load_testfile(filename
, package
, module_relative
)
1952 # If no name was given, then use the file's name.
1954 name
= os
.path
.basename(filename
)
1956 # Assemble the globals.
1960 globs
= globs
.copy()
1961 if extraglobs
is not None:
1962 globs
.update(extraglobs
)
1963 if '__name__' not in globs
:
1964 globs
['__name__'] = '__main__'
1967 runner
= DebugRunner(verbose
=verbose
, optionflags
=optionflags
)
1969 runner
= DocTestRunner(verbose
=verbose
, optionflags
=optionflags
)
1971 if encoding
is not None:
1972 text
= text
.decode(encoding
)
1974 # Read the file, convert it to a test, and run it.
1975 test
= parser
.get_doctest(text
, globs
, name
, filename
, 0)
1984 master
.merge(runner
)
1986 return TestResults(runner
.failures
, runner
.tries
)
1988 def run_docstring_examples(f
, globs
, verbose
=False, name
="NoName",
1989 compileflags
=None, optionflags
=0):
1991 Test examples in the given object's docstring (`f`), using `globs`
1992 as globals. Optional argument `name` is used in failure messages.
1993 If the optional argument `verbose` is true, then generate output
1994 even if there are no failures.
1996 `compileflags` gives the set of flags that should be used by the
1997 Python compiler when running the examples. If not specified, then
1998 it will default to the set of future-import flags that apply to
2001 Optional keyword arg `optionflags` specifies options for the
2002 testing and output. See the documentation for `testmod` for more
2005 # Find, parse, and run all tests in the given module.
2006 finder
= DocTestFinder(verbose
=verbose
, recurse
=False)
2007 runner
= DocTestRunner(verbose
=verbose
, optionflags
=optionflags
)
2008 for test
in finder
.find(f
, name
, globs
=globs
):
2009 runner
.run(test
, compileflags
=compileflags
)
2011 ######################################################################
2013 ######################################################################
2014 # This is provided only for backwards compatibility. It's not
2015 # actually used in any way.
2018 def __init__(self
, mod
=None, globs
=None, verbose
=None, optionflags
=0):
2020 warnings
.warn("class Tester is deprecated; "
2021 "use class doctest.DocTestRunner instead",
2022 DeprecationWarning, stacklevel
=2)
2023 if mod
is None and globs
is None:
2024 raise TypeError("Tester.__init__: must specify mod or globs")
2025 if mod
is not None and not inspect
.ismodule(mod
):
2026 raise TypeError("Tester.__init__: mod must be a module; %r" %
2029 globs
= mod
.__dict
__
2032 self
.verbose
= verbose
2033 self
.optionflags
= optionflags
2034 self
.testfinder
= DocTestFinder()
2035 self
.testrunner
= DocTestRunner(verbose
=verbose
,
2036 optionflags
=optionflags
)
2038 def runstring(self
, s
, name
):
2039 test
= DocTestParser().get_doctest(s
, self
.globs
, name
, None, None)
2041 print "Running string", name
2042 (f
,t
) = self
.testrunner
.run(test
)
2044 print f
, "of", t
, "examples failed in string", name
2045 return TestResults(f
,t
)
2047 def rundoc(self
, object, name
=None, module
=None):
2049 tests
= self
.testfinder
.find(object, name
, module
=module
,
2052 (f2
, t2
) = self
.testrunner
.run(test
)
2053 (f
,t
) = (f
+f2
, t
+t2
)
2054 return TestResults(f
,t
)
2056 def rundict(self
, d
, name
, module
=None):
2058 m
= types
.ModuleType(name
)
2059 m
.__dict
__.update(d
)
2062 return self
.rundoc(m
, name
, module
)
2064 def run__test__(self
, d
, name
):
2066 m
= types
.ModuleType(name
)
2068 return self
.rundoc(m
, name
)
2070 def summarize(self
, verbose
=None):
2071 return self
.testrunner
.summarize(verbose
)
2073 def merge(self
, other
):
2074 self
.testrunner
.merge(other
.testrunner
)
2076 ######################################################################
2077 ## 8. Unittest Support
2078 ######################################################################
2080 _unittest_reportflags
= 0
2082 def set_unittest_reportflags(flags
):
2083 """Sets the unittest option flags.
2085 The old flag is returned so that a runner could restore the old
2086 value if it wished to:
2089 >>> old = doctest._unittest_reportflags
2090 >>> doctest.set_unittest_reportflags(REPORT_NDIFF |
2091 ... REPORT_ONLY_FIRST_FAILURE) == old
2094 >>> doctest._unittest_reportflags == (REPORT_NDIFF |
2095 ... REPORT_ONLY_FIRST_FAILURE)
2098 Only reporting flags can be set:
2100 >>> doctest.set_unittest_reportflags(ELLIPSIS)
2101 Traceback (most recent call last):
2103 ValueError: ('Only reporting flags allowed', 8)
2105 >>> doctest.set_unittest_reportflags(old) == (REPORT_NDIFF |
2106 ... REPORT_ONLY_FIRST_FAILURE)
2109 global _unittest_reportflags
2111 if (flags
& REPORTING_FLAGS
) != flags
:
2112 raise ValueError("Only reporting flags allowed", flags
)
2113 old
= _unittest_reportflags
2114 _unittest_reportflags
= flags
2118 class DocTestCase(unittest
.TestCase
):
2120 def __init__(self
, test
, optionflags
=0, setUp
=None, tearDown
=None,
2123 unittest
.TestCase
.__init
__(self
)
2124 self
._dt
_optionflags
= optionflags
2125 self
._dt
_checker
= checker
2126 self
._dt
_test
= test
2127 self
._dt
_setUp
= setUp
2128 self
._dt
_tearDown
= tearDown
2131 test
= self
._dt
_test
2133 if self
._dt
_setUp
is not None:
2134 self
._dt
_setUp
(test
)
2137 test
= self
._dt
_test
2139 if self
._dt
_tearDown
is not None:
2140 self
._dt
_tearDown
(test
)
2145 test
= self
._dt
_test
2148 optionflags
= self
._dt
_optionflags
2150 if not (optionflags
& REPORTING_FLAGS
):
2151 # The option flags don't include any reporting flags,
2152 # so add the default reporting flags
2153 optionflags |
= _unittest_reportflags
2155 runner
= DocTestRunner(optionflags
=optionflags
,
2156 checker
=self
._dt
_checker
, verbose
=False)
2159 runner
.DIVIDER
= "-"*70
2160 failures
, tries
= runner
.run(
2161 test
, out
=new
.write
, clear_globs
=False)
2166 raise self
.failureException(self
.format_failure(new
.getvalue()))
2168 def format_failure(self
, err
):
2169 test
= self
._dt
_test
2170 if test
.lineno
is None:
2171 lineno
= 'unknown line number'
2173 lineno
= '%s' % test
.lineno
2174 lname
= '.'.join(test
.name
.split('.')[-1:])
2175 return ('Failed doctest test for %s\n'
2176 ' File "%s", line %s, in %s\n\n%s'
2177 % (test
.name
, test
.filename
, lineno
, lname
, err
)
2181 r
"""Run the test case without results and without catching exceptions
2183 The unit test framework includes a debug method on test cases
2184 and test suites to support post-mortem debugging. The test code
2185 is run in such a way that errors are not caught. This way a
2186 caller can catch the errors and initiate post-mortem debugging.
2188 The DocTestCase provides a debug method that raises
2189 UnexpectedException errors if there is an unexpected
2192 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
2193 ... {}, 'foo', 'foo.py', 0)
2194 >>> case = DocTestCase(test)
2197 ... except UnexpectedException, failure:
2200 The UnexpectedException contains the test, the example, and
2201 the original exception:
2203 >>> failure.test is test
2206 >>> failure.example.want
2209 >>> exc_info = failure.exc_info
2210 >>> raise exc_info[0], exc_info[1], exc_info[2]
2211 Traceback (most recent call last):
2215 If the output doesn't match, then a DocTestFailure is raised:
2217 >>> test = DocTestParser().get_doctest('''
2221 ... ''', {}, 'foo', 'foo.py', 0)
2222 >>> case = DocTestCase(test)
2226 ... except DocTestFailure, failure:
2229 DocTestFailure objects provide access to the test:
2231 >>> failure.test is test
2234 As well as to the example:
2236 >>> failure.example.want
2239 and the actual output:
2247 runner
= DebugRunner(optionflags
=self
._dt
_optionflags
,
2248 checker
=self
._dt
_checker
, verbose
=False)
2249 runner
.run(self
._dt
_test
, clear_globs
=False)
2253 return self
._dt
_test
.name
2256 name
= self
._dt
_test
.name
.split('.')
2257 return "%s (%s)" % (name
[-1], '.'.join(name
[:-1]))
2261 def shortDescription(self
):
2262 return "Doctest: " + self
._dt
_test
.name
2264 class SkipDocTestCase(DocTestCase
):
2266 DocTestCase
.__init
__(self
, None)
2269 self
.skipTest("DocTestSuite will not work with -O2 and above")
2271 def test_skip(self
):
2274 def shortDescription(self
):
2275 return "Skipping tests from %s" % module
.__name
__
2277 def DocTestSuite(module
=None, globs
=None, extraglobs
=None, test_finder
=None,
2280 Convert doctest tests for a module to a unittest test suite.
2282 This converts each documentation string in a module that
2283 contains doctest tests to a unittest test case. If any of the
2284 tests in a doc string fail, then the test case fails. An exception
2285 is raised showing the name of the file containing the test and a
2286 (sometimes approximate) line number.
2288 The `module` argument provides the module to be tested. The argument
2289 can be either a module or a module name.
2291 If no argument is given, the calling module is used.
2293 A number of options may be provided as keyword arguments:
2296 A set-up function. This is called before running the
2297 tests in each file. The setUp function will be passed a DocTest
2298 object. The setUp function can access the test globals as the
2299 globs attribute of the test passed.
2302 A tear-down function. This is called after running the
2303 tests in each file. The tearDown function will be passed a DocTest
2304 object. The tearDown function can access the test globals as the
2305 globs attribute of the test passed.
2308 A dictionary containing initial global variables for the tests.
2311 A set of doctest option flags expressed as an integer.
2314 if test_finder
is None:
2315 test_finder
= DocTestFinder()
2317 module
= _normalize_module(module
)
2318 tests
= test_finder
.find(module
, globs
=globs
, extraglobs
=extraglobs
)
2320 if not tests
and sys
.flags
.optimize
>=2:
2321 # Skip doctests when running with -O2
2322 suite
= unittest
.TestSuite()
2323 suite
.addTest(SkipDocTestCase())
2326 # Why do we want to do this? Because it reveals a bug that might
2327 # otherwise be hidden.
2328 raise ValueError(module
, "has no tests")
2331 suite
= unittest
.TestSuite()
2334 if len(test
.examples
) == 0:
2336 if not test
.filename
:
2337 filename
= module
.__file
__
2338 if filename
[-4:] in (".pyc", ".pyo"):
2339 filename
= filename
[:-1]
2340 test
.filename
= filename
2341 suite
.addTest(DocTestCase(test
, **options
))
2345 class DocFileCase(DocTestCase
):
2348 return '_'.join(self
._dt
_test
.name
.split('.'))
2351 return self
._dt
_test
.filename
2354 def format_failure(self
, err
):
2355 return ('Failed doctest test for %s\n File "%s", line 0\n\n%s'
2356 % (self
._dt
_test
.name
, self
._dt
_test
.filename
, err
)
2359 def DocFileTest(path
, module_relative
=True, package
=None,
2360 globs
=None, parser
=DocTestParser(),
2361 encoding
=None, **options
):
2365 globs
= globs
.copy()
2367 if package
and not module_relative
:
2368 raise ValueError("Package may only be specified for module-"
2371 # Relativize the path.
2372 doc
, path
= _load_testfile(path
, package
, module_relative
)
2374 if "__file__" not in globs
:
2375 globs
["__file__"] = path
2377 # Find the file and read it.
2378 name
= os
.path
.basename(path
)
2380 # If an encoding is specified, use it to convert the file to unicode
2381 if encoding
is not None:
2382 doc
= doc
.decode(encoding
)
2384 # Convert it to a test, and wrap it in a DocFileCase.
2385 test
= parser
.get_doctest(doc
, globs
, name
, path
, 0)
2386 return DocFileCase(test
, **options
)
2388 def DocFileSuite(*paths
, **kw
):
2389 """A unittest suite for one or more doctest files.
2391 The path to each doctest file is given as a string; the
2392 interpretation of that string depends on the keyword argument
2395 A number of options may be provided as keyword arguments:
2398 If "module_relative" is True, then the given file paths are
2399 interpreted as os-independent module-relative paths. By
2400 default, these paths are relative to the calling module's
2401 directory; but if the "package" argument is specified, then
2402 they are relative to that package. To ensure os-independence,
2403 "filename" should use "/" characters to separate path
2404 segments, and may not be an absolute path (i.e., it may not
2407 If "module_relative" is False, then the given file paths are
2408 interpreted as os-specific paths. These paths may be absolute
2409 or relative (to the current working directory).
2412 A Python package or the name of a Python package whose directory
2413 should be used as the base directory for module relative paths.
2414 If "package" is not specified, then the calling module's
2415 directory is used as the base directory for module relative
2416 filenames. It is an error to specify "package" if
2417 "module_relative" is False.
2420 A set-up function. This is called before running the
2421 tests in each file. The setUp function will be passed a DocTest
2422 object. The setUp function can access the test globals as the
2423 globs attribute of the test passed.
2426 A tear-down function. This is called after running the
2427 tests in each file. The tearDown function will be passed a DocTest
2428 object. The tearDown function can access the test globals as the
2429 globs attribute of the test passed.
2432 A dictionary containing initial global variables for the tests.
2435 A set of doctest option flags expressed as an integer.
2438 A DocTestParser (or subclass) that should be used to extract
2439 tests from the files.
2442 An encoding that will be used to convert the files to unicode.
2444 suite
= unittest
.TestSuite()
2446 # We do this here so that _normalize_module is called at the right
2447 # level. If it were called in DocFileTest, then this function
2448 # would be the caller and we might guess the package incorrectly.
2449 if kw
.get('module_relative', True):
2450 kw
['package'] = _normalize_module(kw
.get('package'))
2453 suite
.addTest(DocFileTest(path
, **kw
))
2457 ######################################################################
2458 ## 9. Debugging Support
2459 ######################################################################
2461 def script_from_examples(s
):
2462 r
"""Extract script from text with examples.
2464 Converts text with examples to a Python script. Example input is
2465 converted to regular code. Example output and all other words
2466 are converted to comments:
2469 ... Here are examples of simple math.
2471 ... Python has super accurate integer addition
2476 ... And very friendly error messages:
2483 ... You can use logic if you want:
2493 >>> print script_from_examples(text)
2494 # Here are examples of simple math.
2496 # Python has super accurate integer addition
2502 # And very friendly error messages:
2510 # You can use logic if you want:
2520 for piece
in DocTestParser().parse(s
):
2521 if isinstance(piece
, Example
):
2522 # Add the example's source code (strip trailing NL)
2523 output
.append(piece
.source
[:-1])
2524 # Add the expected output:
2527 output
.append('# Expected:')
2528 output
+= ['## '+l
for l
in want
.split('\n')[:-1]]
2530 # Add non-example text.
2531 output
+= [_comment_line(l
)
2532 for l
in piece
.split('\n')[:-1]]
2534 # Trim junk on both ends.
2535 while output
and output
[-1] == '#':
2537 while output
and output
[0] == '#':
2539 # Combine the output, and return it.
2540 # Add a courtesy newline to prevent exec from choking (see bug #1172785)
2541 return '\n'.join(output
) + '\n'
2543 def testsource(module
, name
):
2544 """Extract the test sources from a doctest docstring as a script.
2546 Provide the module (or dotted name of the module) containing the
2547 test to be debugged and the name (within the module) of the object
2548 with the doc string with tests to be debugged.
2550 module
= _normalize_module(module
)
2551 tests
= DocTestFinder().find(module
)
2552 test
= [t
for t
in tests
if t
.name
== name
]
2554 raise ValueError(name
, "not found in tests")
2556 testsrc
= script_from_examples(test
.docstring
)
2559 def debug_src(src
, pm
=False, globs
=None):
2560 """Debug a single doctest docstring, in argument `src`'"""
2561 testsrc
= script_from_examples(src
)
2562 debug_script(testsrc
, pm
, globs
)
2564 def debug_script(src
, pm
=False, globs
=None):
2565 "Debug a test script. `src` is the script, as a string."
2568 # Note that tempfile.NameTemporaryFile() cannot be used. As the
2569 # docs say, a file so created cannot be opened by name a second time
2570 # on modern Windows boxes, and execfile() needs to open it.
2571 srcfilename
= tempfile
.mktemp(".py", "doctestdebug")
2572 f
= open(srcfilename
, 'w')
2578 globs
= globs
.copy()
2584 execfile(srcfilename
, globs
, globs
)
2586 print sys
.exc_info()[1]
2587 pdb
.post_mortem(sys
.exc_info()[2])
2589 # Note that %r is vital here. '%s' instead can, e.g., cause
2590 # backslashes to get treated as metacharacters on Windows.
2591 pdb
.run("execfile(%r)" % srcfilename
, globs
, globs
)
2594 os
.remove(srcfilename
)
2596 def debug(module
, name
, pm
=False):
2597 """Debug a single doctest docstring.
2599 Provide the module (or dotted name of the module) containing the
2600 test to be debugged and the name (within the module) of the object
2601 with the docstring with tests to be debugged.
2603 module
= _normalize_module(module
)
2604 testsrc
= testsource(module
, name
)
2605 debug_script(testsrc
, pm
, module
.__dict
__)
2607 ######################################################################
2608 ## 10. Example Usage
2609 ######################################################################
2612 A pointless class, for sanity-checking of docstring testing.
2618 >>> _TestClass(13).get() + _TestClass(-12).get()
2620 >>> hex(_TestClass(13).square().get())
2624 def __init__(self
, val
):
2625 """val -> _TestClass object with associated value val.
2627 >>> t = _TestClass(123)
2635 """square() -> square TestClass's associated value
2637 >>> _TestClass(13).square().get()
2641 self
.val
= self
.val
** 2
2645 """get() -> return TestClass's associated value.
2647 >>> x = _TestClass(-42)
2654 __test__
= {"_TestClass": _TestClass
,
2656 Example of a string object, searched as-is.
2662 "bool-int equivalence": r
"""
2663 In 2.2, boolean expressions displayed
2664 0 or 1. By default, we still accept
2665 them. This can be disabled by passing
2666 DONT_ACCEPT_TRUE_FOR_1 to the new
2667 optionflags argument.
2679 Blank lines can be marked with <BLANKLINE>:
2680 >>> print 'foo\n\nbar\n'
2688 If the ellipsis flag is used, then '...' can be used to
2689 elide substrings in the desired output:
2690 >>> print range(1000) #doctest: +ELLIPSIS
2694 "whitespace normalization": r
"""
2695 If the whitespace normalization flag is used, then
2696 differences in whitespace are ignored.
2697 >>> print range(30) #doctest: +NORMALIZE_WHITESPACE
2698 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
2699 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,
2706 testfiles
= [arg
for arg
in sys
.argv
[1:] if arg
and arg
[0] != '-']
2708 name
= os
.path
.basename(sys
.argv
[0])
2709 if '__loader__' in globals(): # python -m
2710 name
, _
= os
.path
.splitext(name
)
2711 print("usage: {0} [-v] file ...".format(name
))
2713 for filename
in testfiles
:
2714 if filename
.endswith(".py"):
2715 # It is a module -- insert its dir into sys.path and try to
2716 # import it. If it is part of a package, that possibly
2717 # won't work because of package imports.
2718 dirname
, filename
= os
.path
.split(filename
)
2719 sys
.path
.insert(0, dirname
)
2720 m
= __import__(filename
[:-3])
2722 failures
, _
= testmod(m
)
2724 failures
, _
= testfile(filename
, module_relative
=False)
2730 if __name__
== "__main__":