root/galaxy-central/eggs/Paste-1.6-py2.6.egg/paste/util/doctest24.py

リビジョン 3, 97.0 KB (コミッタ: kohda, 14 年 前)

Install Unix tools  http://hannonlab.cshl.edu/galaxy_unix_tools/galaxy.html

行番号 
1# Module doctest.
2# Released to the public domain 16-Jan-2001, by Tim Peters (tim@python.org).
3# Major enhancements and refactoring by:
4#     Jim Fulton
5#     Edward Loper
6
7# Provided as-is; use at your own risk; no warranty; no promises; enjoy!
8
9r"""Module doctest -- a framework for running examples in docstrings.
10
11In simplest use, end each module M to be tested with:
12
13def _test():
14    import doctest
15    doctest.testmod()
16
17if __name__ == "__main__":
18    _test()
19
20Then running the module as a script will cause the examples in the
21docstrings to get executed and verified:
22
23python M.py
24
25This won't display anything unless an example fails, in which case the
26failing 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
28line of output is "Test failed.".
29
30Run it with the -v switch instead:
31
32python M.py -v
33
34and a detailed report of all examples tried is printed to stdout, along
35with assorted summaries at the end.
36
37You can force verbose mode by passing "verbose=True" to testmod, or prohibit
38it by passing "verbose=False".  In either of those cases, sys.argv is not
39examined by testmod.
40
41There are a variety of other ways to run doctests, including integration
42with the unittest framework, and support for running non-Python text
43files containing doctests.  There are also many ways to override parts
44of doctest's default behaviors.  See the Library Reference Manual for
45details.
46"""
47
48__docformat__ = 'reStructuredText en'
49
50__all__ = [
51    # 0, Option Flags
52    'register_optionflag',
53    'DONT_ACCEPT_TRUE_FOR_1',
54    'DONT_ACCEPT_BLANKLINE',
55    'NORMALIZE_WHITESPACE',
56    'ELLIPSIS',
57    'IGNORE_EXCEPTION_DETAIL',
58    'COMPARISON_FLAGS',
59    'REPORT_UDIFF',
60    'REPORT_CDIFF',
61    'REPORT_NDIFF',
62    'REPORT_ONLY_FIRST_FAILURE',
63    'REPORTING_FLAGS',
64    # 1. Utility Functions
65    'is_private',
66    # 2. Example & DocTest
67    'Example',
68    'DocTest',
69    # 3. Doctest Parser
70    'DocTestParser',
71    # 4. Doctest Finder
72    'DocTestFinder',
73    # 5. Doctest Runner
74    'DocTestRunner',
75    'OutputChecker',
76    'DocTestFailure',
77    'UnexpectedException',
78    'DebugRunner',
79    # 6. Test Functions
80    'testmod',
81    'testfile',
82    'run_docstring_examples',
83    # 7. Tester
84    'Tester',
85    # 8. Unittest Support
86    'DocTestSuite',
87    'DocFileSuite',
88    'set_unittest_reportflags',
89    # 9. Debugging Support
90    'script_from_examples',
91    'testsource',
92    'debug_src',
93    'debug',
94]
95
96import __future__
97
98import sys, traceback, inspect, linecache, os, re, types
99import unittest, difflib, pdb, tempfile
100import warnings
101from StringIO import StringIO
102
103# Don't whine about the deprecated is_private function in this
104# module's tests.
105warnings.filterwarnings("ignore", "is_private", DeprecationWarning,
106                        __name__, 0)
107
108# There are 4 basic classes:
109#  - Example: a <source, want> pair, plus an intra-docstring line number.
110#  - DocTest: a collection of examples, parsed from a docstring, plus
111#    info about where the docstring came from (name, filename, lineno).
112#  - DocTestFinder: extracts DocTests from a given object's docstring and
113#    its contained objects' docstrings.
114#  - DocTestRunner: runs DocTest cases, and accumulates statistics.
115#
116# So the basic picture is:
117#
118#                             list of:
119# +------+                   +---------+                   +-------+
120# |object| --DocTestFinder-> | DocTest | --DocTestRunner-> |results|
121# +------+                   +---------+                   +-------+
122#                            | Example |
123#                            |   ...   |
124#                            | Example |
125#                            +---------+
126
127# Option constants.
128
129OPTIONFLAGS_BY_NAME = {}
130def register_optionflag(name):
131    flag = 1 << len(OPTIONFLAGS_BY_NAME)
132    OPTIONFLAGS_BY_NAME[name] = flag
133    return flag
134
135DONT_ACCEPT_TRUE_FOR_1 = register_optionflag('DONT_ACCEPT_TRUE_FOR_1')
136DONT_ACCEPT_BLANKLINE = register_optionflag('DONT_ACCEPT_BLANKLINE')
137NORMALIZE_WHITESPACE = register_optionflag('NORMALIZE_WHITESPACE')
138ELLIPSIS = register_optionflag('ELLIPSIS')
139IGNORE_EXCEPTION_DETAIL = register_optionflag('IGNORE_EXCEPTION_DETAIL')
140
141COMPARISON_FLAGS = (DONT_ACCEPT_TRUE_FOR_1 |
142                    DONT_ACCEPT_BLANKLINE |
143                    NORMALIZE_WHITESPACE |
144                    ELLIPSIS |
145                    IGNORE_EXCEPTION_DETAIL)
146
147REPORT_UDIFF = register_optionflag('REPORT_UDIFF')
148REPORT_CDIFF = register_optionflag('REPORT_CDIFF')
149REPORT_NDIFF = register_optionflag('REPORT_NDIFF')
150REPORT_ONLY_FIRST_FAILURE = register_optionflag('REPORT_ONLY_FIRST_FAILURE')
151
152REPORTING_FLAGS = (REPORT_UDIFF |
153                   REPORT_CDIFF |
154                   REPORT_NDIFF |
155                   REPORT_ONLY_FIRST_FAILURE)
156
157# Special string markers for use in `want` strings:
158BLANKLINE_MARKER = '<BLANKLINE>'
159ELLIPSIS_MARKER = '...'
160
161######################################################################
162## Table of Contents
163######################################################################
164#  1. Utility Functions
165#  2. Example & DocTest -- store test cases
166#  3. DocTest Parser -- extracts examples from strings
167#  4. DocTest Finder -- extracts test cases from objects
168#  5. DocTest Runner -- runs test cases
169#  6. Test Functions -- convenient wrappers for testing
170#  7. Tester Class -- for backwards compatibility
171#  8. Unittest Support
172#  9. Debugging Support
173# 10. Example Usage
174
175######################################################################
176## 1. Utility Functions
177######################################################################
178
179def is_private(prefix, base):
180    """prefix, base -> true iff name prefix + "." + base is "private".
181
182    Prefix may be an empty string, and base does not contain a period.
183    Prefix is ignored (although functions you write conforming to this
184    protocol may make use of it).
185    Return true iff base begins with an (at least one) underscore, but
186    does not both begin and end with (at least) two underscores.
187
188    >>> is_private("a.b", "my_func")
189    False
190    >>> is_private("____", "_my_func")
191    True
192    >>> is_private("someclass", "__init__")
193    False
194    >>> is_private("sometypo", "__init_")
195    True
196    >>> is_private("x.y.z", "_")
197    True
198    >>> is_private("_x.y.z", "__")
199    False
200    >>> is_private("", "")  # senseless but consistent
201    False
202    """
203    warnings.warn("is_private is deprecated; it wasn't useful; "
204                  "examine DocTestFinder.find() lists instead",
205                  DeprecationWarning, stacklevel=2)
206    return base[:1] == "_" and not base[:2] == "__" == base[-2:]
207
208def _extract_future_flags(globs):
209    """
210    Return the compiler-flags associated with the future features that
211    have been imported into the given namespace (globs).
212    """
213    flags = 0
214    for fname in __future__.all_feature_names:
215        feature = globs.get(fname, None)
216        if feature is getattr(__future__, fname):
217            flags |= feature.compiler_flag
218    return flags
219
220def _normalize_module(module, depth=2):
221    """
222    Return the module specified by `module`.  In particular:
223      - If `module` is a module, then return module.
224      - If `module` is a string, then import and return the
225        module with that name.
226      - If `module` is None, then return the calling module.
227        The calling module is assumed to be the module of
228        the stack frame at the given depth in the call stack.
229    """
230    if inspect.ismodule(module):
231        return module
232    elif isinstance(module, (str, unicode)):
233        return __import__(module, globals(), locals(), ["*"])
234    elif module is None:
235        return sys.modules[sys._getframe(depth).f_globals['__name__']]
236    else:
237        raise TypeError("Expected a module, string, or None")
238
239def _indent(s, indent=4):
240    """
241    Add the given number of space characters to the beginning every
242    non-blank line in `s`, and return the result.
243    """
244    # This regexp matches the start of non-blank lines:
245    return re.sub('(?m)^(?!$)', indent*' ', s)
246
247def _exception_traceback(exc_info):
248    """
249    Return a string containing a traceback message for the given
250    exc_info tuple (as returned by sys.exc_info()).
251    """
252    # Get a traceback message.
253    excout = StringIO()
254    exc_type, exc_val, exc_tb = exc_info
255    traceback.print_exception(exc_type, exc_val, exc_tb, file=excout)
256    return excout.getvalue()
257
258# Override some StringIO methods.
259class _SpoofOut(StringIO):
260    def getvalue(self):
261        result = StringIO.getvalue(self)
262        # If anything at all was written, make sure there's a trailing
263        # newline.  There's no way for the expected output to indicate
264        # that a trailing newline is missing.
265        if result and not result.endswith("\n"):
266            result += "\n"
267        # Prevent softspace from screwing up the next test case, in
268        # case they used print with a trailing comma in an example.
269        if hasattr(self, "softspace"):
270            del self.softspace
271        return result
272
273    def truncate(self,   size=None):
274        StringIO.truncate(self, size)
275        if hasattr(self, "softspace"):
276            del self.softspace
277
278# Worst-case linear-time ellipsis matching.
279def _ellipsis_match(want, got):
280    """
281    Essentially the only subtle case:
282    >>> _ellipsis_match('aa...aa', 'aaa')
283    False
284    """
285    if ELLIPSIS_MARKER not in want:
286        return want == got
287
288    # Find "the real" strings.
289    ws = want.split(ELLIPSIS_MARKER)
290    assert len(ws) >= 2
291
292    # Deal with exact matches possibly needed at one or both ends.
293    startpos, endpos = 0, len(got)
294    w = ws[0]
295    if w:   # starts with exact match
296        if got.startswith(w):
297            startpos = len(w)
298            del ws[0]
299        else:
300            return False
301    w = ws[-1]
302    if w:   # ends with exact match
303        if got.endswith(w):
304            endpos -= len(w)
305            del ws[-1]
306        else:
307            return False
308
309    if startpos > endpos:
310        # Exact end matches required more characters than we have, as in
311        # _ellipsis_match('aa...aa', 'aaa')
312        return False
313
314    # For the rest, we only need to find the leftmost non-overlapping
315    # match for each piece.  If there's no overall match that way alone,
316    # there's no overall match period.
317    for w in ws:
318        # w may be '' at times, if there are consecutive ellipses, or
319        # due to an ellipsis at the start or end of `want`.  That's OK.
320        # Search for an empty string succeeds, and doesn't change startpos.
321        startpos = got.find(w, startpos, endpos)
322        if startpos < 0:
323            return False
324        startpos += len(w)
325
326    return True
327
328def _comment_line(line):
329    "Return a commented form of the given line"
330    line = line.rstrip()
331    if line:
332        return '# '+line
333    else:
334        return '#'
335
336class _OutputRedirectingPdb(pdb.Pdb):
337    """
338    A specialized version of the python debugger that redirects stdout
339    to a given stream when interacting with the user.  Stdout is *not*
340    redirected when traced code is executed.
341    """
342    def __init__(self, out):
343        self.__out = out
344        pdb.Pdb.__init__(self)
345
346    def trace_dispatch(self, *args):
347        # Redirect stdout to the given stream.
348        save_stdout = sys.stdout
349        sys.stdout = self.__out
350        # Call Pdb's trace dispatch method.
351        try:
352            return pdb.Pdb.trace_dispatch(self, *args)
353        finally:
354            sys.stdout = save_stdout
355
356# [XX] Normalize with respect to os.path.pardir?
357def _module_relative_path(module, path):
358    if not inspect.ismodule(module):
359        raise TypeError, 'Expected a module: %r' % module
360    if path.startswith('/'):
361        raise ValueError, 'Module-relative files may not have absolute paths'
362
363    # Find the base directory for the path.
364    if hasattr(module, '__file__'):
365        # A normal module/package
366        basedir = os.path.split(module.__file__)[0]
367    elif module.__name__ == '__main__':
368        # An interactive session.
369        if len(sys.argv)>0 and sys.argv[0] != '':
370            basedir = os.path.split(sys.argv[0])[0]
371        else:
372            basedir = os.curdir
373    else:
374        # A module w/o __file__ (this includes builtins)
375        raise ValueError("Can't resolve paths relative to the module " +
376                         module + " (it has no __file__)")
377
378    # Combine the base directory and the path.
379    return os.path.join(basedir, *(path.split('/')))
380
381######################################################################
382## 2. Example & DocTest
383######################################################################
384## - An "example" is a <source, want> pair, where "source" is a
385##   fragment of source code, and "want" is the expected output for
386##   "source."  The Example class also includes information about
387##   where the example was extracted from.
388##
389## - A "doctest" is a collection of examples, typically extracted from
390##   a string (such as an object's docstring).  The DocTest class also
391##   includes information about where the string was extracted from.
392
393class Example:
394    """
395    A single doctest example, consisting of source code and expected
396    output.  `Example` defines the following attributes:
397
398      - source: A single Python statement, always ending with a newline.
399        The constructor adds a newline if needed.
400
401      - want: The expected output from running the source code (either
402        from stdout, or a traceback in case of exception).  `want` ends
403        with a newline unless it's empty, in which case it's an empty
404        string.  The constructor adds a newline if needed.
405
406      - exc_msg: The exception message generated by the example, if
407        the example is expected to generate an exception; or `None` if
408        it is not expected to generate an exception.  This exception
409        message is compared against the return value of
410        `traceback.format_exception_only()`.  `exc_msg` ends with a
411        newline unless it's `None`.  The constructor adds a newline
412        if needed.
413
414      - lineno: The line number within the DocTest string containing
415        this Example where the Example begins.  This line number is
416        zero-based, with respect to the beginning of the DocTest.
417
418      - indent: The example's indentation in the DocTest string.
419        I.e., the number of space characters that preceed the
420        example's first prompt.
421
422      - options: A dictionary mapping from option flags to True or
423        False, which is used to override default options for this
424        example.  Any option flags not contained in this dictionary
425        are left at their default value (as specified by the
426        DocTestRunner's optionflags).  By default, no options are set.
427    """
428    def __init__(self, source, want, exc_msg=None, lineno=0, indent=0,
429                 options=None):
430        # Normalize inputs.
431        if not source.endswith('\n'):
432            source += '\n'
433        if want and not want.endswith('\n'):
434            want += '\n'
435        if exc_msg is not None and not exc_msg.endswith('\n'):
436            exc_msg += '\n'
437        # Store properties.
438        self.source = source
439        self.want = want
440        self.lineno = lineno
441        self.indent = indent
442        if options is None: options = {}
443        self.options = options
444        self.exc_msg = exc_msg
445
446class DocTest:
447    """
448    A collection of doctest examples that should be run in a single
449    namespace.  Each `DocTest` defines the following attributes:
450
451      - examples: the list of examples.
452
453      - globs: The namespace (aka globals) that the examples should
454        be run in.
455
456      - name: A name identifying the DocTest (typically, the name of
457        the object whose docstring this DocTest was extracted from).
458
459      - filename: The name of the file that this DocTest was extracted
460        from, or `None` if the filename is unknown.
461
462      - lineno: The line number within filename where this DocTest
463        begins, or `None` if the line number is unavailable.  This
464        line number is zero-based, with respect to the beginning of
465        the file.
466
467      - docstring: The string that the examples were extracted from,
468        or `None` if the string is unavailable.
469    """
470    def __init__(self, examples, globs, name, filename, lineno, docstring):
471        """
472        Create a new DocTest containing the given examples.  The
473        DocTest's globals are initialized with a copy of `globs`.
474        """
475        assert not isinstance(examples, basestring), \
476               "DocTest no longer accepts str; use DocTestParser instead"
477        self.examples = examples
478        self.docstring = docstring
479        self.globs = globs.copy()
480        self.name = name
481        self.filename = filename
482        self.lineno = lineno
483
484    def __repr__(self):
485        if len(self.examples) == 0:
486            examples = 'no examples'
487        elif len(self.examples) == 1:
488            examples = '1 example'
489        else:
490            examples = '%d examples' % len(self.examples)
491        return ('<DocTest %s from %s:%s (%s)>' %
492                (self.name, self.filename, self.lineno, examples))
493
494
495    # This lets us sort tests by name:
496    def __cmp__(self, other):
497        if not isinstance(other, DocTest):
498            return -1
499        return cmp((self.name, self.filename, self.lineno, id(self)),
500                   (other.name, other.filename, other.lineno, id(other)))
501
502######################################################################
503## 3. DocTestParser
504######################################################################
505
506class DocTestParser:
507    """
508    A class used to parse strings containing doctest examples.
509    """
510    # This regular expression is used to find doctest examples in a
511    # string.  It defines three groups: `source` is the source code
512    # (including leading indentation and prompts); `indent` is the
513    # indentation of the first (PS1) line of the source code; and
514    # `want` is the expected output (including leading indentation).
515    _EXAMPLE_RE = re.compile(r'''
516        # Source consists of a PS1 line followed by zero or more PS2 lines.
517        (?P<source>
518            (?:^(?P<indent> [ ]*) >>>    .*)    # PS1 line
519            (?:\n           [ ]*  \.\.\. .*)*)  # PS2 lines
520        \n?
521        # Want consists of any non-blank lines that do not start with PS1.
522        (?P<want> (?:(?![ ]*$)    # Not a blank line
523                     (?![ ]*>>>)  # Not a line starting with PS1
524                     .*$\n?       # But any other line
525                  )*)
526        ''', re.MULTILINE | re.VERBOSE)
527
528    # A regular expression for handling `want` strings that contain
529    # expected exceptions.  It divides `want` into three pieces:
530    #    - the traceback header line (`hdr`)
531    #    - the traceback stack (`stack`)
532    #    - the exception message (`msg`), as generated by
533    #      traceback.format_exception_only()
534    # `msg` may have multiple lines.  We assume/require that the
535    # exception message is the first non-indented line starting with a word
536    # character following the traceback header line.
537    _EXCEPTION_RE = re.compile(r"""
538        # Grab the traceback header.  Different versions of Python have
539        # said different things on the first traceback line.
540        ^(?P<hdr> Traceback\ \(
541            (?: most\ recent\ call\ last
542            |   innermost\ last
543            ) \) :
544        )
545        \s* $                # toss trailing whitespace on the header.
546        (?P<stack> .*?)      # don't blink: absorb stuff until...
547        ^ (?P<msg> \w+ .*)   #     a line *starts* with alphanum.
548        """, re.VERBOSE | re.MULTILINE | re.DOTALL)
549
550    # A callable returning a true value iff its argument is a blank line
551    # or contains a single comment.
552    _IS_BLANK_OR_COMMENT = re.compile(r'^[ ]*(#.*)?$').match
553
554    def parse(self, string, name='<string>'):
555        """
556        Divide the given string into examples and intervening text,
557        and return them as a list of alternating Examples and strings.
558        Line numbers for the Examples are 0-based.  The optional
559        argument `name` is a name identifying this string, and is only
560        used for error messages.
561        """
562        string = string.expandtabs()
563        # If all lines begin with the same indentation, then strip it.
564        min_indent = self._min_indent(string)
565        if min_indent > 0:
566            string = '\n'.join([l[min_indent:] for l in string.split('\n')])
567
568        output = []
569        charno, lineno = 0, 0
570        # Find all doctest examples in the string:
571        for m in self._EXAMPLE_RE.finditer(string):
572            # Add the pre-example text to `output`.
573            output.append(string[charno:m.start()])
574            # Update lineno (lines before this example)
575            lineno += string.count('\n', charno, m.start())
576            # Extract info from the regexp match.
577            (source, options, want, exc_msg) = \
578                     self._parse_example(m, name, lineno)
579            # Create an Example, and add it to the list.
580            if not self._IS_BLANK_OR_COMMENT(source):
581                output.append( Example(source, want, exc_msg,
582                                    lineno=lineno,
583                                    indent=min_indent+len(m.group('indent')),
584                                    options=options) )
585            # Update lineno (lines inside this example)
586            lineno += string.count('\n', m.start(), m.end())
587            # Update charno.
588            charno = m.end()
589        # Add any remaining post-example text to `output`.
590        output.append(string[charno:])
591        return output
592
593    def get_doctest(self, string, globs, name, filename, lineno):
594        """
595        Extract all doctest examples from the given string, and
596        collect them into a `DocTest` object.
597
598        `globs`, `name`, `filename`, and `lineno` are attributes for
599        the new `DocTest` object.  See the documentation for `DocTest`
600        for more information.
601        """
602        return DocTest(self.get_examples(string, name), globs,
603                       name, filename, lineno, string)
604
605    def get_examples(self, string, name='<string>'):
606        """
607        Extract all doctest examples from the given string, and return
608        them as a list of `Example` objects.  Line numbers are
609        0-based, because it's most common in doctests that nothing
610        interesting appears on the same line as opening triple-quote,
611        and so the first interesting line is called \"line 1\" then.
612
613        The optional argument `name` is a name identifying this
614        string, and is only used for error messages.
615        """
616        return [x for x in self.parse(string, name)
617                if isinstance(x, Example)]
618
619    def _parse_example(self, m, name, lineno):
620        """
621        Given a regular expression match from `_EXAMPLE_RE` (`m`),
622        return a pair `(source, want)`, where `source` is the matched
623        example's source code (with prompts and indentation stripped);
624        and `want` is the example's expected output (with indentation
625        stripped).
626
627        `name` is the string's name, and `lineno` is the line number
628        where the example starts; both are used for error messages.
629        """
630        # Get the example's indentation level.
631        indent = len(m.group('indent'))
632
633        # Divide source into lines; check that they're properly
634        # indented; and then strip their indentation & prompts.
635        source_lines = m.group('source').split('\n')
636        self._check_prompt_blank(source_lines, indent, name, lineno)
637        self._check_prefix(source_lines[1:], ' '*indent + '.', name, lineno)
638        source = '\n'.join([sl[indent+4:] for sl in source_lines])
639
640        # Divide want into lines; check that it's properly indented; and
641        # then strip the indentation.  Spaces before the last newline should
642        # be preserved, so plain rstrip() isn't good enough.
643        want = m.group('want')
644        want_lines = want.split('\n')
645        if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]):
646            del want_lines[-1]  # forget final newline & spaces after it
647        self._check_prefix(want_lines, ' '*indent, name,
648                           lineno + len(source_lines))
649        want = '\n'.join([wl[indent:] for wl in want_lines])
650
651        # If `want` contains a traceback message, then extract it.
652        m = self._EXCEPTION_RE.match(want)
653        if m:
654            exc_msg = m.group('msg')
655        else:
656            exc_msg = None
657
658        # Extract options from the source.
659        options = self._find_options(source, name, lineno)
660
661        return source, options, want, exc_msg
662
663    # This regular expression looks for option directives in the
664    # source code of an example.  Option directives are comments
665    # starting with "doctest:".  Warning: this may give false
666    # positives for string-literals that contain the string
667    # "#doctest:".  Eliminating these false positives would require
668    # actually parsing the string; but we limit them by ignoring any
669    # line containing "#doctest:" that is *followed* by a quote mark.
670    _OPTION_DIRECTIVE_RE = re.compile(r'#\s*doctest:\s*([^\n\'"]*)$',
671                                      re.MULTILINE)
672
673    def _find_options(self, source, name, lineno):
674        """
675        Return a dictionary containing option overrides extracted from
676        option directives in the given source string.
677
678        `name` is the string's name, and `lineno` is the line number
679        where the example starts; both are used for error messages.
680        """
681        options = {}
682        # (note: with the current regexp, this will match at most once:)
683        for m in self._OPTION_DIRECTIVE_RE.finditer(source):
684            option_strings = m.group(1).replace(',', ' ').split()
685            for option in option_strings:
686                if (option[0] not in '+-' or
687                    option[1:] not in OPTIONFLAGS_BY_NAME):
688                    raise ValueError('line %r of the doctest for %s '
689                                     'has an invalid option: %r' %
690                                     (lineno+1, name, option))
691                flag = OPTIONFLAGS_BY_NAME[option[1:]]
692                options[flag] = (option[0] == '+')
693        if options and self._IS_BLANK_OR_COMMENT(source):
694            raise ValueError('line %r of the doctest for %s has an option '
695                             'directive on a line with no example: %r' %
696                             (lineno, name, source))
697        return options
698
699    # This regular expression finds the indentation of every non-blank
700    # line in a string.
701    _INDENT_RE = re.compile('^([ ]*)(?=\S)', re.MULTILINE)
702
703    def _min_indent(self, s):
704        "Return the minimum indentation of any non-blank line in `s`"
705        indents = [len(indent) for indent in self._INDENT_RE.findall(s)]
706        if len(indents) > 0:
707            return min(indents)
708        else:
709            return 0
710
711    def _check_prompt_blank(self, lines, indent, name, lineno):
712        """
713        Given the lines of a source string (including prompts and
714        leading indentation), check to make sure that every prompt is
715        followed by a space character.  If any line is not followed by
716        a space character, then raise ValueError.
717        """
718        for i, line in enumerate(lines):
719            if len(line) >= indent+4 and line[indent+3] != ' ':
720                raise ValueError('line %r of the docstring for %s '
721                                 'lacks blank after %s: %r' %
722                                 (lineno+i+1, name,
723                                  line[indent:indent+3], line))
724
725    def _check_prefix(self, lines, prefix, name, lineno):
726        """
727        Check that every line in the given list starts with the given
728        prefix; if any line does not, then raise a ValueError.
729        """
730        for i, line in enumerate(lines):
731            if line and not line.startswith(prefix):
732                raise ValueError('line %r of the docstring for %s has '
733                                 'inconsistent leading whitespace: %r' %
734                                 (lineno+i+1, name, line))
735
736
737######################################################################
738## 4. DocTest Finder
739######################################################################
740
741class DocTestFinder:
742    """
743    A class used to extract the DocTests that are relevant to a given
744    object, from its docstring and the docstrings of its contained
745    objects.  Doctests can currently be extracted from the following
746    object types: modules, functions, classes, methods, staticmethods,
747    classmethods, and properties.
748    """
749
750    def __init__(self, verbose=False, parser=DocTestParser(),
751                 recurse=True, _namefilter=None, exclude_empty=True):
752        """
753        Create a new doctest finder.
754
755        The optional argument `parser` specifies a class or
756        function that should be used to create new DocTest objects (or
757        objects that implement the same interface as DocTest).  The
758        signature for this factory function should match the signature
759        of the DocTest constructor.
760
761        If the optional argument `recurse` is false, then `find` will
762        only examine the given object, and not any contained objects.
763
764        If the optional argument `exclude_empty` is false, then `find`
765        will include tests for objects with empty docstrings.
766        """
767        self._parser = parser
768        self._verbose = verbose
769        self._recurse = recurse
770        self._exclude_empty = exclude_empty
771        # _namefilter is undocumented, and exists only for temporary backward-
772        # compatibility support of testmod's deprecated isprivate mess.
773        self._namefilter = _namefilter
774
775    def find(self, obj, name=None, module=None, globs=None,
776             extraglobs=None):
777        """
778        Return a list of the DocTests that are defined by the given
779        object's docstring, or by any of its contained objects'
780        docstrings.
781
782        The optional parameter `module` is the module that contains
783        the given object.  If the module is not specified or is None, then
784        the test finder will attempt to automatically determine the
785        correct module.  The object's module is used:
786
787            - As a default namespace, if `globs` is not specified.
788            - To prevent the DocTestFinder from extracting DocTests
789              from objects that are imported from other modules.
790            - To find the name of the file containing the object.
791            - To help find the line number of the object within its
792              file.
793
794        Contained objects whose module does not match `module` are ignored.
795
796        If `module` is False, no attempt to find the module will be made.
797        This is obscure, of use mostly in tests:  if `module` is False, or
798        is None but cannot be found automatically, then all objects are
799        considered to belong to the (non-existent) module, so all contained
800        objects will (recursively) be searched for doctests.
801
802        The globals for each DocTest is formed by combining `globs`
803        and `extraglobs` (bindings in `extraglobs` override bindings
804        in `globs`).  A new copy of the globals dictionary is created
805        for each DocTest.  If `globs` is not specified, then it
806        defaults to the module's `__dict__`, if specified, or {}
807        otherwise.  If `extraglobs` is not specified, then it defaults
808        to {}.
809
810        """
811        # If name was not specified, then extract it from the object.
812        if name is None:
813            name = getattr(obj, '__name__', None)
814            if name is None:
815                raise ValueError("DocTestFinder.find: name must be given "
816                        "when obj.__name__ doesn't exist: %r" %
817                                 (type(obj),))
818
819        # Find the module that contains the given object (if obj is
820        # a module, then module=obj.).  Note: this may fail, in which
821        # case module will be None.
822        if module is False:
823            module = None
824        elif module is None:
825            module = inspect.getmodule(obj)
826
827        # Read the module's source code.  This is used by
828        # DocTestFinder._find_lineno to find the line number for a
829        # given object's docstring.
830        try:
831            file = inspect.getsourcefile(obj) or inspect.getfile(obj)
832            source_lines = linecache.getlines(file)
833            if not source_lines:
834                source_lines = None
835        except TypeError:
836            source_lines = None
837
838        # Initialize globals, and merge in extraglobs.
839        if globs is None:
840            if module is None:
841                globs = {}
842            else:
843                globs = module.__dict__.copy()
844        else:
845            globs = globs.copy()
846        if extraglobs is not None:
847            globs.update(extraglobs)
848
849        # Recursively expore `obj`, extracting DocTests.
850        tests = []
851        self._find(tests, obj, name, module, source_lines, globs, {})
852        return tests
853
854    def _filter(self, obj, prefix, base):
855        """
856        Return true if the given object should not be examined.
857        """
858        return (self._namefilter is not None and
859                self._namefilter(prefix, base))
860
861    def _from_module(self, module, object):
862        """
863        Return true if the given object is defined in the given
864        module.
865        """
866        if module is None:
867            return True
868        elif inspect.isfunction(object):
869            return module.__dict__ is object.func_globals
870        elif inspect.isclass(object):
871            return module.__name__ == object.__module__
872        elif inspect.getmodule(object) is not None:
873            return module is inspect.getmodule(object)
874        elif hasattr(object, '__module__'):
875            return module.__name__ == object.__module__
876        elif isinstance(object, property):
877            return True # [XX] no way not be sure.
878        else:
879            raise ValueError("object must be a class or function")
880
881    def _find(self, tests, obj, name, module, source_lines, globs, seen):
882        """
883        Find tests for the given object and any contained objects, and
884        add them to `tests`.
885        """
886        if self._verbose:
887            print 'Finding tests in %s' % name
888
889        # If we've already processed this object, then ignore it.
890        if id(obj) in seen:
891            return
892        seen[id(obj)] = 1
893
894        # Find a test for this object, and add it to the list of tests.
895        test = self._get_test(obj, name, module, globs, source_lines)
896        if test is not None:
897            tests.append(test)
898
899        # Look for tests in a module's contained objects.
900        if inspect.ismodule(obj) and self._recurse:
901            for valname, val in obj.__dict__.items():
902                # Check if this contained object should be ignored.
903                if self._filter(val, name, valname):
904                    continue
905                valname = '%s.%s' % (name, valname)
906                # Recurse to functions & classes.
907                if ((inspect.isfunction(val) or inspect.isclass(val)) and
908                    self._from_module(module, val)):
909                    self._find(tests, val, valname, module, source_lines,
910                               globs, seen)
911
912        # Look for tests in a module's __test__ dictionary.
913        if inspect.ismodule(obj) and self._recurse:
914            for valname, val in getattr(obj, '__test__', {}).items():
915                if not isinstance(valname, basestring):
916                    raise ValueError("DocTestFinder.find: __test__ keys "
917                                     "must be strings: %r" %
918                                     (type(valname),))
919                if not (inspect.isfunction(val) or inspect.isclass(val) or
920                        inspect.ismethod(val) or inspect.ismodule(val) or
921                        isinstance(val, basestring)):
922                    raise ValueError("DocTestFinder.find: __test__ values "
923                                     "must be strings, functions, methods, "
924                                     "classes, or modules: %r" %
925                                     (type(val),))
926                valname = '%s.__test__.%s' % (name, valname)
927                self._find(tests, val, valname, module, source_lines,
928                           globs, seen)
929
930        # Look for tests in a class's contained objects.
931        if inspect.isclass(obj) and self._recurse:
932            for valname, val in obj.__dict__.items():
933                # Check if this contained object should be ignored.
934                if self._filter(val, name, valname):
935                    continue
936                # Special handling for staticmethod/classmethod.
937                if isinstance(val, staticmethod):
938                    val = getattr(obj, valname)
939                if isinstance(val, classmethod):
940                    val = getattr(obj, valname).im_func
941
942                # Recurse to methods, properties, and nested classes.
943                if ((inspect.isfunction(val) or inspect.isclass(val) or
944                      isinstance(val, property)) and
945                      self._from_module(module, val)):
946                    valname = '%s.%s' % (name, valname)
947                    self._find(tests, val, valname, module, source_lines,
948                               globs, seen)
949
950    def _get_test(self, obj, name, module, globs, source_lines):
951        """
952        Return a DocTest for the given object, if it defines a docstring;
953        otherwise, return None.
954        """
955        # Extract the object's docstring.  If it doesn't have one,
956        # then return None (no test for this object).
957        if isinstance(obj, basestring):
958            docstring = obj
959        else:
960            try:
961                if obj.__doc__ is None:
962                    docstring = ''
963                else:
964                    docstring = obj.__doc__
965                    if not isinstance(docstring, basestring):
966                        docstring = str(docstring)
967            except (TypeError, AttributeError):
968                docstring = ''
969
970        # Find the docstring's location in the file.
971        lineno = self._find_lineno(obj, source_lines)
972
973        # Don't bother if the docstring is empty.
974        if self._exclude_empty and not docstring:
975            return None
976
977        # Return a DocTest for this object.
978        if module is None:
979            filename = None
980        else:
981            filename = getattr(module, '__file__', module.__name__)
982            if filename[-4:] in (".pyc", ".pyo"):
983                filename = filename[:-1]
984        return self._parser.get_doctest(docstring, globs, name,
985                                        filename, lineno)
986
987    def _find_lineno(self, obj, source_lines):
988        """
989        Return a line number of the given object's docstring.  Note:
990        this method assumes that the object has a docstring.
991        """
992        lineno = None
993
994        # Find the line number for modules.
995        if inspect.ismodule(obj):
996            lineno = 0
997
998        # Find the line number for classes.
999        # Note: this could be fooled if a class is defined multiple
1000        # times in a single file.
1001        if inspect.isclass(obj):
1002            if source_lines is None:
1003                return None
1004            pat = re.compile(r'^\s*class\s*%s\b' %
1005                             getattr(obj, '__name__', '-'))
1006            for i, line in enumerate(source_lines):
1007                if pat.match(line):
1008                    lineno = i
1009                    break
1010
1011        # Find the line number for functions & methods.
1012        if inspect.ismethod(obj): obj = obj.im_func
1013        if inspect.isfunction(obj): obj = obj.func_code
1014        if inspect.istraceback(obj): obj = obj.tb_frame
1015        if inspect.isframe(obj): obj = obj.f_code
1016        if inspect.iscode(obj):
1017            lineno = getattr(obj, 'co_firstlineno', None)-1
1018
1019        # Find the line number where the docstring starts.  Assume
1020        # that it's the first line that begins with a quote mark.
1021        # Note: this could be fooled by a multiline function
1022        # signature, where a continuation line begins with a quote
1023        # mark.
1024        if lineno is not None:
1025            if source_lines is None:
1026                return lineno+1
1027            pat = re.compile('(^|.*:)\s*\w*("|\')')
1028            for lineno in range(lineno, len(source_lines)):
1029                if pat.match(source_lines[lineno]):
1030                    return lineno
1031
1032        # We couldn't find the line number.
1033        return None
1034
1035######################################################################
1036## 5. DocTest Runner
1037######################################################################
1038
1039class DocTestRunner:
1040    """
1041    A class used to run DocTest test cases, and accumulate statistics.
1042    The `run` method is used to process a single DocTest case.  It
1043    returns a tuple `(f, t)`, where `t` is the number of test cases
1044    tried, and `f` is the number of test cases that failed.
1045
1046        >>> tests = DocTestFinder().find(_TestClass)
1047        >>> runner = DocTestRunner(verbose=False)
1048        >>> for test in tests:
1049        ...     print runner.run(test)
1050        (0, 2)
1051        (0, 1)
1052        (0, 2)
1053        (0, 2)
1054
1055    The `summarize` method prints a summary of all the test cases that
1056    have been run by the runner, and returns an aggregated `(f, t)`
1057    tuple:
1058
1059        >>> runner.summarize(verbose=1)
1060        4 items passed all tests:
1061           2 tests in _TestClass
1062           2 tests in _TestClass.__init__
1063           2 tests in _TestClass.get
1064           1 tests in _TestClass.square
1065        7 tests in 4 items.
1066        7 passed and 0 failed.
1067        Test passed.
1068        (0, 7)
1069
1070    The aggregated number of tried examples and failed examples is
1071    also available via the `tries` and `failures` attributes:
1072
1073        >>> runner.tries
1074        7
1075        >>> runner.failures
1076        0
1077
1078    The comparison between expected outputs and actual outputs is done
1079    by an `OutputChecker`.  This comparison may be customized with a
1080    number of option flags; see the documentation for `testmod` for
1081    more information.  If the option flags are insufficient, then the
1082    comparison may also be customized by passing a subclass of
1083    `OutputChecker` to the constructor.
1084
1085    The test runner's display output can be controlled in two ways.
1086    First, an output function (`out) can be passed to
1087    `TestRunner.run`; this function will be called with strings that
1088    should be displayed.  It defaults to `sys.stdout.write`.  If
1089    capturing the output is not sufficient, then the display output
1090    can be also customized by subclassing DocTestRunner, and
1091    overriding the methods `report_start`, `report_success`,
1092    `report_unexpected_exception`, and `report_failure`.
1093    """
1094    # This divider string is used to separate failure messages, and to
1095    # separate sections of the summary.
1096    DIVIDER = "*" * 70
1097
1098    def __init__(self, checker=None, verbose=None, optionflags=0):
1099        """
1100        Create a new test runner.
1101
1102        Optional keyword arg `checker` is the `OutputChecker` that
1103        should be used to compare the expected outputs and actual
1104        outputs of doctest examples.
1105
1106        Optional keyword arg 'verbose' prints lots of stuff if true,
1107        only failures if false; by default, it's true iff '-v' is in
1108        sys.argv.
1109
1110        Optional argument `optionflags` can be used to control how the
1111        test runner compares expected output to actual output, and how
1112        it displays failures.  See the documentation for `testmod` for
1113        more information.
1114        """
1115        self._checker = checker or OutputChecker()
1116        if verbose is None:
1117            verbose = '-v' in sys.argv
1118        self._verbose = verbose
1119        self.optionflags = optionflags
1120        self.original_optionflags = optionflags
1121
1122        # Keep track of the examples we've run.
1123        self.tries = 0
1124        self.failures = 0
1125        self._name2ft = {}
1126
1127        # Create a fake output target for capturing doctest output.
1128        self._fakeout = _SpoofOut()
1129
1130    #/////////////////////////////////////////////////////////////////
1131    # Reporting methods
1132    #/////////////////////////////////////////////////////////////////
1133
1134    def report_start(self, out, test, example):
1135        """
1136        Report that the test runner is about to process the given
1137        example.  (Only displays a message if verbose=True)
1138        """
1139        if self._verbose:
1140            if example.want:
1141                out('Trying:\n' + _indent(example.source) +
1142                    'Expecting:\n' + _indent(example.want))
1143            else:
1144                out('Trying:\n' + _indent(example.source) +
1145                    'Expecting nothing\n')
1146
1147    def report_success(self, out, test, example, got):
1148        """
1149        Report that the given example ran successfully.  (Only
1150        displays a message if verbose=True)
1151        """
1152        if self._verbose:
1153            out("ok\n")
1154
1155    def report_failure(self, out, test, example, got):
1156        """
1157        Report that the given example failed.
1158        """
1159        out(self._failure_header(test, example) +
1160            self._checker.output_difference(example, got, self.optionflags))
1161
1162    def report_unexpected_exception(self, out, test, example, exc_info):
1163        """
1164        Report that the given example raised an unexpected exception.
1165        """
1166        out(self._failure_header(test, example) +
1167            'Exception raised:\n' + _indent(_exception_traceback(exc_info)))
1168
1169    def _failure_header(self, test, example):
1170        out = [self.DIVIDER]
1171        if test.filename:
1172            if test.lineno is not None and example.lineno is not None:
1173                lineno = test.lineno + example.lineno + 1
1174            else:
1175                lineno = '?'
1176            out.append('File "%s", line %s, in %s' %
1177                       (test.filename, lineno, test.name))
1178        else:
1179            out.append('Line %s, in %s' % (example.lineno+1, test.name))
1180        out.append('Failed example:')
1181        source = example.source
1182        out.append(_indent(source))
1183        return '\n'.join(out)
1184
1185    #/////////////////////////////////////////////////////////////////
1186    # DocTest Running
1187    #/////////////////////////////////////////////////////////////////
1188
1189    def __run(self, test, compileflags, out):
1190        """
1191        Run the examples in `test`.  Write the outcome of each example
1192        with one of the `DocTestRunner.report_*` methods, using the
1193        writer function `out`.  `compileflags` is the set of compiler
1194        flags that should be used to execute examples.  Return a tuple
1195        `(f, t)`, where `t` is the number of examples tried, and `f`
1196        is the number of examples that failed.  The examples are run
1197        in the namespace `test.globs`.
1198        """
1199        # Keep track of the number of failures and tries.
1200        failures = tries = 0
1201
1202        # Save the option flags (since option directives can be used
1203        # to modify them).
1204        original_optionflags = self.optionflags
1205
1206        SUCCESS, FAILURE, BOOM = range(3) # `outcome` state
1207
1208        check = self._checker.check_output
1209
1210        # Process each example.
1211        for examplenum, example in enumerate(test.examples):
1212
1213            # If REPORT_ONLY_FIRST_FAILURE is set, then supress
1214            # reporting after the first failure.
1215            quiet = (self.optionflags & REPORT_ONLY_FIRST_FAILURE and
1216                     failures > 0)
1217
1218            # Merge in the example's options.
1219            self.optionflags = original_optionflags
1220            if example.options:
1221                for (optionflag, val) in example.options.items():
1222                    if val:
1223                        self.optionflags |= optionflag
1224                    else:
1225                        self.optionflags &= ~optionflag
1226
1227            # Record that we started this example.
1228            tries += 1
1229            if not quiet:
1230                self.report_start(out, test, example)
1231
1232            # Use a special filename for compile(), so we can retrieve
1233            # the source code during interactive debugging (see
1234            # __patched_linecache_getlines).
1235            filename = '<doctest %s[%d]>' % (test.name, examplenum)
1236
1237            # Run the example in the given context (globs), and record
1238            # any exception that gets raised.  (But don't intercept
1239            # keyboard interrupts.)
1240            try:
1241                # Don't blink!  This is where the user's code gets run.
1242                exec compile(example.source, filename, "single",
1243                             compileflags, 1) in test.globs
1244                self.debugger.set_continue() # ==== Example Finished ====
1245                exception = None
1246            except KeyboardInterrupt:
1247                raise
1248            except:
1249                exception = sys.exc_info()
1250                self.debugger.set_continue() # ==== Example Finished ====
1251
1252            got = self._fakeout.getvalue()  # the actual output
1253            self._fakeout.truncate(0)
1254            outcome = FAILURE   # guilty until proved innocent or insane
1255
1256            # If the example executed without raising any exceptions,
1257            # verify its output.
1258            if exception is None:
1259                if check(example.want, got, self.optionflags):
1260                    outcome = SUCCESS
1261
1262            # The example raised an exception:  check if it was expected.
1263            else:
1264                exc_info = sys.exc_info()
1265                exc_msg = traceback.format_exception_only(*exc_info[:2])[-1]
1266                if not quiet:
1267                    got += _exception_traceback(exc_info)
1268
1269                # If `example.exc_msg` is None, then we weren't expecting
1270                # an exception.
1271                if example.exc_msg is None:
1272                    outcome = BOOM
1273
1274                # We expected an exception:  see whether it matches.
1275                elif check(example.exc_msg, exc_msg, self.optionflags):
1276                    outcome = SUCCESS
1277
1278                # Another chance if they didn't care about the detail.
1279                elif self.optionflags & IGNORE_EXCEPTION_DETAIL:
1280                    m1 = re.match(r'[^:]*:', example.exc_msg)
1281                    m2 = re.match(r'[^:]*:', exc_msg)
1282                    if m1 and m2 and check(m1.group(0), m2.group(0),
1283                                           self.optionflags):
1284                        outcome = SUCCESS
1285
1286            # Report the outcome.
1287            if outcome is SUCCESS:
1288                if not quiet:
1289                    self.report_success(out, test, example, got)
1290            elif outcome is FAILURE:
1291                if not quiet:
1292                    self.report_failure(out, test, example, got)
1293                failures += 1
1294            elif outcome is BOOM:
1295                if not quiet:
1296                    self.report_unexpected_exception(out, test, example,
1297                                                     exc_info)
1298                failures += 1
1299            else:
1300                assert False, ("unknown outcome", outcome)
1301
1302        # Restore the option flags (in case they were modified)
1303        self.optionflags = original_optionflags
1304
1305        # Record and return the number of failures and tries.
1306        self.__record_outcome(test, failures, tries)
1307        return failures, tries
1308
1309    def __record_outcome(self, test, f, t):
1310        """
1311        Record the fact that the given DocTest (`test`) generated `f`
1312        failures out of `t` tried examples.
1313        """
1314        f2, t2 = self._name2ft.get(test.name, (0,0))
1315        self._name2ft[test.name] = (f+f2, t+t2)
1316        self.failures += f
1317        self.tries += t
1318
1319    __LINECACHE_FILENAME_RE = re.compile(r'<doctest '
1320                                         r'(?P<name>[\w\.]+)'
1321                                         r'\[(?P<examplenum>\d+)\]>$')
1322    def __patched_linecache_getlines(self, filename):
1323        m = self.__LINECACHE_FILENAME_RE.match(filename)
1324        if m and m.group('name') == self.test.name:
1325            example = self.test.examples[int(m.group('examplenum'))]
1326            return example.source.splitlines(True)
1327        else:
1328            return self.save_linecache_getlines(filename)
1329
1330    def run(self, test, compileflags=None, out=None, clear_globs=True):
1331        """
1332        Run the examples in `test`, and display the results using the
1333        writer function `out`.
1334
1335        The examples are run in the namespace `test.globs`.  If
1336        `clear_globs` is true (the default), then this namespace will
1337        be cleared after the test runs, to help with garbage
1338        collection.  If you would like to examine the namespace after
1339        the test completes, then use `clear_globs=False`.
1340
1341        `compileflags` gives the set of flags that should be used by
1342        the Python compiler when running the examples.  If not
1343        specified, then it will default to the set of future-import
1344        flags that apply to `globs`.
1345
1346        The output of each example is checked using
1347        `DocTestRunner.check_output`, and the results are formatted by
1348        the `DocTestRunner.report_*` methods.
1349        """
1350        self.test = test
1351
1352        if compileflags is None:
1353            compileflags = _extract_future_flags(test.globs)
1354
1355        save_stdout = sys.stdout
1356        if out is None:
1357            out = save_stdout.write
1358        sys.stdout = self._fakeout
1359
1360        # Patch pdb.set_trace to restore sys.stdout during interactive
1361        # debugging (so it's not still redirected to self._fakeout).
1362        # Note that the interactive output will go to *our*
1363        # save_stdout, even if that's not the real sys.stdout; this
1364        # allows us to write test cases for the set_trace behavior.
1365        save_set_trace = pdb.set_trace
1366        self.debugger = _OutputRedirectingPdb(save_stdout)
1367        self.debugger.reset()
1368        pdb.set_trace = self.debugger.set_trace
1369
1370        # Patch linecache.getlines, so we can see the example's source
1371        # when we're inside the debugger.
1372        self.save_linecache_getlines = linecache.getlines
1373        linecache.getlines = self.__patched_linecache_getlines
1374
1375        try:
1376            return self.__run(test, compileflags, out)
1377        finally:
1378            sys.stdout = save_stdout
1379            pdb.set_trace = save_set_trace
1380            linecache.getlines = self.save_linecache_getlines
1381            if clear_globs:
1382                test.globs.clear()
1383
1384    #/////////////////////////////////////////////////////////////////
1385    # Summarization
1386    #/////////////////////////////////////////////////////////////////
1387    def summarize(self, verbose=None):
1388        """
1389        Print a summary of all the test cases that have been run by
1390        this DocTestRunner, and return a tuple `(f, t)`, where `f` is
1391        the total number of failed examples, and `t` is the total
1392        number of tried examples.
1393
1394        The optional `verbose` argument controls how detailed the
1395        summary is.  If the verbosity is not specified, then the
1396        DocTestRunner's verbosity is used.
1397        """
1398        if verbose is None:
1399            verbose = self._verbose
1400        notests = []
1401        passed = []
1402        failed = []
1403        totalt = totalf = 0
1404        for x in self._name2ft.items():
1405            name, (f, t) = x
1406            assert f <= t
1407            totalt += t
1408            totalf += f
1409            if t == 0:
1410                notests.append(name)
1411            elif f == 0:
1412                passed.append( (name, t) )
1413            else:
1414                failed.append(x)
1415        if verbose:
1416            if notests:
1417                print len(notests), "items had no tests:"
1418                notests.sort()
1419                for thing in notests:
1420                    print "   ", thing
1421            if passed:
1422                print len(passed), "items passed all tests:"
1423                passed.sort()
1424                for thing, count in passed:
1425                    print " %3d tests in %s" % (count, thing)
1426        if failed:
1427            print self.DIVIDER
1428            print len(failed), "items had failures:"
1429            failed.sort()
1430            for thing, (f, t) in failed:
1431                print " %3d of %3d in %s" % (f, t, thing)
1432        if verbose:
1433            print totalt, "tests in", len(self._name2ft), "items."
1434            print totalt - totalf, "passed and", totalf, "failed."
1435        if totalf:
1436            print "***Test Failed***", totalf, "failures."
1437        elif verbose:
1438            print "Test passed."
1439        return totalf, totalt
1440
1441    #/////////////////////////////////////////////////////////////////
1442    # Backward compatibility cruft to maintain doctest.master.
1443    #/////////////////////////////////////////////////////////////////
1444    def merge(self, other):
1445        d = self._name2ft
1446        for name, (f, t) in other._name2ft.items():
1447            if name in d:
1448                print "*** DocTestRunner.merge: '" + name + "' in both" \
1449                    " testers; summing outcomes."
1450                f2, t2 = d[name]
1451                f = f + f2
1452                t = t + t2
1453            d[name] = f, t
1454
1455class OutputChecker:
1456    """
1457    A class used to check the whether the actual output from a doctest
1458    example matches the expected output.  `OutputChecker` defines two
1459    methods: `check_output`, which compares a given pair of outputs,
1460    and returns true if they match; and `output_difference`, which
1461    returns a string describing the differences between two outputs.
1462    """
1463    def check_output(self, want, got, optionflags):
1464        """
1465        Return True iff the actual output from an example (`got`)
1466        matches the expected output (`want`).  These strings are
1467        always considered to match if they are identical; but
1468        depending on what option flags the test runner is using,
1469        several non-exact match types are also possible.  See the
1470        documentation for `TestRunner` for more information about
1471        option flags.
1472        """
1473        # Handle the common case first, for efficiency:
1474        # if they're string-identical, always return true.
1475        if got == want:
1476            return True
1477
1478        # The values True and False replaced 1 and 0 as the return
1479        # value for boolean comparisons in Python 2.3.
1480        if not (optionflags & DONT_ACCEPT_TRUE_FOR_1):
1481            if (got,want) == ("True\n", "1\n"):
1482                return True
1483            if (got,want) == ("False\n", "0\n"):
1484                return True
1485
1486        # <BLANKLINE> can be used as a special sequence to signify a
1487        # blank line, unless the DONT_ACCEPT_BLANKLINE flag is used.
1488        if not (optionflags & DONT_ACCEPT_BLANKLINE):
1489            # Replace <BLANKLINE> in want with a blank line.
1490            want = re.sub('(?m)^%s\s*?$' % re.escape(BLANKLINE_MARKER),
1491                          '', want)
1492            # If a line in got contains only spaces, then remove the
1493            # spaces.
1494            got = re.sub('(?m)^\s*?$', '', got)
1495            if got == want:
1496                return True
1497
1498        # This flag causes doctest to ignore any differences in the
1499        # contents of whitespace strings.  Note that this can be used
1500        # in conjunction with the ELLIPSIS flag.
1501        if optionflags & NORMALIZE_WHITESPACE:
1502            got = ' '.join(got.split())
1503            want = ' '.join(want.split())
1504            if got == want:
1505                return True
1506
1507        # The ELLIPSIS flag says to let the sequence "..." in `want`
1508        # match any substring in `got`.
1509        if optionflags & ELLIPSIS:
1510            if _ellipsis_match(want, got):
1511                return True
1512
1513        # We didn't find any match; return false.
1514        return False
1515
1516    # Should we do a fancy diff?
1517    def _do_a_fancy_diff(self, want, got, optionflags):
1518        # Not unless they asked for a fancy diff.
1519        if not optionflags & (REPORT_UDIFF |
1520                              REPORT_CDIFF |
1521                              REPORT_NDIFF):
1522            return False
1523
1524        # If expected output uses ellipsis, a meaningful fancy diff is
1525        # too hard ... or maybe not.  In two real-life failures Tim saw,
1526        # a diff was a major help anyway, so this is commented out.
1527        # [todo] _ellipsis_match() knows which pieces do and don't match,
1528        # and could be the basis for a kick-ass diff in this case.
1529        ##if optionflags & ELLIPSIS and ELLIPSIS_MARKER in want:
1530        ##    return False
1531
1532        # ndiff does intraline difference marking, so can be useful even
1533        # for 1-line differences.
1534        if optionflags & REPORT_NDIFF:
1535            return True
1536
1537        # The other diff types need at least a few lines to be helpful.
1538        return want.count('\n') > 2 and got.count('\n') > 2
1539
1540    def output_difference(self, example, got, optionflags):
1541        """
1542        Return a string describing the differences between the
1543        expected output for a given example (`example`) and the actual
1544        output (`got`).  `optionflags` is the set of option flags used
1545        to compare `want` and `got`.
1546        """
1547        want = example.want
1548        # If <BLANKLINE>s are being used, then replace blank lines
1549        # with <BLANKLINE> in the actual output string.
1550        if not (optionflags & DONT_ACCEPT_BLANKLINE):
1551            got = re.sub('(?m)^[ ]*(?=\n)', BLANKLINE_MARKER, got)
1552
1553        # Check if we should use diff.
1554        if self._do_a_fancy_diff(want, got, optionflags):
1555            # Split want & got into lines.
1556            want_lines = want.splitlines(True)  # True == keep line ends
1557            got_lines = got.splitlines(True)
1558            # Use difflib to find their differences.
1559            if optionflags & REPORT_UDIFF:
1560                diff = difflib.unified_diff(want_lines, got_lines, n=2)
1561                diff = list(diff)[2:] # strip the diff header
1562                kind = 'unified diff with -expected +actual'
1563            elif optionflags & REPORT_CDIFF:
1564                diff = difflib.context_diff(want_lines, got_lines, n=2)
1565                diff = list(diff)[2:] # strip the diff header
1566                kind = 'context diff with expected followed by actual'
1567            elif optionflags & REPORT_NDIFF:
1568                engine = difflib.Differ(charjunk=difflib.IS_CHARACTER_JUNK)
1569                diff = list(engine.compare(want_lines, got_lines))
1570                kind = 'ndiff with -expected +actual'
1571            else:
1572                assert 0, 'Bad diff option'
1573            # Remove trailing whitespace on diff output.
1574            diff = [line.rstrip() + '\n' for line in diff]
1575            return 'Differences (%s):\n' % kind + _indent(''.join(diff))
1576
1577        # If we're not using diff, then simply list the expected
1578        # output followed by the actual output.
1579        if want and got:
1580            return 'Expected:\n%sGot:\n%s' % (_indent(want), _indent(got))
1581        elif want:
1582            return 'Expected:\n%sGot nothing\n' % _indent(want)
1583        elif got:
1584            return 'Expected nothing\nGot:\n%s' % _indent(got)
1585        else:
1586            return 'Expected nothing\nGot nothing\n'
1587
1588class DocTestFailure(Exception):
1589    """A DocTest example has failed in debugging mode.
1590
1591    The exception instance has variables:
1592
1593    - test: the DocTest object being run
1594
1595    - excample: the Example object that failed
1596
1597    - got: the actual output
1598    """
1599    def __init__(self, test, example, got):
1600        self.test = test
1601        self.example = example
1602        self.got = got
1603
1604    def __str__(self):
1605        return str(self.test)
1606
1607class UnexpectedException(Exception):
1608    """A DocTest example has encountered an unexpected exception
1609
1610    The exception instance has variables:
1611
1612    - test: the DocTest object being run
1613
1614    - excample: the Example object that failed
1615
1616    - exc_info: the exception info
1617    """
1618    def __init__(self, test, example, exc_info):
1619        self.test = test
1620        self.example = example
1621        self.exc_info = exc_info
1622
1623    def __str__(self):
1624        return str(self.test)
1625
1626class DebugRunner(DocTestRunner):
1627    r"""Run doc tests but raise an exception as soon as there is a failure.
1628
1629       If an unexpected exception occurs, an UnexpectedException is raised.
1630       It contains the test, the example, and the original exception:
1631
1632         >>> runner = DebugRunner(verbose=False)
1633         >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
1634         ...                                    {}, 'foo', 'foo.py', 0)
1635         >>> try:
1636         ...     runner.run(test)
1637         ... except UnexpectedException, failure:
1638         ...     pass
1639
1640         >>> failure.test is test
1641         True
1642
1643         >>> failure.example.want
1644         '42\n'
1645
1646         >>> exc_info = failure.exc_info
1647         >>> raise exc_info[0], exc_info[1], exc_info[2]
1648         Traceback (most recent call last):
1649         ...
1650         KeyError
1651
1652       We wrap the original exception to give the calling application
1653       access to the test and example information.
1654
1655       If the output doesn't match, then a DocTestFailure is raised:
1656
1657         >>> test = DocTestParser().get_doctest('''
1658         ...      >>> x = 1
1659         ...      >>> x
1660         ...      2
1661         ...      ''', {}, 'foo', 'foo.py', 0)
1662
1663         >>> try:
1664         ...    runner.run(test)
1665         ... except DocTestFailure, failure:
1666         ...    pass
1667
1668       DocTestFailure objects provide access to the test:
1669
1670         >>> failure.test is test
1671         True
1672
1673       As well as to the example:
1674
1675         >>> failure.example.want
1676         '2\n'
1677
1678       and the actual output:
1679
1680         >>> failure.got
1681         '1\n'
1682
1683       If a failure or error occurs, the globals are left intact:
1684
1685         >>> del test.globs['__builtins__']
1686         >>> test.globs
1687         {'x': 1}
1688
1689         >>> test = DocTestParser().get_doctest('''
1690         ...      >>> x = 2
1691         ...      >>> raise KeyError
1692         ...      ''', {}, 'foo', 'foo.py', 0)
1693
1694         >>> runner.run(test)
1695         Traceback (most recent call last):
1696         ...
1697         UnexpectedException: <DocTest foo from foo.py:0 (2 examples)>
1698
1699         >>> del test.globs['__builtins__']
1700         >>> test.globs
1701         {'x': 2}
1702
1703       But the globals are cleared if there is no error:
1704
1705         >>> test = DocTestParser().get_doctest('''
1706         ...      >>> x = 2
1707         ...      ''', {}, 'foo', 'foo.py', 0)
1708
1709         >>> runner.run(test)
1710         (0, 1)
1711
1712         >>> test.globs
1713         {}
1714
1715       """
1716
1717    def run(self, test, compileflags=None, out=None, clear_globs=True):
1718        r = DocTestRunner.run(self, test, compileflags, out, False)
1719        if clear_globs:
1720            test.globs.clear()
1721        return r
1722
1723    def report_unexpected_exception(self, out, test, example, exc_info):
1724        raise UnexpectedException(test, example, exc_info)
1725
1726    def report_failure(self, out, test, example, got):
1727        raise DocTestFailure(test, example, got)
1728
1729######################################################################
1730## 6. Test Functions
1731######################################################################
1732# These should be backwards compatible.
1733
1734# For backward compatibility, a global instance of a DocTestRunner
1735# class, updated by testmod.
1736master = None
1737
1738def testmod(m=None, name=None, globs=None, verbose=None, isprivate=None,
1739            report=True, optionflags=0, extraglobs=None,
1740            raise_on_error=False, exclude_empty=False):
1741    """m=None, name=None, globs=None, verbose=None, isprivate=None,
1742       report=True, optionflags=0, extraglobs=None, raise_on_error=False,
1743       exclude_empty=False
1744
1745    Test examples in docstrings in functions and classes reachable
1746    from module m (or the current module if m is not supplied), starting
1747    with m.__doc__.  Unless isprivate is specified, private names
1748    are not skipped.
1749
1750    Also test examples reachable from dict m.__test__ if it exists and is
1751    not None.  m.__test__ maps names to functions, classes and strings;
1752    function and class docstrings are tested even if the name is private;
1753    strings are tested directly, as if they were docstrings.
1754
1755    Return (#failures, #tests).
1756
1757    See doctest.__doc__ for an overview.
1758
1759    Optional keyword arg "name" gives the name of the module; by default
1760    use m.__name__.
1761
1762    Optional keyword arg "globs" gives a dict to be used as the globals
1763    when executing examples; by default, use m.__dict__.  A copy of this
1764    dict is actually used for each docstring, so that each docstring's
1765    examples start with a clean slate.
1766
1767    Optional keyword arg "extraglobs" gives a dictionary that should be
1768    merged into the globals that are used to execute examples.  By
1769    default, no extra globals are used.  This is new in 2.4.
1770
1771    Optional keyword arg "verbose" prints lots of stuff if true, prints
1772    only failures if false; by default, it's true iff "-v" is in sys.argv.
1773
1774    Optional keyword arg "report" prints a summary at the end when true,
1775    else prints nothing at the end.  In verbose mode, the summary is
1776    detailed, else very brief (in fact, empty if all tests passed).
1777
1778    Optional keyword arg "optionflags" or's together module constants,
1779    and defaults to 0.  This is new in 2.3.  Possible values (see the
1780    docs for details):
1781
1782        DONT_ACCEPT_TRUE_FOR_1
1783        DONT_ACCEPT_BLANKLINE
1784        NORMALIZE_WHITESPACE
1785        ELLIPSIS
1786        IGNORE_EXCEPTION_DETAIL
1787        REPORT_UDIFF
1788        REPORT_CDIFF
1789        REPORT_NDIFF
1790        REPORT_ONLY_FIRST_FAILURE
1791
1792    Optional keyword arg "raise_on_error" raises an exception on the
1793    first unexpected exception or failure. This allows failures to be
1794    post-mortem debugged.
1795
1796    Deprecated in Python 2.4:
1797    Optional keyword arg "isprivate" specifies a function used to
1798    determine whether a name is private.  The default function is
1799    treat all functions as public.  Optionally, "isprivate" can be
1800    set to doctest.is_private to skip over functions marked as private
1801    using the underscore naming convention; see its docs for details.
1802
1803    Advanced tomfoolery:  testmod runs methods of a local instance of
1804    class doctest.Tester, then merges the results into (or creates)
1805    global Tester instance doctest.master.  Methods of doctest.master
1806    can be called directly too, if you want to do something unusual.
1807    Passing report=0 to testmod is especially useful then, to delay
1808    displaying a summary.  Invoke doctest.master.summarize(verbose)
1809    when you're done fiddling.
1810    """
1811    global master
1812
1813    if isprivate is not None:
1814        warnings.warn("the isprivate argument is deprecated; "
1815                      "examine DocTestFinder.find() lists instead",
1816                      DeprecationWarning)
1817
1818    # If no module was given, then use __main__.
1819    if m is None:
1820        # DWA - m will still be None if this wasn't invoked from the command
1821        # line, in which case the following TypeError is about as good an error
1822        # as we should expect
1823        m = sys.modules.get('__main__')
1824
1825    # Check that we were actually given a module.
1826    if not inspect.ismodule(m):
1827        raise TypeError("testmod: module required; %r" % (m,))
1828
1829    # If no name was given, then use the module's name.
1830    if name is None:
1831        name = m.__name__
1832
1833    # Find, parse, and run all tests in the given module.
1834    finder = DocTestFinder(_namefilter=isprivate, exclude_empty=exclude_empty)
1835
1836    if raise_on_error:
1837        runner = DebugRunner(verbose=verbose, optionflags=optionflags)
1838    else:
1839        runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1840
1841    for test in finder.find(m, name, globs=globs, extraglobs=extraglobs):
1842        runner.run(test)
1843
1844    if report:
1845        runner.summarize()
1846
1847    if master is None:
1848        master = runner
1849    else:
1850        master.merge(runner)
1851
1852    return runner.failures, runner.tries
1853
1854def testfile(filename, module_relative=True, name=None, package=None,
1855             globs=None, verbose=None, report=True, optionflags=0,
1856             extraglobs=None, raise_on_error=False, parser=DocTestParser()):
1857    """
1858    Test examples in the given file.  Return (#failures, #tests).
1859
1860    Optional keyword arg "module_relative" specifies how filenames
1861    should be interpreted:
1862
1863      - If "module_relative" is True (the default), then "filename"
1864         specifies a module-relative path.  By default, this path is
1865         relative to the calling module's directory; but if the
1866         "package" argument is specified, then it is relative to that
1867         package.  To ensure os-independence, "filename" should use
1868         "/" characters to separate path segments, and should not
1869         be an absolute path (i.e., it may not begin with "/").
1870
1871      - If "module_relative" is False, then "filename" specifies an
1872        os-specific path.  The path may be absolute or relative (to
1873        the current working directory).
1874
1875    Optional keyword arg "name" gives the name of the test; by default
1876    use the file's basename.
1877
1878    Optional keyword argument "package" is a Python package or the
1879    name of a Python package whose directory should be used as the
1880    base directory for a module relative filename.  If no package is
1881    specified, then the calling module's directory is used as the base
1882    directory for module relative filenames.  It is an error to
1883    specify "package" if "module_relative" is False.
1884
1885    Optional keyword arg "globs" gives a dict to be used as the globals
1886    when executing examples; by default, use {}.  A copy of this dict
1887    is actually used for each docstring, so that each docstring's
1888    examples start with a clean slate.
1889
1890    Optional keyword arg "extraglobs" gives a dictionary that should be
1891    merged into the globals that are used to execute examples.  By
1892    default, no extra globals are used.
1893
1894    Optional keyword arg "verbose" prints lots of stuff if true, prints
1895    only failures if false; by default, it's true iff "-v" is in sys.argv.
1896
1897    Optional keyword arg "report" prints a summary at the end when true,
1898    else prints nothing at the end.  In verbose mode, the summary is
1899    detailed, else very brief (in fact, empty if all tests passed).
1900
1901    Optional keyword arg "optionflags" or's together module constants,
1902    and defaults to 0.  Possible values (see the docs for details):
1903
1904        DONT_ACCEPT_TRUE_FOR_1
1905        DONT_ACCEPT_BLANKLINE
1906        NORMALIZE_WHITESPACE
1907        ELLIPSIS
1908        IGNORE_EXCEPTION_DETAIL
1909        REPORT_UDIFF
1910        REPORT_CDIFF
1911        REPORT_NDIFF
1912        REPORT_ONLY_FIRST_FAILURE
1913
1914    Optional keyword arg "raise_on_error" raises an exception on the
1915    first unexpected exception or failure. This allows failures to be
1916    post-mortem debugged.
1917
1918    Optional keyword arg "parser" specifies a DocTestParser (or
1919    subclass) that should be used to extract tests from the files.
1920
1921    Advanced tomfoolery:  testmod runs methods of a local instance of
1922    class doctest.Tester, then merges the results into (or creates)
1923    global Tester instance doctest.master.  Methods of doctest.master
1924    can be called directly too, if you want to do something unusual.
1925    Passing report=0 to testmod is especially useful then, to delay
1926    displaying a summary.  Invoke doctest.master.summarize(verbose)
1927    when you're done fiddling.
1928    """
1929    global master
1930
1931    if package and not module_relative:
1932        raise ValueError("Package may only be specified for module-"
1933                         "relative paths.")
1934
1935    # Relativize the path
1936    if module_relative:
1937        package = _normalize_module(package)
1938        filename = _module_relative_path(package, filename)
1939
1940    # If no name was given, then use the file's name.
1941    if name is None:
1942        name = os.path.basename(filename)
1943
1944    # Assemble the globals.
1945    if globs is None:
1946        globs = {}
1947    else:
1948        globs = globs.copy()
1949    if extraglobs is not None:
1950        globs.update(extraglobs)
1951
1952    if raise_on_error:
1953        runner = DebugRunner(verbose=verbose, optionflags=optionflags)
1954    else:
1955        runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1956
1957    # Read the file, convert it to a test, and run it.
1958    s = open(filename).read()
1959    test = parser.get_doctest(s, globs, name, filename, 0)
1960    runner.run(test)
1961
1962    if report:
1963        runner.summarize()
1964
1965    if master is None:
1966        master = runner
1967    else:
1968        master.merge(runner)
1969
1970    return runner.failures, runner.tries
1971
1972def run_docstring_examples(f, globs, verbose=False, name="NoName",
1973                           compileflags=None, optionflags=0):
1974    """
1975    Test examples in the given object's docstring (`f`), using `globs`
1976    as globals.  Optional argument `name` is used in failure messages.
1977    If the optional argument `verbose` is true, then generate output
1978    even if there are no failures.
1979
1980    `compileflags` gives the set of flags that should be used by the
1981    Python compiler when running the examples.  If not specified, then
1982    it will default to the set of future-import flags that apply to
1983    `globs`.
1984
1985    Optional keyword arg `optionflags` specifies options for the
1986    testing and output.  See the documentation for `testmod` for more
1987    information.
1988    """
1989    # Find, parse, and run all tests in the given module.
1990    finder = DocTestFinder(verbose=verbose, recurse=False)
1991    runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1992    for test in finder.find(f, name, globs=globs):
1993        runner.run(test, compileflags=compileflags)
1994
1995######################################################################
1996## 7. Tester
1997######################################################################
1998# This is provided only for backwards compatibility.  It's not
1999# actually used in any way.
2000
2001class Tester:
2002    def __init__(self, mod=None, globs=None, verbose=None,
2003                 isprivate=None, optionflags=0):
2004
2005        warnings.warn("class Tester is deprecated; "
2006                      "use class doctest.DocTestRunner instead",
2007                      DeprecationWarning, stacklevel=2)
2008        if mod is None and globs is None:
2009            raise TypeError("Tester.__init__: must specify mod or globs")
2010        if mod is not None and not inspect.ismodule(mod):
2011            raise TypeError("Tester.__init__: mod must be a module; %r" %
2012                            (mod,))
2013        if globs is None:
2014            globs = mod.__dict__
2015        self.globs = globs
2016
2017        self.verbose = verbose
2018        self.isprivate = isprivate
2019        self.optionflags = optionflags
2020        self.testfinder = DocTestFinder(_namefilter=isprivate)
2021        self.testrunner = DocTestRunner(verbose=verbose,
2022                                        optionflags=optionflags)
2023
2024    def runstring(self, s, name):
2025        test = DocTestParser().get_doctest(s, self.globs, name, None, None)
2026        if self.verbose:
2027            print "Running string", name
2028        (f,t) = self.testrunner.run(test)
2029        if self.verbose:
2030            print f, "of", t, "examples failed in string", name
2031        return (f,t)
2032
2033    def rundoc(self, object, name=None, module=None):
2034        f = t = 0
2035        tests = self.testfinder.find(object, name, module=module,
2036                                     globs=self.globs)
2037        for test in tests:
2038            (f2, t2) = self.testrunner.run(test)
2039            (f,t) = (f+f2, t+t2)
2040        return (f,t)
2041
2042    def rundict(self, d, name, module=None):
2043        import new
2044        m = new.module(name)
2045        m.__dict__.update(d)
2046        if module is None:
2047            module = False
2048        return self.rundoc(m, name, module)
2049
2050    def run__test__(self, d, name):
2051        import new
2052        m = new.module(name)
2053        m.__test__ = d
2054        return self.rundoc(m, name)
2055
2056    def summarize(self, verbose=None):
2057        return self.testrunner.summarize(verbose)
2058
2059    def merge(self, other):
2060        self.testrunner.merge(other.testrunner)
2061
2062######################################################################
2063## 8. Unittest Support
2064######################################################################
2065
2066_unittest_reportflags = 0
2067
2068def set_unittest_reportflags(flags):
2069    """Sets the unittest option flags.
2070
2071    The old flag is returned so that a runner could restore the old
2072    value if it wished to:
2073
2074      >>> old = _unittest_reportflags
2075      >>> set_unittest_reportflags(REPORT_NDIFF |
2076      ...                          REPORT_ONLY_FIRST_FAILURE) == old
2077      True
2078
2079      >>> import doctest
2080      >>> doctest._unittest_reportflags == (REPORT_NDIFF |
2081      ...                                   REPORT_ONLY_FIRST_FAILURE)
2082      True
2083
2084    Only reporting flags can be set:
2085
2086      >>> set_unittest_reportflags(ELLIPSIS)
2087      Traceback (most recent call last):
2088      ...
2089      ValueError: ('Only reporting flags allowed', 8)
2090
2091      >>> set_unittest_reportflags(old) == (REPORT_NDIFF |
2092      ...                                   REPORT_ONLY_FIRST_FAILURE)
2093      True
2094    """
2095    global _unittest_reportflags
2096
2097    if (flags & REPORTING_FLAGS) != flags:
2098        raise ValueError("Only reporting flags allowed", flags)
2099    old = _unittest_reportflags
2100    _unittest_reportflags = flags
2101    return old
2102
2103
2104class DocTestCase(unittest.TestCase):
2105
2106    def __init__(self, test, optionflags=0, setUp=None, tearDown=None,
2107                 checker=None):
2108
2109        unittest.TestCase.__init__(self)
2110        self._dt_optionflags = optionflags
2111        self._dt_checker = checker
2112        self._dt_test = test
2113        self._dt_setUp = setUp
2114        self._dt_tearDown = tearDown
2115
2116    def setUp(self):
2117        test = self._dt_test
2118
2119        if self._dt_setUp is not None:
2120            self._dt_setUp(test)
2121
2122    def tearDown(self):
2123        test = self._dt_test
2124
2125        if self._dt_tearDown is not None:
2126            self._dt_tearDown(test)
2127
2128        test.globs.clear()
2129
2130    def runTest(self):
2131        test = self._dt_test
2132        old = sys.stdout
2133        new = StringIO()
2134        optionflags = self._dt_optionflags
2135
2136        if not (optionflags & REPORTING_FLAGS):
2137            # The option flags don't include any reporting flags,
2138            # so add the default reporting flags
2139            optionflags |= _unittest_reportflags
2140
2141        runner = DocTestRunner(optionflags=optionflags,
2142                               checker=self._dt_checker, verbose=False)
2143
2144        try:
2145            runner.DIVIDER = "-"*70
2146            failures, tries = runner.run(
2147                test, out=new.write, clear_globs=False)
2148        finally:
2149            sys.stdout = old
2150
2151        if failures:
2152            raise self.failureException(self.format_failure(new.getvalue()))
2153
2154    def format_failure(self, err):
2155        test = self._dt_test
2156        if test.lineno is None:
2157            lineno = 'unknown line number'
2158        else:
2159            lineno = '%s' % test.lineno
2160        lname = '.'.join(test.name.split('.')[-1:])
2161        return ('Failed doctest test for %s\n'
2162                '  File "%s", line %s, in %s\n\n%s'
2163                % (test.name, test.filename, lineno, lname, err)
2164                )
2165
2166    def debug(self):
2167        r"""Run the test case without results and without catching exceptions
2168
2169           The unit test framework includes a debug method on test cases
2170           and test suites to support post-mortem debugging.  The test code
2171           is run in such a way that errors are not caught.  This way a
2172           caller can catch the errors and initiate post-mortem debugging.
2173
2174           The DocTestCase provides a debug method that raises
2175           UnexpectedException errors if there is an unexepcted
2176           exception:
2177
2178             >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
2179             ...                {}, 'foo', 'foo.py', 0)
2180             >>> case = DocTestCase(test)
2181             >>> try:
2182             ...     case.debug()
2183             ... except UnexpectedException, failure:
2184             ...     pass
2185
2186           The UnexpectedException contains the test, the example, and
2187           the original exception:
2188
2189             >>> failure.test is test
2190             True
2191
2192             >>> failure.example.want
2193             '42\n'
2194
2195             >>> exc_info = failure.exc_info
2196             >>> raise exc_info[0], exc_info[1], exc_info[2]
2197             Traceback (most recent call last):
2198             ...
2199             KeyError
2200
2201           If the output doesn't match, then a DocTestFailure is raised:
2202
2203             >>> test = DocTestParser().get_doctest('''
2204             ...      >>> x = 1
2205             ...      >>> x
2206             ...      2
2207             ...      ''', {}, 'foo', 'foo.py', 0)
2208             >>> case = DocTestCase(test)
2209
2210             >>> try:
2211             ...    case.debug()
2212             ... except DocTestFailure, failure:
2213             ...    pass
2214
2215           DocTestFailure objects provide access to the test:
2216
2217             >>> failure.test is test
2218             True
2219
2220           As well as to the example:
2221
2222             >>> failure.example.want
2223             '2\n'
2224
2225           and the actual output:
2226
2227             >>> failure.got
2228             '1\n'
2229
2230           """
2231
2232        self.setUp()
2233        runner = DebugRunner(optionflags=self._dt_optionflags,
2234                             checker=self._dt_checker, verbose=False)
2235        runner.run(self._dt_test)
2236        self.tearDown()
2237
2238    def id(self):
2239        return self._dt_test.name
2240
2241    def __repr__(self):
2242        name = self._dt_test.name.split('.')
2243        return "%s (%s)" % (name[-1], '.'.join(name[:-1]))
2244
2245    __str__ = __repr__
2246
2247    def shortDescription(self):
2248        return "Doctest: " + self._dt_test.name
2249
2250def DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None,
2251                 **options):
2252    """
2253    Convert doctest tests for a module to a unittest test suite.
2254
2255    This converts each documentation string in a module that
2256    contains doctest tests to a unittest test case.  If any of the
2257    tests in a doc string fail, then the test case fails.  An exception
2258    is raised showing the name of the file containing the test and a
2259    (sometimes approximate) line number.
2260
2261    The `module` argument provides the module to be tested.  The argument
2262    can be either a module or a module name.
2263
2264    If no argument is given, the calling module is used.
2265
2266    A number of options may be provided as keyword arguments:
2267
2268    setUp
2269      A set-up function.  This is called before running the
2270      tests in each file. The setUp function will be passed a DocTest
2271      object.  The setUp function can access the test globals as the
2272      globs attribute of the test passed.
2273
2274    tearDown
2275      A tear-down function.  This is called after running the
2276      tests in each file.  The tearDown function will be passed a DocTest
2277      object.  The tearDown function can access the test globals as the
2278      globs attribute of the test passed.
2279
2280    globs
2281      A dictionary containing initial global variables for the tests.
2282
2283    optionflags
2284       A set of doctest option flags expressed as an integer.
2285    """
2286
2287    if test_finder is None:
2288        test_finder = DocTestFinder()
2289
2290    module = _normalize_module(module)
2291    tests = test_finder.find(module, globs=globs, extraglobs=extraglobs)
2292    if globs is None:
2293        globs = module.__dict__
2294    if not tests:
2295        # Why do we want to do this? Because it reveals a bug that might
2296        # otherwise be hidden.
2297        raise ValueError(module, "has no tests")
2298
2299    tests.sort()
2300    suite = unittest.TestSuite()
2301    for test in tests:
2302        if len(test.examples) == 0:
2303            continue
2304        if not test.filename:
2305            filename = module.__file__
2306            if filename[-4:] in (".pyc", ".pyo"):
2307                filename = filename[:-1]
2308            test.filename = filename
2309        suite.addTest(DocTestCase(test, **options))
2310
2311    return suite
2312
2313class DocFileCase(DocTestCase):
2314
2315    def id(self):
2316        return '_'.join(self._dt_test.name.split('.'))
2317
2318    def __repr__(self):
2319        return self._dt_test.filename
2320    __str__ = __repr__
2321
2322    def format_failure(self, err):
2323        return ('Failed doctest test for %s\n  File "%s", line 0\n\n%s'
2324                % (self._dt_test.name, self._dt_test.filename, err)
2325                )
2326
2327def DocFileTest(path, module_relative=True, package=None,
2328                globs=None, parser=DocTestParser(), **options):
2329    if globs is None:
2330        globs = {}
2331
2332    if package and not module_relative:
2333        raise ValueError("Package may only be specified for module-"
2334                         "relative paths.")
2335
2336    # Relativize the path.
2337    if module_relative:
2338        package = _normalize_module(package)
2339        path = _module_relative_path(package, path)
2340
2341    # Find the file and read it.
2342    name = os.path.basename(path)
2343    doc = open(path).read()
2344
2345    # Convert it to a test, and wrap it in a DocFileCase.
2346    test = parser.get_doctest(doc, globs, name, path, 0)
2347    return DocFileCase(test, **options)
2348
2349def DocFileSuite(*paths, **kw):
2350    """A unittest suite for one or more doctest files.
2351
2352    The path to each doctest file is given as a string; the
2353    interpretation of that string depends on the keyword argument
2354    "module_relative".
2355
2356    A number of options may be provided as keyword arguments:
2357
2358    module_relative
2359      If "module_relative" is True, then the given file paths are
2360      interpreted as os-independent module-relative paths.  By
2361      default, these paths are relative to the calling module's
2362      directory; but if the "package" argument is specified, then
2363      they are relative to that package.  To ensure os-independence,
2364      "filename" should use "/" characters to separate path
2365      segments, and may not be an absolute path (i.e., it may not
2366      begin with "/").
2367
2368      If "module_relative" is False, then the given file paths are
2369      interpreted as os-specific paths.  These paths may be absolute
2370      or relative (to the current working directory).
2371
2372    package
2373      A Python package or the name of a Python package whose directory
2374      should be used as the base directory for module relative paths.
2375      If "package" is not specified, then the calling module's
2376      directory is used as the base directory for module relative
2377      filenames.  It is an error to specify "package" if
2378      "module_relative" is False.
2379
2380    setUp
2381      A set-up function.  This is called before running the
2382      tests in each file. The setUp function will be passed a DocTest
2383      object.  The setUp function can access the test globals as the
2384      globs attribute of the test passed.
2385
2386    tearDown
2387      A tear-down function.  This is called after running the
2388      tests in each file.  The tearDown function will be passed a DocTest
2389      object.  The tearDown function can access the test globals as the
2390      globs attribute of the test passed.
2391
2392    globs
2393      A dictionary containing initial global variables for the tests.
2394
2395    optionflags
2396      A set of doctest option flags expressed as an integer.
2397
2398    parser
2399      A DocTestParser (or subclass) that should be used to extract
2400      tests from the files.
2401    """
2402    suite = unittest.TestSuite()
2403
2404    # We do this here so that _normalize_module is called at the right
2405    # level.  If it were called in DocFileTest, then this function
2406    # would be the caller and we might guess the package incorrectly.
2407    if kw.get('module_relative', True):
2408        kw['package'] = _normalize_module(kw.get('package'))
2409
2410    for path in paths:
2411        suite.addTest(DocFileTest(path, **kw))
2412
2413    return suite
2414
2415######################################################################
2416## 9. Debugging Support
2417######################################################################
2418
2419def script_from_examples(s):
2420    r"""Extract script from text with examples.
2421
2422       Converts text with examples to a Python script.  Example input is
2423       converted to regular code.  Example output and all other words
2424       are converted to comments:
2425
2426       >>> text = '''
2427       ...       Here are examples of simple math.
2428       ...
2429       ...           Python has super accurate integer addition
2430       ...
2431       ...           >>> 2 + 2
2432       ...           5
2433       ...
2434       ...           And very friendly error messages:
2435       ...
2436       ...           >>> 1/0
2437       ...           To Infinity
2438       ...           And
2439       ...           Beyond
2440       ...
2441       ...           You can use logic if you want:
2442       ...
2443       ...           >>> if 0:
2444       ...           ...    blah
2445       ...           ...    blah
2446       ...           ...
2447       ...
2448       ...           Ho hum
2449       ...           '''
2450
2451       >>> print script_from_examples(text)
2452       # Here are examples of simple math.
2453       #
2454       #     Python has super accurate integer addition
2455       #
2456       2 + 2
2457       # Expected:
2458       ## 5
2459       #
2460       #     And very friendly error messages:
2461       #
2462       1/0
2463       # Expected:
2464       ## To Infinity
2465       ## And
2466       ## Beyond
2467       #
2468       #     You can use logic if you want:
2469       #
2470       if 0:
2471          blah
2472          blah
2473       #
2474       #     Ho hum
2475       """
2476    output = []
2477    for piece in DocTestParser().parse(s):
2478        if isinstance(piece, Example):
2479            # Add the example's source code (strip trailing NL)
2480            output.append(piece.source[:-1])
2481            # Add the expected output:
2482            want = piece.want
2483            if want:
2484                output.append('# Expected:')
2485                output += ['## '+l for l in want.split('\n')[:-1]]
2486        else:
2487            # Add non-example text.
2488            output += [_comment_line(l)
2489                       for l in piece.split('\n')[:-1]]
2490
2491    # Trim junk on both ends.
2492    while output and output[-1] == '#':
2493        output.pop()
2494    while output and output[0] == '#':
2495        output.pop(0)
2496    # Combine the output, and return it.
2497    return '\n'.join(output)
2498
2499def testsource(module, name):
2500    """Extract the test sources from a doctest docstring as a script.
2501
2502    Provide the module (or dotted name of the module) containing the
2503    test to be debugged and the name (within the module) of the object
2504    with the doc string with tests to be debugged.
2505    """
2506    module = _normalize_module(module)
2507    tests = DocTestFinder().find(module)
2508    test = [t for t in tests if t.name == name]
2509    if not test:
2510        raise ValueError(name, "not found in tests")
2511    test = test[0]
2512    testsrc = script_from_examples(test.docstring)
2513    return testsrc
2514
2515def debug_src(src, pm=False, globs=None):
2516    """Debug a single doctest docstring, in argument `src`'"""
2517    testsrc = script_from_examples(src)
2518    debug_script(testsrc, pm, globs)
2519
2520def debug_script(src, pm=False, globs=None):
2521    "Debug a test script.  `src` is the script, as a string."
2522    import pdb
2523
2524    # Note that tempfile.NameTemporaryFile() cannot be used.  As the
2525    # docs say, a file so created cannot be opened by name a second time
2526    # on modern Windows boxes, and execfile() needs to open it.
2527    srcfilename = tempfile.mktemp(".py", "doctestdebug")
2528    f = open(srcfilename, 'w')
2529    f.write(src)
2530    f.close()
2531
2532    try:
2533        if globs:
2534            globs = globs.copy()
2535        else:
2536            globs = {}
2537
2538        if pm:
2539            try:
2540                execfile(srcfilename, globs, globs)
2541            except:
2542                print sys.exc_info()[1]
2543                pdb.post_mortem(sys.exc_info()[2])
2544        else:
2545            # Note that %r is vital here.  '%s' instead can, e.g., cause
2546            # backslashes to get treated as metacharacters on Windows.
2547            pdb.run("execfile(%r)" % srcfilename, globs, globs)
2548
2549    finally:
2550        os.remove(srcfilename)
2551
2552def debug(module, name, pm=False):
2553    """Debug a single doctest docstring.
2554
2555    Provide the module (or dotted name of the module) containing the
2556    test to be debugged and the name (within the module) of the object
2557    with the docstring with tests to be debugged.
2558    """
2559    module = _normalize_module(module)
2560    testsrc = testsource(module, name)
2561    debug_script(testsrc, pm, module.__dict__)
2562
2563######################################################################
2564## 10. Example Usage
2565######################################################################
2566class _TestClass:
2567    """
2568    A pointless class, for sanity-checking of docstring testing.
2569
2570    Methods:
2571        square()
2572        get()
2573
2574    >>> _TestClass(13).get() + _TestClass(-12).get()
2575    1
2576    >>> hex(_TestClass(13).square().get())
2577    '0xa9'
2578    """
2579
2580    def __init__(self, val):
2581        """val -> _TestClass object with associated value val.
2582
2583        >>> t = _TestClass(123)
2584        >>> print t.get()
2585        123
2586        """
2587
2588        self.val = val
2589
2590    def square(self):
2591        """square() -> square TestClass's associated value
2592
2593        >>> _TestClass(13).square().get()
2594        169
2595        """
2596
2597        self.val = self.val ** 2
2598        return self
2599
2600    def get(self):
2601        """get() -> return TestClass's associated value.
2602
2603        >>> x = _TestClass(-42)
2604        >>> print x.get()
2605        -42
2606        """
2607
2608        return self.val
2609
2610__test__ = {"_TestClass": _TestClass,
2611            "string": r"""
2612                      Example of a string object, searched as-is.
2613                      >>> x = 1; y = 2
2614                      >>> x + y, x * y
2615                      (3, 2)
2616                      """,
2617
2618            "bool-int equivalence": r"""
2619                                    In 2.2, boolean expressions displayed
2620                                    0 or 1.  By default, we still accept
2621                                    them.  This can be disabled by passing
2622                                    DONT_ACCEPT_TRUE_FOR_1 to the new
2623                                    optionflags argument.
2624                                    >>> 4 == 4
2625                                    1
2626                                    >>> 4 == 4
2627                                    True
2628                                    >>> 4 > 4
2629                                    0
2630                                    >>> 4 > 4
2631                                    False
2632                                    """,
2633
2634            "blank lines": r"""
2635                Blank lines can be marked with <BLANKLINE>:
2636                    >>> print 'foo\n\nbar\n'
2637                    foo
2638                    <BLANKLINE>
2639                    bar
2640                    <BLANKLINE>
2641            """,
2642
2643            "ellipsis": r"""
2644                If the ellipsis flag is used, then '...' can be used to
2645                elide substrings in the desired output:
2646                    >>> print range(1000) #doctest: +ELLIPSIS
2647                    [0, 1, 2, ..., 999]
2648            """,
2649
2650            "whitespace normalization": r"""
2651                If the whitespace normalization flag is used, then
2652                differences in whitespace are ignored.
2653                    >>> print range(30) #doctest: +NORMALIZE_WHITESPACE
2654                    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
2655                     15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,
2656                     27, 28, 29]
2657            """,
2658           }
2659
2660def _test():
2661    r = unittest.TextTestRunner()
2662    r.run(DocTestSuite())
2663
2664if __name__ == "__main__":
2665    _test()
Note: リポジトリブラウザについてのヘルプは TracBrowser を参照してください。