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