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)
1128            try:
1129                obj = obj.__code__
1130            except AttributeError:
1131                # Functions implemented in C don't necessarily
1132                # have a __code__ attribute.
1133                # If there's no code, there's no lineno
1134                return None
1135        if inspect.istraceback(obj): obj = obj.tb_frame
1136        if inspect.isframe(obj): obj = obj.f_code
1137        if inspect.iscode(obj):
1138            lineno = obj.co_firstlineno - 1
1139
1140        # Find the line number where the docstring starts.  Assume
1141        # that it's the first line that begins with a quote mark.
1142        # Note: this could be fooled by a multiline function
1143        # signature, where a continuation line begins with a quote
1144        # mark.
1145        if lineno is not None:
1146            if source_lines is None:
1147                return lineno+1
1148            pat = re.compile(r'(^|.*:)\s*\w*("|\')')
1149            for lineno in range(lineno, len(source_lines)):
1150                if pat.match(source_lines[lineno]):
1151                    return lineno
1152
1153        # We couldn't find the line number.
1154        return None
1155
1156######################################################################
1157## 5. DocTest Runner
1158######################################################################
1159
1160class DocTestRunner:
1161    """
1162    A class used to run DocTest test cases, and accumulate statistics.
1163    The `run` method is used to process a single DocTest case.  It
1164    returns a tuple `(f, t)`, where `t` is the number of test cases
1165    tried, and `f` is the number of test cases that failed.
1166
1167        >>> tests = DocTestFinder().find(_TestClass)
1168        >>> runner = DocTestRunner(verbose=False)
1169        >>> tests.sort(key = lambda test: test.name)
1170        >>> for test in tests:
1171        ...     print(test.name, '->', runner.run(test))
1172        _TestClass -> TestResults(failed=0, attempted=2)
1173        _TestClass.__init__ -> TestResults(failed=0, attempted=2)
1174        _TestClass.get -> TestResults(failed=0, attempted=2)
1175        _TestClass.square -> TestResults(failed=0, attempted=1)
1176
1177    The `summarize` method prints a summary of all the test cases that
1178    have been run by the runner, and returns an aggregated `(f, t)`
1179    tuple:
1180
1181        >>> runner.summarize(verbose=1)
1182        4 items passed all tests:
1183           2 tests in _TestClass
1184           2 tests in _TestClass.__init__
1185           2 tests in _TestClass.get
1186           1 tests in _TestClass.square
1187        7 tests in 4 items.
1188        7 passed and 0 failed.
1189        Test passed.
1190        TestResults(failed=0, attempted=7)
1191
1192    The aggregated number of tried examples and failed examples is
1193    also available via the `tries` and `failures` attributes:
1194
1195        >>> runner.tries
1196        7
1197        >>> runner.failures
1198        0
1199
1200    The comparison between expected outputs and actual outputs is done
1201    by an `OutputChecker`.  This comparison may be customized with a
1202    number of option flags; see the documentation for `testmod` for
1203    more information.  If the option flags are insufficient, then the
1204    comparison may also be customized by passing a subclass of
1205    `OutputChecker` to the constructor.
1206
1207    The test runner's display output can be controlled in two ways.
1208    First, an output function (`out) can be passed to
1209    `TestRunner.run`; this function will be called with strings that
1210    should be displayed.  It defaults to `sys.stdout.write`.  If
1211    capturing the output is not sufficient, then the display output
1212    can be also customized by subclassing DocTestRunner, and
1213    overriding the methods `report_start`, `report_success`,
1214    `report_unexpected_exception`, and `report_failure`.
1215    """
1216    # This divider string is used to separate failure messages, and to
1217    # separate sections of the summary.
1218    DIVIDER = "*" * 70
1219
1220    def __init__(self, checker=None, verbose=None, optionflags=0):
1221        """
1222        Create a new test runner.
1223
1224        Optional keyword arg `checker` is the `OutputChecker` that
1225        should be used to compare the expected outputs and actual
1226        outputs of doctest examples.
1227
1228        Optional keyword arg 'verbose' prints lots of stuff if true,
1229        only failures if false; by default, it's true iff '-v' is in
1230        sys.argv.
1231
1232        Optional argument `optionflags` can be used to control how the
1233        test runner compares expected output to actual output, and how
1234        it displays failures.  See the documentation for `testmod` for
1235        more information.
1236        """
1237        self._checker = checker or OutputChecker()
1238        if verbose is None:
1239            verbose = '-v' in sys.argv
1240        self._verbose = verbose
1241        self.optionflags = optionflags
1242        self.original_optionflags = optionflags
1243
1244        # Keep track of the examples we've run.
1245        self.tries = 0
1246        self.failures = 0
1247        self._name2ft = {}
1248
1249        # Create a fake output target for capturing doctest output.
1250        self._fakeout = _SpoofOut()
1251
1252    #/////////////////////////////////////////////////////////////////
1253    # Reporting methods
1254    #/////////////////////////////////////////////////////////////////
1255
1256    def report_start(self, out, test, example):
1257        """
1258        Report that the test runner is about to process the given
1259        example.  (Only displays a message if verbose=True)
1260        """
1261        if self._verbose:
1262            if example.want:
1263                out('Trying:\n' + _indent(example.source) +
1264                    'Expecting:\n' + _indent(example.want))
1265            else:
1266                out('Trying:\n' + _indent(example.source) +
1267                    'Expecting nothing\n')
1268
1269    def report_success(self, out, test, example, got):
1270        """
1271        Report that the given example ran successfully.  (Only
1272        displays a message if verbose=True)
1273        """
1274        if self._verbose:
1275            out("ok\n")
1276
1277    def report_failure(self, out, test, example, got):
1278        """
1279        Report that the given example failed.
1280        """
1281        out(self._failure_header(test, example) +
1282            self._checker.output_difference(example, got, self.optionflags))
1283
1284    def report_unexpected_exception(self, out, test, example, exc_info):
1285        """
1286        Report that the given example raised an unexpected exception.
1287        """
1288        out(self._failure_header(test, example) +
1289            'Exception raised:\n' + _indent(_exception_traceback(exc_info)))
1290
1291    def _failure_header(self, test, example):
1292        out = [self.DIVIDER]
1293        if test.filename:
1294            if test.lineno is not None and example.lineno is not None:
1295                lineno = test.lineno + example.lineno + 1
1296            else:
1297                lineno = '?'
1298            out.append('File "%s", line %s, in %s' %
1299                       (test.filename, lineno, test.name))
1300        else:
1301            out.append('Line %s, in %s' % (example.lineno+1, test.name))
1302        out.append('Failed example:')
1303        source = example.source
1304        out.append(_indent(source))
1305        return '\n'.join(out)
1306
1307    #/////////////////////////////////////////////////////////////////
1308    # DocTest Running
1309    #/////////////////////////////////////////////////////////////////
1310
1311    def __run(self, test, compileflags, out):
1312        """
1313        Run the examples in `test`.  Write the outcome of each example
1314        with one of the `DocTestRunner.report_*` methods, using the
1315        writer function `out`.  `compileflags` is the set of compiler
1316        flags that should be used to execute examples.  Return a tuple
1317        `(f, t)`, where `t` is the number of examples tried, and `f`
1318        is the number of examples that failed.  The examples are run
1319        in the namespace `test.globs`.
1320        """
1321        # Keep track of the number of failures and tries.
1322        failures = tries = 0
1323
1324        # Save the option flags (since option directives can be used
1325        # to modify them).
1326        original_optionflags = self.optionflags
1327
1328        SUCCESS, FAILURE, BOOM = range(3) # `outcome` state
1329
1330        check = self._checker.check_output
1331
1332        # Process each example.
1333        for examplenum, example in enumerate(test.examples):
1334
1335            # If REPORT_ONLY_FIRST_FAILURE is set, then suppress
1336            # reporting after the first failure.
1337            quiet = (self.optionflags & REPORT_ONLY_FIRST_FAILURE and
1338                     failures > 0)
1339
1340            # Merge in the example's options.
1341            self.optionflags = original_optionflags
1342            if example.options:
1343                for (optionflag, val) in example.options.items():
1344                    if val:
1345                        self.optionflags |= optionflag
1346                    else:
1347                        self.optionflags &= ~optionflag
1348
1349            # If 'SKIP' is set, then skip this example.
1350            if self.optionflags & SKIP:
1351                continue
1352
1353            # Record that we started this example.
1354            tries += 1
1355            if not quiet:
1356                self.report_start(out, test, example)
1357
1358            # Use a special filename for compile(), so we can retrieve
1359            # the source code during interactive debugging (see
1360            # __patched_linecache_getlines).
1361            filename = '<doctest %s[%d]>' % (test.name, examplenum)
1362
1363            # Run the example in the given context (globs), and record
1364            # any exception that gets raised.  (But don't intercept
1365            # keyboard interrupts.)
1366            try:
1367                # Don't blink!  This is where the user's code gets run.
1368                exec(compile(example.source, filename, "single",
1369                             compileflags, True), test.globs)
1370                self.debugger.set_continue() # ==== Example Finished ====
1371                exception = None
1372            except KeyboardInterrupt:
1373                raise
1374            except:
1375                exception = sys.exc_info()
1376                self.debugger.set_continue() # ==== Example Finished ====
1377
1378            got = self._fakeout.getvalue()  # the actual output
1379            self._fakeout.truncate(0)
1380            outcome = FAILURE   # guilty until proved innocent or insane
1381
1382            # If the example executed without raising any exceptions,
1383            # verify its output.
1384            if exception is None:
1385                if check(example.want, got, self.optionflags):
1386                    outcome = SUCCESS
1387
1388            # The example raised an exception:  check if it was expected.
1389            else:
1390                formatted_ex = traceback.format_exception_only(*exception[:2])
1391                if issubclass(exception[0], SyntaxError):
1392                    # SyntaxError / IndentationError is special:
1393                    # we don't care about the carets / suggestions / etc
1394                    # We only care about the error message and notes.
1395                    # They start with `SyntaxError:` (or any other class name)
1396                    exception_line_prefixes = (
1397                        f"{exception[0].__qualname__}:",
1398                        f"{exception[0].__module__}.{exception[0].__qualname__}:",
1399                    )
1400                    exc_msg_index = next(
1401                        index
1402                        for index, line in enumerate(formatted_ex)
1403                        if line.startswith(exception_line_prefixes)
1404                    )
1405                    formatted_ex = formatted_ex[exc_msg_index:]
1406
1407                exc_msg = "".join(formatted_ex)
1408                if not quiet:
1409                    got += _exception_traceback(exception)
1410
1411                # If `example.exc_msg` is None, then we weren't expecting
1412                # an exception.
1413                if example.exc_msg is None:
1414                    outcome = BOOM
1415
1416                # We expected an exception:  see whether it matches.
1417                elif check(example.exc_msg, exc_msg, self.optionflags):
1418                    outcome = SUCCESS
1419
1420                # Another chance if they didn't care about the detail.
1421                elif self.optionflags & IGNORE_EXCEPTION_DETAIL:
1422                    if check(_strip_exception_details(example.exc_msg),
1423                             _strip_exception_details(exc_msg),
1424                             self.optionflags):
1425                        outcome = SUCCESS
1426
1427            # Report the outcome.
1428            if outcome is SUCCESS:
1429                if not quiet:
1430                    self.report_success(out, test, example, got)
1431            elif outcome is FAILURE:
1432                if not quiet:
1433                    self.report_failure(out, test, example, got)
1434                failures += 1
1435            elif outcome is BOOM:
1436                if not quiet:
1437                    self.report_unexpected_exception(out, test, example,
1438                                                     exception)
1439                failures += 1
1440            else:
1441                assert False, ("unknown outcome", outcome)
1442
1443            if failures and self.optionflags & FAIL_FAST:
1444                break
1445
1446        # Restore the option flags (in case they were modified)
1447        self.optionflags = original_optionflags
1448
1449        # Record and return the number of failures and tries.
1450        self.__record_outcome(test, failures, tries)
1451        return TestResults(failures, tries)
1452
1453    def __record_outcome(self, test, f, t):
1454        """
1455        Record the fact that the given DocTest (`test`) generated `f`
1456        failures out of `t` tried examples.
1457        """
1458        f2, t2 = self._name2ft.get(test.name, (0,0))
1459        self._name2ft[test.name] = (f+f2, t+t2)
1460        self.failures += f
1461        self.tries += t
1462
1463    __LINECACHE_FILENAME_RE = re.compile(r'<doctest '
1464                                         r'(?P<name>.+)'
1465                                         r'\[(?P<examplenum>\d+)\]>$')
1466    def __patched_linecache_getlines(self, filename, module_globals=None):
1467        m = self.__LINECACHE_FILENAME_RE.match(filename)
1468        if m and m.group('name') == self.test.name:
1469            example = self.test.examples[int(m.group('examplenum'))]
1470            return example.source.splitlines(keepends=True)
1471        else:
1472            return self.save_linecache_getlines(filename, module_globals)
1473
1474    def run(self, test, compileflags=None, out=None, clear_globs=True):
1475        """
1476        Run the examples in `test`, and display the results using the
1477        writer function `out`.
1478
1479        The examples are run in the namespace `test.globs`.  If
1480        `clear_globs` is true (the default), then this namespace will
1481        be cleared after the test runs, to help with garbage
1482        collection.  If you would like to examine the namespace after
1483        the test completes, then use `clear_globs=False`.
1484
1485        `compileflags` gives the set of flags that should be used by
1486        the Python compiler when running the examples.  If not
1487        specified, then it will default to the set of future-import
1488        flags that apply to `globs`.
1489
1490        The output of each example is checked using
1491        `DocTestRunner.check_output`, and the results are formatted by
1492        the `DocTestRunner.report_*` methods.
1493        """
1494        self.test = test
1495
1496        if compileflags is None:
1497            compileflags = _extract_future_flags(test.globs)
1498
1499        save_stdout = sys.stdout
1500        if out is None:
1501            encoding = save_stdout.encoding
1502            if encoding is None or encoding.lower() == 'utf-8':
1503                out = save_stdout.write
1504            else:
1505                # Use backslashreplace error handling on write
1506                def out(s):
1507                    s = str(s.encode(encoding, 'backslashreplace'), encoding)
1508                    save_stdout.write(s)
1509        sys.stdout = self._fakeout
1510
1511        # Patch pdb.set_trace to restore sys.stdout during interactive
1512        # debugging (so it's not still redirected to self._fakeout).
1513        # Note that the interactive output will go to *our*
1514        # save_stdout, even if that's not the real sys.stdout; this
1515        # allows us to write test cases for the set_trace behavior.
1516        save_trace = sys.gettrace()
1517        save_set_trace = pdb.set_trace
1518        self.debugger = _OutputRedirectingPdb(save_stdout)
1519        self.debugger.reset()
1520        pdb.set_trace = self.debugger.set_trace
1521
1522        # Patch linecache.getlines, so we can see the example's source
1523        # when we're inside the debugger.
1524        self.save_linecache_getlines = linecache.getlines
1525        linecache.getlines = self.__patched_linecache_getlines
1526
1527        # Make sure sys.displayhook just prints the value to stdout
1528        save_displayhook = sys.displayhook
1529        sys.displayhook = sys.__displayhook__
1530
1531        try:
1532            return self.__run(test, compileflags, out)
1533        finally:
1534            sys.stdout = save_stdout
1535            pdb.set_trace = save_set_trace
1536            sys.settrace(save_trace)
1537            linecache.getlines = self.save_linecache_getlines
1538            sys.displayhook = save_displayhook
1539            if clear_globs:
1540                test.globs.clear()
1541                import builtins
1542                builtins._ = None
1543
1544    #/////////////////////////////////////////////////////////////////
1545    # Summarization
1546    #/////////////////////////////////////////////////////////////////
1547    def summarize(self, verbose=None):
1548        """
1549        Print a summary of all the test cases that have been run by
1550        this DocTestRunner, and return a tuple `(f, t)`, where `f` is
1551        the total number of failed examples, and `t` is the total
1552        number of tried examples.
1553
1554        The optional `verbose` argument controls how detailed the
1555        summary is.  If the verbosity is not specified, then the
1556        DocTestRunner's verbosity is used.
1557        """
1558        if verbose is None:
1559            verbose = self._verbose
1560        notests = []
1561        passed = []
1562        failed = []
1563        totalt = totalf = 0
1564        for x in self._name2ft.items():
1565            name, (f, t) = x
1566            assert f <= t
1567            totalt += t
1568            totalf += f
1569            if t == 0:
1570                notests.append(name)
1571            elif f == 0:
1572                passed.append( (name, t) )
1573            else:
1574                failed.append(x)
1575        if verbose:
1576            if notests:
1577                print(len(notests), "items had no tests:")
1578                notests.sort()
1579                for thing in notests:
1580                    print("   ", thing)
1581            if passed:
1582                print(len(passed), "items passed all tests:")
1583                passed.sort()
1584                for thing, count in passed:
1585                    print(" %3d tests in %s" % (count, thing))
1586        if failed:
1587            print(self.DIVIDER)
1588            print(len(failed), "items had failures:")
1589            failed.sort()
1590            for thing, (f, t) in failed:
1591                print(" %3d of %3d in %s" % (f, t, thing))
1592        if verbose:
1593            print(totalt, "tests in", len(self._name2ft), "items.")
1594            print(totalt - totalf, "passed and", totalf, "failed.")
1595        if totalf:
1596            print("***Test Failed***", totalf, "failures.")
1597        elif verbose:
1598            print("Test passed.")
1599        return TestResults(totalf, totalt)
1600
1601    #/////////////////////////////////////////////////////////////////
1602    # Backward compatibility cruft to maintain doctest.master.
1603    #/////////////////////////////////////////////////////////////////
1604    def merge(self, other):
1605        d = self._name2ft
1606        for name, (f, t) in other._name2ft.items():
1607            if name in d:
1608                # Don't print here by default, since doing
1609                #     so breaks some of the buildbots
1610                #print("*** DocTestRunner.merge: '" + name + "' in both" \
1611                #    " testers; summing outcomes.")
1612                f2, t2 = d[name]
1613                f = f + f2
1614                t = t + t2
1615            d[name] = f, t
1616
1617class OutputChecker:
1618    """
1619    A class used to check the whether the actual output from a doctest
1620    example matches the expected output.  `OutputChecker` defines two
1621    methods: `check_output`, which compares a given pair of outputs,
1622    and returns true if they match; and `output_difference`, which
1623    returns a string describing the differences between two outputs.
1624    """
1625    def _toAscii(self, s):
1626        """
1627        Convert string to hex-escaped ASCII string.
1628        """
1629        return str(s.encode('ASCII', 'backslashreplace'), "ASCII")
1630
1631    def check_output(self, want, got, optionflags):
1632        """
1633        Return True iff the actual output from an example (`got`)
1634        matches the expected output (`want`).  These strings are
1635        always considered to match if they are identical; but
1636        depending on what option flags the test runner is using,
1637        several non-exact match types are also possible.  See the
1638        documentation for `TestRunner` for more information about
1639        option flags.
1640        """
1641
1642        # If `want` contains hex-escaped character such as "\u1234",
1643        # then `want` is a string of six characters(e.g. [\,u,1,2,3,4]).
1644        # On the other hand, `got` could be another sequence of
1645        # characters such as [\u1234], so `want` and `got` should
1646        # be folded to hex-escaped ASCII string to compare.
1647        got = self._toAscii(got)
1648        want = self._toAscii(want)
1649
1650        # Handle the common case first, for efficiency:
1651        # if they're string-identical, always return true.
1652        if got == want:
1653            return True
1654
1655        # The values True and False replaced 1 and 0 as the return
1656        # value for boolean comparisons in Python 2.3.
1657        if not (optionflags & DONT_ACCEPT_TRUE_FOR_1):
1658            if (got,want) == ("True\n", "1\n"):
1659                return True
1660            if (got,want) == ("False\n", "0\n"):
1661                return True
1662
1663        # <BLANKLINE> can be used as a special sequence to signify a
1664        # blank line, unless the DONT_ACCEPT_BLANKLINE flag is used.
1665        if not (optionflags & DONT_ACCEPT_BLANKLINE):
1666            # Replace <BLANKLINE> in want with a blank line.
1667            want = re.sub(r'(?m)^%s\s*?$' % re.escape(BLANKLINE_MARKER),
1668                          '', want)
1669            # If a line in got contains only spaces, then remove the
1670            # spaces.
1671            got = re.sub(r'(?m)^[^\S\n]+$', '', got)
1672            if got == want:
1673                return True
1674
1675        # This flag causes doctest to ignore any differences in the
1676        # contents of whitespace strings.  Note that this can be used
1677        # in conjunction with the ELLIPSIS flag.
1678        if optionflags & NORMALIZE_WHITESPACE:
1679            got = ' '.join(got.split())
1680            want = ' '.join(want.split())
1681            if got == want:
1682                return True
1683
1684        # The ELLIPSIS flag says to let the sequence "..." in `want`
1685        # match any substring in `got`.
1686        if optionflags & ELLIPSIS:
1687            if _ellipsis_match(want, got):
1688                return True
1689
1690        # We didn't find any match; return false.
1691        return False
1692
1693    # Should we do a fancy diff?
1694    def _do_a_fancy_diff(self, want, got, optionflags):
1695        # Not unless they asked for a fancy diff.
1696        if not optionflags & (REPORT_UDIFF |
1697                              REPORT_CDIFF |
1698                              REPORT_NDIFF):
1699            return False
1700
1701        # If expected output uses ellipsis, a meaningful fancy diff is
1702        # too hard ... or maybe not.  In two real-life failures Tim saw,
1703        # a diff was a major help anyway, so this is commented out.
1704        # [todo] _ellipsis_match() knows which pieces do and don't match,
1705        # and could be the basis for a kick-ass diff in this case.
1706        ##if optionflags & ELLIPSIS and ELLIPSIS_MARKER in want:
1707        ##    return False
1708
1709        # ndiff does intraline difference marking, so can be useful even
1710        # for 1-line differences.
1711        if optionflags & REPORT_NDIFF:
1712            return True
1713
1714        # The other diff types need at least a few lines to be helpful.
1715        return want.count('\n') > 2 and got.count('\n') > 2
1716
1717    def output_difference(self, example, got, optionflags):
1718        """
1719        Return a string describing the differences between the
1720        expected output for a given example (`example`) and the actual
1721        output (`got`).  `optionflags` is the set of option flags used
1722        to compare `want` and `got`.
1723        """
1724        want = example.want
1725        # If <BLANKLINE>s are being used, then replace blank lines
1726        # with <BLANKLINE> in the actual output string.
1727        if not (optionflags & DONT_ACCEPT_BLANKLINE):
1728            got = re.sub('(?m)^[ ]*(?=\n)', BLANKLINE_MARKER, got)
1729
1730        # Check if we should use diff.
1731        if self._do_a_fancy_diff(want, got, optionflags):
1732            # Split want & got into lines.
1733            want_lines = want.splitlines(keepends=True)
1734            got_lines = got.splitlines(keepends=True)
1735            # Use difflib to find their differences.
1736            if optionflags & REPORT_UDIFF:
1737                diff = difflib.unified_diff(want_lines, got_lines, n=2)
1738                diff = list(diff)[2:] # strip the diff header
1739                kind = 'unified diff with -expected +actual'
1740            elif optionflags & REPORT_CDIFF:
1741                diff = difflib.context_diff(want_lines, got_lines, n=2)
1742                diff = list(diff)[2:] # strip the diff header
1743                kind = 'context diff with expected followed by actual'
1744            elif optionflags & REPORT_NDIFF:
1745                engine = difflib.Differ(charjunk=difflib.IS_CHARACTER_JUNK)
1746                diff = list(engine.compare(want_lines, got_lines))
1747                kind = 'ndiff with -expected +actual'
1748            else:
1749                assert 0, 'Bad diff option'
1750            return 'Differences (%s):\n' % kind + _indent(''.join(diff))
1751
1752        # If we're not using diff, then simply list the expected
1753        # output followed by the actual output.
1754        if want and got:
1755            return 'Expected:\n%sGot:\n%s' % (_indent(want), _indent(got))
1756        elif want:
1757            return 'Expected:\n%sGot nothing\n' % _indent(want)
1758        elif got:
1759            return 'Expected nothing\nGot:\n%s' % _indent(got)
1760        else:
1761            return 'Expected nothing\nGot nothing\n'
1762
1763class DocTestFailure(Exception):
1764    """A DocTest example has failed in debugging mode.
1765
1766    The exception instance has variables:
1767
1768    - test: the DocTest object being run
1769
1770    - example: the Example object that failed
1771
1772    - got: the actual output
1773    """
1774    def __init__(self, test, example, got):
1775        self.test = test
1776        self.example = example
1777        self.got = got
1778
1779    def __str__(self):
1780        return str(self.test)
1781
1782class UnexpectedException(Exception):
1783    """A DocTest example has encountered an unexpected exception
1784
1785    The exception instance has variables:
1786
1787    - test: the DocTest object being run
1788
1789    - example: the Example object that failed
1790
1791    - exc_info: the exception info
1792    """
1793    def __init__(self, test, example, exc_info):
1794        self.test = test
1795        self.example = example
1796        self.exc_info = exc_info
1797
1798    def __str__(self):
1799        return str(self.test)
1800
1801class DebugRunner(DocTestRunner):
1802    r"""Run doc tests but raise an exception as soon as there is a failure.
1803
1804       If an unexpected exception occurs, an UnexpectedException is raised.
1805       It contains the test, the example, and the original exception:
1806
1807         >>> runner = DebugRunner(verbose=False)
1808         >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
1809         ...                                    {}, 'foo', 'foo.py', 0)
1810         >>> try:
1811         ...     runner.run(test)
1812         ... except UnexpectedException as f:
1813         ...     failure = f
1814
1815         >>> failure.test is test
1816         True
1817
1818         >>> failure.example.want
1819         '42\n'
1820
1821         >>> exc_info = failure.exc_info
1822         >>> raise exc_info[1] # Already has the traceback
1823         Traceback (most recent call last):
1824         ...
1825         KeyError
1826
1827       We wrap the original exception to give the calling application
1828       access to the test and example information.
1829
1830       If the output doesn't match, then a DocTestFailure is raised:
1831
1832         >>> test = DocTestParser().get_doctest('''
1833         ...      >>> x = 1
1834         ...      >>> x
1835         ...      2
1836         ...      ''', {}, 'foo', 'foo.py', 0)
1837
1838         >>> try:
1839         ...    runner.run(test)
1840         ... except DocTestFailure as f:
1841         ...    failure = f
1842
1843       DocTestFailure objects provide access to the test:
1844
1845         >>> failure.test is test
1846         True
1847
1848       As well as to the example:
1849
1850         >>> failure.example.want
1851         '2\n'
1852
1853       and the actual output:
1854
1855         >>> failure.got
1856         '1\n'
1857
1858       If a failure or error occurs, the globals are left intact:
1859
1860         >>> del test.globs['__builtins__']
1861         >>> test.globs
1862         {'x': 1}
1863
1864         >>> test = DocTestParser().get_doctest('''
1865         ...      >>> x = 2
1866         ...      >>> raise KeyError
1867         ...      ''', {}, 'foo', 'foo.py', 0)
1868
1869         >>> runner.run(test)
1870         Traceback (most recent call last):
1871         ...
1872         doctest.UnexpectedException: <DocTest foo from foo.py:0 (2 examples)>
1873
1874         >>> del test.globs['__builtins__']
1875         >>> test.globs
1876         {'x': 2}
1877
1878       But the globals are cleared if there is no error:
1879
1880         >>> test = DocTestParser().get_doctest('''
1881         ...      >>> x = 2
1882         ...      ''', {}, 'foo', 'foo.py', 0)
1883
1884         >>> runner.run(test)
1885         TestResults(failed=0, attempted=1)
1886
1887         >>> test.globs
1888         {}
1889
1890       """
1891
1892    def run(self, test, compileflags=None, out=None, clear_globs=True):
1893        r = DocTestRunner.run(self, test, compileflags, out, False)
1894        if clear_globs:
1895            test.globs.clear()
1896        return r
1897
1898    def report_unexpected_exception(self, out, test, example, exc_info):
1899        raise UnexpectedException(test, example, exc_info)
1900
1901    def report_failure(self, out, test, example, got):
1902        raise DocTestFailure(test, example, got)
1903
1904######################################################################
1905## 6. Test Functions
1906######################################################################
1907# These should be backwards compatible.
1908
1909# For backward compatibility, a global instance of a DocTestRunner
1910# class, updated by testmod.
1911master = None
1912
1913def testmod(m=None, name=None, globs=None, verbose=None,
1914            report=True, optionflags=0, extraglobs=None,
1915            raise_on_error=False, exclude_empty=False):
1916    """m=None, name=None, globs=None, verbose=None, report=True,
1917       optionflags=0, extraglobs=None, raise_on_error=False,
1918       exclude_empty=False
1919
1920    Test examples in docstrings in functions and classes reachable
1921    from module m (or the current module if m is not supplied), starting
1922    with m.__doc__.
1923
1924    Also test examples reachable from dict m.__test__ if it exists and is
1925    not None.  m.__test__ maps names to functions, classes and strings;
1926    function and class docstrings are tested even if the name is private;
1927    strings are tested directly, as if they were docstrings.
1928
1929    Return (#failures, #tests).
1930
1931    See help(doctest) for an overview.
1932
1933    Optional keyword arg "name" gives the name of the module; by default
1934    use m.__name__.
1935
1936    Optional keyword arg "globs" gives a dict to be used as the globals
1937    when executing examples; by default, use m.__dict__.  A copy of this
1938    dict is actually used for each docstring, so that each docstring's
1939    examples start with a clean slate.
1940
1941    Optional keyword arg "extraglobs" gives a dictionary that should be
1942    merged into the globals that are used to execute examples.  By
1943    default, no extra globals are used.  This is new in 2.4.
1944
1945    Optional keyword arg "verbose" prints lots of stuff if true, prints
1946    only failures if false; by default, it's true iff "-v" is in sys.argv.
1947
1948    Optional keyword arg "report" prints a summary at the end when true,
1949    else prints nothing at the end.  In verbose mode, the summary is
1950    detailed, else very brief (in fact, empty if all tests passed).
1951
1952    Optional keyword arg "optionflags" or's together module constants,
1953    and defaults to 0.  This is new in 2.3.  Possible values (see the
1954    docs for details):
1955
1956        DONT_ACCEPT_TRUE_FOR_1
1957        DONT_ACCEPT_BLANKLINE
1958        NORMALIZE_WHITESPACE
1959        ELLIPSIS
1960        SKIP
1961        IGNORE_EXCEPTION_DETAIL
1962        REPORT_UDIFF
1963        REPORT_CDIFF
1964        REPORT_NDIFF
1965        REPORT_ONLY_FIRST_FAILURE
1966
1967    Optional keyword arg "raise_on_error" raises an exception on the
1968    first unexpected exception or failure. This allows failures to be
1969    post-mortem debugged.
1970
1971    Advanced tomfoolery:  testmod runs methods of a local instance of
1972    class doctest.Tester, then merges the results into (or creates)
1973    global Tester instance doctest.master.  Methods of doctest.master
1974    can be called directly too, if you want to do something unusual.
1975    Passing report=0 to testmod is especially useful then, to delay
1976    displaying a summary.  Invoke doctest.master.summarize(verbose)
1977    when you're done fiddling.
1978    """
1979    global master
1980
1981    # If no module was given, then use __main__.
1982    if m is None:
1983        # DWA - m will still be None if this wasn't invoked from the command
1984        # line, in which case the following TypeError is about as good an error
1985        # as we should expect
1986        m = sys.modules.get('__main__')
1987
1988    # Check that we were actually given a module.
1989    if not inspect.ismodule(m):
1990        raise TypeError("testmod: module required; %r" % (m,))
1991
1992    # If no name was given, then use the module's name.
1993    if name is None:
1994        name = m.__name__
1995
1996    # Find, parse, and run all tests in the given module.
1997    finder = DocTestFinder(exclude_empty=exclude_empty)
1998
1999    if raise_on_error:
2000        runner = DebugRunner(verbose=verbose, optionflags=optionflags)
2001    else:
2002        runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
2003
2004    for test in finder.find(m, name, globs=globs, extraglobs=extraglobs):
2005        runner.run(test)
2006
2007    if report:
2008        runner.summarize()
2009
2010    if master is None:
2011        master = runner
2012    else:
2013        master.merge(runner)
2014
2015    return TestResults(runner.failures, runner.tries)
2016
2017def testfile(filename, module_relative=True, name=None, package=None,
2018             globs=None, verbose=None, report=True, optionflags=0,
2019             extraglobs=None, raise_on_error=False, parser=DocTestParser(),
2020             encoding=None):
2021    """
2022    Test examples in the given file.  Return (#failures, #tests).
2023
2024    Optional keyword arg "module_relative" specifies how filenames
2025    should be interpreted:
2026
2027      - If "module_relative" is True (the default), then "filename"
2028         specifies a module-relative path.  By default, this path is
2029         relative to the calling module's directory; but if the
2030         "package" argument is specified, then it is relative to that
2031         package.  To ensure os-independence, "filename" should use
2032         "/" characters to separate path segments, and should not
2033         be an absolute path (i.e., it may not begin with "/").
2034
2035      - If "module_relative" is False, then "filename" specifies an
2036        os-specific path.  The path may be absolute or relative (to
2037        the current working directory).
2038
2039    Optional keyword arg "name" gives the name of the test; by default
2040    use the file's basename.
2041
2042    Optional keyword argument "package" is a Python package or the
2043    name of a Python package whose directory should be used as the
2044    base directory for a module relative filename.  If no package is
2045    specified, then the calling module's directory is used as the base
2046    directory for module relative filenames.  It is an error to
2047    specify "package" if "module_relative" is False.
2048
2049    Optional keyword arg "globs" gives a dict to be used as the globals
2050    when executing examples; by default, use {}.  A copy of this dict
2051    is actually used for each docstring, so that each docstring's
2052    examples start with a clean slate.
2053
2054    Optional keyword arg "extraglobs" gives a dictionary that should be
2055    merged into the globals that are used to execute examples.  By
2056    default, no extra globals are used.
2057
2058    Optional keyword arg "verbose" prints lots of stuff if true, prints
2059    only failures if false; by default, it's true iff "-v" is in sys.argv.
2060
2061    Optional keyword arg "report" prints a summary at the end when true,
2062    else prints nothing at the end.  In verbose mode, the summary is
2063    detailed, else very brief (in fact, empty if all tests passed).
2064
2065    Optional keyword arg "optionflags" or's together module constants,
2066    and defaults to 0.  Possible values (see the docs for details):
2067
2068        DONT_ACCEPT_TRUE_FOR_1
2069        DONT_ACCEPT_BLANKLINE
2070        NORMALIZE_WHITESPACE
2071        ELLIPSIS
2072        SKIP
2073        IGNORE_EXCEPTION_DETAIL
2074        REPORT_UDIFF
2075        REPORT_CDIFF
2076        REPORT_NDIFF
2077        REPORT_ONLY_FIRST_FAILURE
2078
2079    Optional keyword arg "raise_on_error" raises an exception on the
2080    first unexpected exception or failure. This allows failures to be
2081    post-mortem debugged.
2082
2083    Optional keyword arg "parser" specifies a DocTestParser (or
2084    subclass) that should be used to extract tests from the files.
2085
2086    Optional keyword arg "encoding" specifies an encoding that should
2087    be used to convert the file to unicode.
2088
2089    Advanced tomfoolery:  testmod runs methods of a local instance of
2090    class doctest.Tester, then merges the results into (or creates)
2091    global Tester instance doctest.master.  Methods of doctest.master
2092    can be called directly too, if you want to do something unusual.
2093    Passing report=0 to testmod is especially useful then, to delay
2094    displaying a summary.  Invoke doctest.master.summarize(verbose)
2095    when you're done fiddling.
2096    """
2097    global master
2098
2099    if package and not module_relative:
2100        raise ValueError("Package may only be specified for module-"
2101                         "relative paths.")
2102
2103    # Relativize the path
2104    text, filename = _load_testfile(filename, package, module_relative,
2105                                    encoding or "utf-8")
2106
2107    # If no name was given, then use the file's name.
2108    if name is None:
2109        name = os.path.basename(filename)
2110
2111    # Assemble the globals.
2112    if globs is None:
2113        globs = {}
2114    else:
2115        globs = globs.copy()
2116    if extraglobs is not None:
2117        globs.update(extraglobs)
2118    if '__name__' not in globs:
2119        globs['__name__'] = '__main__'
2120
2121    if raise_on_error:
2122        runner = DebugRunner(verbose=verbose, optionflags=optionflags)
2123    else:
2124        runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
2125
2126    # Read the file, convert it to a test, and run it.
2127    test = parser.get_doctest(text, globs, name, filename, 0)
2128    runner.run(test)
2129
2130    if report:
2131        runner.summarize()
2132
2133    if master is None:
2134        master = runner
2135    else:
2136        master.merge(runner)
2137
2138    return TestResults(runner.failures, runner.tries)
2139
2140def run_docstring_examples(f, globs, verbose=False, name="NoName",
2141                           compileflags=None, optionflags=0):
2142    """
2143    Test examples in the given object's docstring (`f`), using `globs`
2144    as globals.  Optional argument `name` is used in failure messages.
2145    If the optional argument `verbose` is true, then generate output
2146    even if there are no failures.
2147
2148    `compileflags` gives the set of flags that should be used by the
2149    Python compiler when running the examples.  If not specified, then
2150    it will default to the set of future-import flags that apply to
2151    `globs`.
2152
2153    Optional keyword arg `optionflags` specifies options for the
2154    testing and output.  See the documentation for `testmod` for more
2155    information.
2156    """
2157    # Find, parse, and run all tests in the given module.
2158    finder = DocTestFinder(verbose=verbose, recurse=False)
2159    runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
2160    for test in finder.find(f, name, globs=globs):
2161        runner.run(test, compileflags=compileflags)
2162
2163######################################################################
2164## 7. Unittest Support
2165######################################################################
2166
2167_unittest_reportflags = 0
2168
2169def set_unittest_reportflags(flags):
2170    """Sets the unittest option flags.
2171
2172    The old flag is returned so that a runner could restore the old
2173    value if it wished to:
2174
2175      >>> import doctest
2176      >>> old = doctest._unittest_reportflags
2177      >>> doctest.set_unittest_reportflags(REPORT_NDIFF |
2178      ...                          REPORT_ONLY_FIRST_FAILURE) == old
2179      True
2180
2181      >>> doctest._unittest_reportflags == (REPORT_NDIFF |
2182      ...                                   REPORT_ONLY_FIRST_FAILURE)
2183      True
2184
2185    Only reporting flags can be set:
2186
2187      >>> doctest.set_unittest_reportflags(ELLIPSIS)
2188      Traceback (most recent call last):
2189      ...
2190      ValueError: ('Only reporting flags allowed', 8)
2191
2192      >>> doctest.set_unittest_reportflags(old) == (REPORT_NDIFF |
2193      ...                                   REPORT_ONLY_FIRST_FAILURE)
2194      True
2195    """
2196    global _unittest_reportflags
2197
2198    if (flags & REPORTING_FLAGS) != flags:
2199        raise ValueError("Only reporting flags allowed", flags)
2200    old = _unittest_reportflags
2201    _unittest_reportflags = flags
2202    return old
2203
2204
2205class DocTestCase(unittest.TestCase):
2206
2207    def __init__(self, test, optionflags=0, setUp=None, tearDown=None,
2208                 checker=None):
2209
2210        unittest.TestCase.__init__(self)
2211        self._dt_optionflags = optionflags
2212        self._dt_checker = checker
2213        self._dt_test = test
2214        self._dt_setUp = setUp
2215        self._dt_tearDown = tearDown
2216
2217    def setUp(self):
2218        test = self._dt_test
2219        self._dt_globs = test.globs.copy()
2220
2221        if self._dt_setUp is not None:
2222            self._dt_setUp(test)
2223
2224    def tearDown(self):
2225        test = self._dt_test
2226
2227        if self._dt_tearDown is not None:
2228            self._dt_tearDown(test)
2229
2230        # restore the original globs
2231        test.globs.clear()
2232        test.globs.update(self._dt_globs)
2233
2234    def runTest(self):
2235        test = self._dt_test
2236        old = sys.stdout
2237        new = StringIO()
2238        optionflags = self._dt_optionflags
2239
2240        if not (optionflags & REPORTING_FLAGS):
2241            # The option flags don't include any reporting flags,
2242            # so add the default reporting flags
2243            optionflags |= _unittest_reportflags
2244
2245        runner = DocTestRunner(optionflags=optionflags,
2246                               checker=self._dt_checker, verbose=False)
2247
2248        try:
2249            runner.DIVIDER = "-"*70
2250            failures, tries = runner.run(
2251                test, out=new.write, clear_globs=False)
2252        finally:
2253            sys.stdout = old
2254
2255        if failures:
2256            raise self.failureException(self.format_failure(new.getvalue()))
2257
2258    def format_failure(self, err):
2259        test = self._dt_test
2260        if test.lineno is None:
2261            lineno = 'unknown line number'
2262        else:
2263            lineno = '%s' % test.lineno
2264        lname = '.'.join(test.name.split('.')[-1:])
2265        return ('Failed doctest test for %s\n'
2266                '  File "%s", line %s, in %s\n\n%s'
2267                % (test.name, test.filename, lineno, lname, err)
2268                )
2269
2270    def debug(self):
2271        r"""Run the test case without results and without catching exceptions
2272
2273           The unit test framework includes a debug method on test cases
2274           and test suites to support post-mortem debugging.  The test code
2275           is run in such a way that errors are not caught.  This way a
2276           caller can catch the errors and initiate post-mortem debugging.
2277
2278           The DocTestCase provides a debug method that raises
2279           UnexpectedException errors if there is an unexpected
2280           exception:
2281
2282             >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
2283             ...                {}, 'foo', 'foo.py', 0)
2284             >>> case = DocTestCase(test)
2285             >>> try:
2286             ...     case.debug()
2287             ... except UnexpectedException as f:
2288             ...     failure = f
2289
2290           The UnexpectedException contains the test, the example, and
2291           the original exception:
2292
2293             >>> failure.test is test
2294             True
2295
2296             >>> failure.example.want
2297             '42\n'
2298
2299             >>> exc_info = failure.exc_info
2300             >>> raise exc_info[1] # Already has the traceback
2301             Traceback (most recent call last):
2302             ...
2303             KeyError
2304
2305           If the output doesn't match, then a DocTestFailure is raised:
2306
2307             >>> test = DocTestParser().get_doctest('''
2308             ...      >>> x = 1
2309             ...      >>> x
2310             ...      2
2311             ...      ''', {}, 'foo', 'foo.py', 0)
2312             >>> case = DocTestCase(test)
2313
2314             >>> try:
2315             ...    case.debug()
2316             ... except DocTestFailure as f:
2317             ...    failure = f
2318
2319           DocTestFailure objects provide access to the test:
2320
2321             >>> failure.test is test
2322             True
2323
2324           As well as to the example:
2325
2326             >>> failure.example.want
2327             '2\n'
2328
2329           and the actual output:
2330
2331             >>> failure.got
2332             '1\n'
2333
2334           """
2335
2336        self.setUp()
2337        runner = DebugRunner(optionflags=self._dt_optionflags,
2338                             checker=self._dt_checker, verbose=False)
2339        runner.run(self._dt_test, clear_globs=False)
2340        self.tearDown()
2341
2342    def id(self):
2343        return self._dt_test.name
2344
2345    def __eq__(self, other):
2346        if type(self) is not type(other):
2347            return NotImplemented
2348
2349        return self._dt_test == other._dt_test and \
2350               self._dt_optionflags == other._dt_optionflags and \
2351               self._dt_setUp == other._dt_setUp and \
2352               self._dt_tearDown == other._dt_tearDown and \
2353               self._dt_checker == other._dt_checker
2354
2355    def __hash__(self):
2356        return hash((self._dt_optionflags, self._dt_setUp, self._dt_tearDown,
2357                     self._dt_checker))
2358
2359    def __repr__(self):
2360        name = self._dt_test.name.split('.')
2361        return "%s (%s)" % (name[-1], '.'.join(name[:-1]))
2362
2363    __str__ = object.__str__
2364
2365    def shortDescription(self):
2366        return "Doctest: " + self._dt_test.name
2367
2368class SkipDocTestCase(DocTestCase):
2369    def __init__(self, module):
2370        self.module = module
2371        DocTestCase.__init__(self, None)
2372
2373    def setUp(self):
2374        self.skipTest("DocTestSuite will not work with -O2 and above")
2375
2376    def test_skip(self):
2377        pass
2378
2379    def shortDescription(self):
2380        return "Skipping tests from %s" % self.module.__name__
2381
2382    __str__ = shortDescription
2383
2384
2385class _DocTestSuite(unittest.TestSuite):
2386
2387    def _removeTestAtIndex(self, index):
2388        pass
2389
2390
2391def DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None,
2392                 **options):
2393    """
2394    Convert doctest tests for a module to a unittest test suite.
2395
2396    This converts each documentation string in a module that
2397    contains doctest tests to a unittest test case.  If any of the
2398    tests in a doc string fail, then the test case fails.  An exception
2399    is raised showing the name of the file containing the test and a
2400    (sometimes approximate) line number.
2401
2402    The `module` argument provides the module to be tested.  The argument
2403    can be either a module or a module name.
2404
2405    If no argument is given, the calling module is used.
2406
2407    A number of options may be provided as keyword arguments:
2408
2409    setUp
2410      A set-up function.  This is called before running the
2411      tests in each file. The setUp function will be passed a DocTest
2412      object.  The setUp function can access the test globals as the
2413      globs attribute of the test passed.
2414
2415    tearDown
2416      A tear-down function.  This is called after running the
2417      tests in each file.  The tearDown function will be passed a DocTest
2418      object.  The tearDown function can access the test globals as the
2419      globs attribute of the test passed.
2420
2421    globs
2422      A dictionary containing initial global variables for the tests.
2423
2424    optionflags
2425       A set of doctest option flags expressed as an integer.
2426    """
2427
2428    if test_finder is None:
2429        test_finder = DocTestFinder()
2430
2431    module = _normalize_module(module)
2432    tests = test_finder.find(module, globs=globs, extraglobs=extraglobs)
2433
2434    if not tests and sys.flags.optimize >=2:
2435        # Skip doctests when running with -O2
2436        suite = _DocTestSuite()
2437        suite.addTest(SkipDocTestCase(module))
2438        return suite
2439
2440    tests.sort()
2441    suite = _DocTestSuite()
2442
2443    for test in tests:
2444        if len(test.examples) == 0:
2445            continue
2446        if not test.filename:
2447            filename = module.__file__
2448            if filename[-4:] == ".pyc":
2449                filename = filename[:-1]
2450            test.filename = filename
2451        suite.addTest(DocTestCase(test, **options))
2452
2453    return suite
2454
2455class DocFileCase(DocTestCase):
2456
2457    def id(self):
2458        return '_'.join(self._dt_test.name.split('.'))
2459
2460    def __repr__(self):
2461        return self._dt_test.filename
2462
2463    def format_failure(self, err):
2464        return ('Failed doctest test for %s\n  File "%s", line 0\n\n%s'
2465                % (self._dt_test.name, self._dt_test.filename, err)
2466                )
2467
2468def DocFileTest(path, module_relative=True, package=None,
2469                globs=None, parser=DocTestParser(),
2470                encoding=None, **options):
2471    if globs is None:
2472        globs = {}
2473    else:
2474        globs = globs.copy()
2475
2476    if package and not module_relative:
2477        raise ValueError("Package may only be specified for module-"
2478                         "relative paths.")
2479
2480    # Relativize the path.
2481    doc, path = _load_testfile(path, package, module_relative,
2482                               encoding or "utf-8")
2483
2484    if "__file__" not in globs:
2485        globs["__file__"] = path
2486
2487    # Find the file and read it.
2488    name = os.path.basename(path)
2489
2490    # Convert it to a test, and wrap it in a DocFileCase.
2491    test = parser.get_doctest(doc, globs, name, path, 0)
2492    return DocFileCase(test, **options)
2493
2494def DocFileSuite(*paths, **kw):
2495    """A unittest suite for one or more doctest files.
2496
2497    The path to each doctest file is given as a string; the
2498    interpretation of that string depends on the keyword argument
2499    "module_relative".
2500
2501    A number of options may be provided as keyword arguments:
2502
2503    module_relative
2504      If "module_relative" is True, then the given file paths are
2505      interpreted as os-independent module-relative paths.  By
2506      default, these paths are relative to the calling module's
2507      directory; but if the "package" argument is specified, then
2508      they are relative to that package.  To ensure os-independence,
2509      "filename" should use "/" characters to separate path
2510      segments, and may not be an absolute path (i.e., it may not
2511      begin with "/").
2512
2513      If "module_relative" is False, then the given file paths are
2514      interpreted as os-specific paths.  These paths may be absolute
2515      or relative (to the current working directory).
2516
2517    package
2518      A Python package or the name of a Python package whose directory
2519      should be used as the base directory for module relative paths.
2520      If "package" is not specified, then the calling module's
2521      directory is used as the base directory for module relative
2522      filenames.  It is an error to specify "package" if
2523      "module_relative" is False.
2524
2525    setUp
2526      A set-up function.  This is called before running the
2527      tests in each file. The setUp function will be passed a DocTest
2528      object.  The setUp function can access the test globals as the
2529      globs attribute of the test passed.
2530
2531    tearDown
2532      A tear-down function.  This is called after running the
2533      tests in each file.  The tearDown function will be passed a DocTest
2534      object.  The tearDown function can access the test globals as the
2535      globs attribute of the test passed.
2536
2537    globs
2538      A dictionary containing initial global variables for the tests.
2539
2540    optionflags
2541      A set of doctest option flags expressed as an integer.
2542
2543    parser
2544      A DocTestParser (or subclass) that should be used to extract
2545      tests from the files.
2546
2547    encoding
2548      An encoding that will be used to convert the files to unicode.
2549    """
2550    suite = _DocTestSuite()
2551
2552    # We do this here so that _normalize_module is called at the right
2553    # level.  If it were called in DocFileTest, then this function
2554    # would be the caller and we might guess the package incorrectly.
2555    if kw.get('module_relative', True):
2556        kw['package'] = _normalize_module(kw.get('package'))
2557
2558    for path in paths:
2559        suite.addTest(DocFileTest(path, **kw))
2560
2561    return suite
2562
2563######################################################################
2564## 8. Debugging Support
2565######################################################################
2566
2567def script_from_examples(s):
2568    r"""Extract script from text with examples.
2569
2570       Converts text with examples to a Python script.  Example input is
2571       converted to regular code.  Example output and all other words
2572       are converted to comments:
2573
2574       >>> text = '''
2575       ...       Here are examples of simple math.
2576       ...
2577       ...           Python has super accurate integer addition
2578       ...
2579       ...           >>> 2 + 2
2580       ...           5
2581       ...
2582       ...           And very friendly error messages:
2583       ...
2584       ...           >>> 1/0
2585       ...           To Infinity
2586       ...           And
2587       ...           Beyond
2588       ...
2589       ...           You can use logic if you want:
2590       ...
2591       ...           >>> if 0:
2592       ...           ...    blah
2593       ...           ...    blah
2594       ...           ...
2595       ...
2596       ...           Ho hum
2597       ...           '''
2598
2599       >>> print(script_from_examples(text))
2600       # Here are examples of simple math.
2601       #
2602       #     Python has super accurate integer addition
2603       #
2604       2 + 2
2605       # Expected:
2606       ## 5
2607       #
2608       #     And very friendly error messages:
2609       #
2610       1/0
2611       # Expected:
2612       ## To Infinity
2613       ## And
2614       ## Beyond
2615       #
2616       #     You can use logic if you want:
2617       #
2618       if 0:
2619          blah
2620          blah
2621       #
2622       #     Ho hum
2623       <BLANKLINE>
2624       """
2625    output = []
2626    for piece in DocTestParser().parse(s):
2627        if isinstance(piece, Example):
2628            # Add the example's source code (strip trailing NL)
2629            output.append(piece.source[:-1])
2630            # Add the expected output:
2631            want = piece.want
2632            if want:
2633                output.append('# Expected:')
2634                output += ['## '+l for l in want.split('\n')[:-1]]
2635        else:
2636            # Add non-example text.
2637            output += [_comment_line(l)
2638                       for l in piece.split('\n')[:-1]]
2639
2640    # Trim junk on both ends.
2641    while output and output[-1] == '#':
2642        output.pop()
2643    while output and output[0] == '#':
2644        output.pop(0)
2645    # Combine the output, and return it.
2646    # Add a courtesy newline to prevent exec from choking (see bug #1172785)
2647    return '\n'.join(output) + '\n'
2648
2649def testsource(module, name):
2650    """Extract the test sources from a doctest docstring as a script.
2651
2652    Provide the module (or dotted name of the module) containing the
2653    test to be debugged and the name (within the module) of the object
2654    with the doc string with tests to be debugged.
2655    """
2656    module = _normalize_module(module)
2657    tests = DocTestFinder().find(module)
2658    test = [t for t in tests if t.name == name]
2659    if not test:
2660        raise ValueError(name, "not found in tests")
2661    test = test[0]
2662    testsrc = script_from_examples(test.docstring)
2663    return testsrc
2664
2665def debug_src(src, pm=False, globs=None):
2666    """Debug a single doctest docstring, in argument `src`'"""
2667    testsrc = script_from_examples(src)
2668    debug_script(testsrc, pm, globs)
2669
2670def debug_script(src, pm=False, globs=None):
2671    "Debug a test script.  `src` is the script, as a string."
2672    import pdb
2673
2674    if globs:
2675        globs = globs.copy()
2676    else:
2677        globs = {}
2678
2679    if pm:
2680        try:
2681            exec(src, globs, globs)
2682        except:
2683            print(sys.exc_info()[1])
2684            p = pdb.Pdb(nosigint=True)
2685            p.reset()
2686            p.interaction(None, sys.exc_info()[2])
2687    else:
2688        pdb.Pdb(nosigint=True).run("exec(%r)" % src, globs, globs)
2689
2690def debug(module, name, pm=False):
2691    """Debug a single doctest docstring.
2692
2693    Provide the module (or dotted name of the module) containing the
2694    test to be debugged and the name (within the module) of the object
2695    with the docstring with tests to be debugged.
2696    """
2697    module = _normalize_module(module)
2698    testsrc = testsource(module, name)
2699    debug_script(testsrc, pm, module.__dict__)
2700
2701######################################################################
2702## 9. Example Usage
2703######################################################################
2704class _TestClass:
2705    """
2706    A pointless class, for sanity-checking of docstring testing.
2707
2708    Methods:
2709        square()
2710        get()
2711
2712    >>> _TestClass(13).get() + _TestClass(-12).get()
2713    1
2714    >>> hex(_TestClass(13).square().get())
2715    '0xa9'
2716    """
2717
2718    def __init__(self, val):
2719        """val -> _TestClass object with associated value val.
2720
2721        >>> t = _TestClass(123)
2722        >>> print(t.get())
2723        123
2724        """
2725
2726        self.val = val
2727
2728    def square(self):
2729        """square() -> square TestClass's associated value
2730
2731        >>> _TestClass(13).square().get()
2732        169
2733        """
2734
2735        self.val = self.val ** 2
2736        return self
2737
2738    def get(self):
2739        """get() -> return TestClass's associated value.
2740
2741        >>> x = _TestClass(-42)
2742        >>> print(x.get())
2743        -42
2744        """
2745
2746        return self.val
2747
2748__test__ = {"_TestClass": _TestClass,
2749            "string": r"""
2750                      Example of a string object, searched as-is.
2751                      >>> x = 1; y = 2
2752                      >>> x + y, x * y
2753                      (3, 2)
2754                      """,
2755
2756            "bool-int equivalence": r"""
2757                                    In 2.2, boolean expressions displayed
2758                                    0 or 1.  By default, we still accept
2759                                    them.  This can be disabled by passing
2760                                    DONT_ACCEPT_TRUE_FOR_1 to the new
2761                                    optionflags argument.
2762                                    >>> 4 == 4
2763                                    1
2764                                    >>> 4 == 4
2765                                    True
2766                                    >>> 4 > 4
2767                                    0
2768                                    >>> 4 > 4
2769                                    False
2770                                    """,
2771
2772            "blank lines": r"""
2773                Blank lines can be marked with <BLANKLINE>:
2774                    >>> print('foo\n\nbar\n')
2775                    foo
2776                    <BLANKLINE>
2777                    bar
2778                    <BLANKLINE>
2779            """,
2780
2781            "ellipsis": r"""
2782                If the ellipsis flag is used, then '...' can be used to
2783                elide substrings in the desired output:
2784                    >>> print(list(range(1000))) #doctest: +ELLIPSIS
2785                    [0, 1, 2, ..., 999]
2786            """,
2787
2788            "whitespace normalization": r"""
2789                If the whitespace normalization flag is used, then
2790                differences in whitespace are ignored.
2791                    >>> print(list(range(30))) #doctest: +NORMALIZE_WHITESPACE
2792                    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
2793                     15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,
2794                     27, 28, 29]
2795            """,
2796           }
2797
2798
2799def _test():
2800    import argparse
2801
2802    parser = argparse.ArgumentParser(description="doctest runner")
2803    parser.add_argument('-v', '--verbose', action='store_true', default=False,
2804                        help='print very verbose output for all tests')
2805    parser.add_argument('-o', '--option', action='append',
2806                        choices=OPTIONFLAGS_BY_NAME.keys(), default=[],
2807                        help=('specify a doctest option flag to apply'
2808                              ' to the test run; may be specified more'
2809                              ' than once to apply multiple options'))
2810    parser.add_argument('-f', '--fail-fast', action='store_true',
2811                        help=('stop running tests after first failure (this'
2812                              ' is a shorthand for -o FAIL_FAST, and is'
2813                              ' in addition to any other -o options)'))
2814    parser.add_argument('file', nargs='+',
2815                        help='file containing the tests to run')
2816    args = parser.parse_args()
2817    testfiles = args.file
2818    # Verbose used to be handled by the "inspect argv" magic in DocTestRunner,
2819    # but since we are using argparse we are passing it manually now.
2820    verbose = args.verbose
2821    options = 0
2822    for option in args.option:
2823        options |= OPTIONFLAGS_BY_NAME[option]
2824    if args.fail_fast:
2825        options |= FAIL_FAST
2826    for filename in testfiles:
2827        if filename.endswith(".py"):
2828            # It is a module -- insert its dir into sys.path and try to
2829            # import it. If it is part of a package, that possibly
2830            # won't work because of package imports.
2831            dirname, filename = os.path.split(filename)
2832            sys.path.insert(0, dirname)
2833            m = __import__(filename[:-3])
2834            del sys.path[0]
2835            failures, _ = testmod(m, verbose=verbose, optionflags=options)
2836        else:
2837            failures, _ = testfile(filename, module_relative=False,
2838                                     verbose=verbose, optionflags=options)
2839        if failures:
2840            return 1
2841    return 0
2842
2843
2844if __name__ == "__main__":
2845    sys.exit(_test())