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