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