PageRenderTime 1053ms CodeModel.GetById 131ms app.highlight 428ms RepoModel.GetById 428ms app.codeStats 1ms

/Lib/doctest.py

http://unladen-swallow.googlecode.com/
Python | 2686 lines | 2629 code | 13 blank | 44 comment | 38 complexity | 7d583fc0f10531949ea1ba679be0b68e MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   1# Module doctest.
   2# Released to the public domain 16-Jan-2001, by Tim Peters (tim@python.org).
   3# Major enhancements and refactoring by:
   4#     Jim Fulton
   5#     Edward Loper
   6
   7# Provided as-is; use at your own risk; no warranty; no promises; enjoy!
   8
   9r"""Module doctest -- a framework for running examples in docstrings.
  10
  11In simplest use, end each module M to be tested with:
  12
  13def _test():
  14    import doctest
  15    doctest.testmod()
  16
  17if __name__ == "__main__":
  18    _test()
  19
  20Then running the module as a script will cause the examples in the
  21docstrings to get executed and verified:
  22
  23python M.py
  24
  25This won't display anything unless an example fails, in which case the
  26failing example(s) and the cause(s) of the failure(s) are printed to stdout
  27(why not stderr? because stderr is a lame hack <0.2 wink>), and the final
  28line of output is "Test failed.".
  29
  30Run it with the -v switch instead:
  31
  32python M.py -v
  33
  34and a detailed report of all examples tried is printed to stdout, along
  35with assorted summaries at the end.
  36
  37You can force verbose mode by passing "verbose=True" to testmod, or prohibit
  38it by passing "verbose=False".  In either of those cases, sys.argv is not
  39examined by testmod.
  40
  41There are a variety of other ways to run doctests, including integration
  42with the unittest framework, and support for running non-Python text
  43files containing doctests.  There are also many ways to override parts
  44of doctest's default behaviors.  See the Library Reference Manual for
  45details.
  46"""
  47
  48__docformat__ = 'reStructuredText en'
  49
  50__all__ = [
  51    # 0, Option Flags
  52    'register_optionflag',
  53    'DONT_ACCEPT_TRUE_FOR_1',
  54    'DONT_ACCEPT_BLANKLINE',
  55    'NORMALIZE_WHITESPACE',
  56    'ELLIPSIS',
  57    'SKIP',
  58    'IGNORE_EXCEPTION_DETAIL',
  59    'COMPARISON_FLAGS',
  60    'REPORT_UDIFF',
  61    'REPORT_CDIFF',
  62    'REPORT_NDIFF',
  63    'REPORT_ONLY_FIRST_FAILURE',
  64    'REPORTING_FLAGS',
  65    # 1. Utility Functions
  66    # 2. Example & DocTest
  67    'Example',
  68    'DocTest',
  69    # 3. Doctest Parser
  70    'DocTestParser',
  71    # 4. Doctest Finder
  72    'DocTestFinder',
  73    # 5. Doctest Runner
  74    'DocTestRunner',
  75    'OutputChecker',
  76    'DocTestFailure',
  77    'UnexpectedException',
  78    'DebugRunner',
  79    # 6. Test Functions
  80    'testmod',
  81    'testfile',
  82    'run_docstring_examples',
  83    # 7. Tester
  84    'Tester',
  85    # 8. Unittest Support
  86    'DocTestSuite',
  87    'DocFileSuite',
  88    'set_unittest_reportflags',
  89    # 9. Debugging Support
  90    'script_from_examples',
  91    'testsource',
  92    'debug_src',
  93    'debug',
  94]
  95
  96import __future__
  97
  98import sys, traceback, inspect, linecache, os, re
  99import unittest, difflib, pdb, tempfile
 100import warnings
 101from StringIO import StringIO
 102from collections import namedtuple
 103
 104TestResults = namedtuple('TestResults', 'failed attempted')
 105
 106# There are 4 basic classes:
 107#  - Example: a <source, want> pair, plus an intra-docstring line number.
 108#  - DocTest: a collection of examples, parsed from a docstring, plus
 109#    info about where the docstring came from (name, filename, lineno).
 110#  - DocTestFinder: extracts DocTests from a given object's docstring and
 111#    its contained objects' docstrings.
 112#  - DocTestRunner: runs DocTest cases, and accumulates statistics.
 113#
 114# So the basic picture is:
 115#
 116#                             list of:
 117# +------+                   +---------+                   +-------+
 118# |object| --DocTestFinder-> | DocTest | --DocTestRunner-> |results|
 119# +------+                   +---------+                   +-------+
 120#                            | Example |
 121#                            |   ...   |
 122#                            | Example |
 123#                            +---------+
 124
 125# Option constants.
 126
 127OPTIONFLAGS_BY_NAME = {}
 128def register_optionflag(name):
 129    # Create a new flag unless `name` is already known.
 130    return OPTIONFLAGS_BY_NAME.setdefault(name, 1 << len(OPTIONFLAGS_BY_NAME))
 131
 132DONT_ACCEPT_TRUE_FOR_1 = register_optionflag('DONT_ACCEPT_TRUE_FOR_1')
 133DONT_ACCEPT_BLANKLINE = register_optionflag('DONT_ACCEPT_BLANKLINE')
 134NORMALIZE_WHITESPACE = register_optionflag('NORMALIZE_WHITESPACE')
 135ELLIPSIS = register_optionflag('ELLIPSIS')
 136SKIP = register_optionflag('SKIP')
 137IGNORE_EXCEPTION_DETAIL = register_optionflag('IGNORE_EXCEPTION_DETAIL')
 138
 139COMPARISON_FLAGS = (DONT_ACCEPT_TRUE_FOR_1 |
 140                    DONT_ACCEPT_BLANKLINE |
 141                    NORMALIZE_WHITESPACE |
 142                    ELLIPSIS |
 143                    SKIP |
 144                    IGNORE_EXCEPTION_DETAIL)
 145
 146REPORT_UDIFF = register_optionflag('REPORT_UDIFF')
 147REPORT_CDIFF = register_optionflag('REPORT_CDIFF')
 148REPORT_NDIFF = register_optionflag('REPORT_NDIFF')
 149REPORT_ONLY_FIRST_FAILURE = register_optionflag('REPORT_ONLY_FIRST_FAILURE')
 150
 151REPORTING_FLAGS = (REPORT_UDIFF |
 152                   REPORT_CDIFF |
 153                   REPORT_NDIFF |
 154                   REPORT_ONLY_FIRST_FAILURE)
 155
 156# Special string markers for use in `want` strings:
 157BLANKLINE_MARKER = '<BLANKLINE>'
 158ELLIPSIS_MARKER = '...'
 159
 160######################################################################
 161## Table of Contents
 162######################################################################
 163#  1. Utility Functions
 164#  2. Example & DocTest -- store test cases
 165#  3. DocTest Parser -- extracts examples from strings
 166#  4. DocTest Finder -- extracts test cases from objects
 167#  5. DocTest Runner -- runs test cases
 168#  6. Test Functions -- convenient wrappers for testing
 169#  7. Tester Class -- for backwards compatibility
 170#  8. Unittest Support
 171#  9. Debugging Support
 172# 10. Example Usage
 173
 174######################################################################
 175## 1. Utility Functions
 176######################################################################
 177
 178def _extract_future_flags(globs):
 179    """
 180    Return the compiler-flags associated with the future features that
 181    have been imported into the given namespace (globs).
 182    """
 183    flags = 0
 184    for fname in __future__.all_feature_names:
 185        feature = globs.get(fname, None)
 186        if feature is getattr(__future__, fname):
 187            flags |= feature.compiler_flag
 188    return flags
 189
 190def _normalize_module(module, depth=2):
 191    """
 192    Return the module specified by `module`.  In particular:
 193      - If `module` is a module, then return module.
 194      - If `module` is a string, then import and return the
 195        module with that name.
 196      - If `module` is None, then return the calling module.
 197        The calling module is assumed to be the module of
 198        the stack frame at the given depth in the call stack.
 199    """
 200    if inspect.ismodule(module):
 201        return module
 202    elif isinstance(module, (str, unicode)):
 203        return __import__(module, globals(), locals(), ["*"])
 204    elif module is None:
 205        return sys.modules[sys._getframe(depth).f_globals['__name__']]
 206    else:
 207        raise TypeError("Expected a module, string, or None")
 208
 209def _load_testfile(filename, package, module_relative):
 210    if module_relative:
 211        package = _normalize_module(package, 3)
 212        filename = _module_relative_path(package, filename)
 213        if hasattr(package, '__loader__'):
 214            if hasattr(package.__loader__, 'get_data'):
 215                file_contents = package.__loader__.get_data(filename)
 216                # get_data() opens files as 'rb', so one must do the equivalent
 217                # conversion as universal newlines would do.
 218                return file_contents.replace(os.linesep, '\n'), filename
 219    return open(filename).read(), filename
 220
 221def _indent(s, indent=4):
 222    """
 223    Add the given number of space characters to the beginning every
 224    non-blank line in `s`, and return the result.
 225    """
 226    # This regexp matches the start of non-blank lines:
 227    return re.sub('(?m)^(?!$)', indent*' ', s)
 228
 229def _exception_traceback(exc_info):
 230    """
 231    Return a string containing a traceback message for the given
 232    exc_info tuple (as returned by sys.exc_info()).
 233    """
 234    # Get a traceback message.
 235    excout = StringIO()
 236    exc_type, exc_val, exc_tb = exc_info
 237    traceback.print_exception(exc_type, exc_val, exc_tb, file=excout)
 238    return excout.getvalue()
 239
 240# Override some StringIO methods.
 241class _SpoofOut(StringIO):
 242    def getvalue(self):
 243        result = StringIO.getvalue(self)
 244        # If anything at all was written, make sure there's a trailing
 245        # newline.  There's no way for the expected output to indicate
 246        # that a trailing newline is missing.
 247        if result and not result.endswith("\n"):
 248            result += "\n"
 249        # Prevent softspace from screwing up the next test case, in
 250        # case they used print with a trailing comma in an example.
 251        if hasattr(self, "softspace"):
 252            del self.softspace
 253        return result
 254
 255    def truncate(self,   size=None):
 256        StringIO.truncate(self, size)
 257        if hasattr(self, "softspace"):
 258            del self.softspace
 259
 260# Worst-case linear-time ellipsis matching.
 261def _ellipsis_match(want, got):
 262    """
 263    Essentially the only subtle case:
 264    >>> _ellipsis_match('aa...aa', 'aaa')
 265    False
 266    """
 267    if ELLIPSIS_MARKER not in want:
 268        return want == got
 269
 270    # Find "the real" strings.
 271    ws = want.split(ELLIPSIS_MARKER)
 272    assert len(ws) >= 2
 273
 274    # Deal with exact matches possibly needed at one or both ends.
 275    startpos, endpos = 0, len(got)
 276    w = ws[0]
 277    if w:   # starts with exact match
 278        if got.startswith(w):
 279            startpos = len(w)
 280            del ws[0]
 281        else:
 282            return False
 283    w = ws[-1]
 284    if w:   # ends with exact match
 285        if got.endswith(w):
 286            endpos -= len(w)
 287            del ws[-1]
 288        else:
 289            return False
 290
 291    if startpos > endpos:
 292        # Exact end matches required more characters than we have, as in
 293        # _ellipsis_match('aa...aa', 'aaa')
 294        return False
 295
 296    # For the rest, we only need to find the leftmost non-overlapping
 297    # match for each piece.  If there's no overall match that way alone,
 298    # there's no overall match period.
 299    for w in ws:
 300        # w may be '' at times, if there are consecutive ellipses, or
 301        # due to an ellipsis at the start or end of `want`.  That's OK.
 302        # Search for an empty string succeeds, and doesn't change startpos.
 303        startpos = got.find(w, startpos, endpos)
 304        if startpos < 0:
 305            return False
 306        startpos += len(w)
 307
 308    return True
 309
 310def _comment_line(line):
 311    "Return a commented form of the given line"
 312    line = line.rstrip()
 313    if line:
 314        return '# '+line
 315    else:
 316        return '#'
 317
 318class _OutputRedirectingPdb(pdb.Pdb):
 319    """
 320    A specialized version of the python debugger that redirects stdout
 321    to a given stream when interacting with the user.  Stdout is *not*
 322    redirected when traced code is executed.
 323    """
 324    def __init__(self, out):
 325        self.__out = out
 326        self.__debugger_used = False
 327        pdb.Pdb.__init__(self, stdout=out)
 328
 329    def set_trace(self, frame=None):
 330        self.__debugger_used = True
 331        if frame is None:
 332            frame = sys._getframe().f_back
 333        pdb.Pdb.set_trace(self, frame)
 334
 335    def set_continue(self):
 336        # Calling set_continue unconditionally would break unit test
 337        # coverage reporting, as Bdb.set_continue calls sys.settrace(None).
 338        if self.__debugger_used:
 339            pdb.Pdb.set_continue(self)
 340
 341    def trace_dispatch(self, *args):
 342        # Redirect stdout to the given stream.
 343        save_stdout = sys.stdout
 344        sys.stdout = self.__out
 345        # Call Pdb's trace dispatch method.
 346        try:
 347            return pdb.Pdb.trace_dispatch(self, *args)
 348        finally:
 349            sys.stdout = save_stdout
 350
 351# [XX] Normalize with respect to os.path.pardir?
 352def _module_relative_path(module, path):
 353    if not inspect.ismodule(module):
 354        raise TypeError, 'Expected a module: %r' % module
 355    if path.startswith('/'):
 356        raise ValueError, 'Module-relative files may not have absolute paths'
 357
 358    # Find the base directory for the path.
 359    if hasattr(module, '__file__'):
 360        # A normal module/package
 361        basedir = os.path.split(module.__file__)[0]
 362    elif module.__name__ == '__main__':
 363        # An interactive session.
 364        if len(sys.argv)>0 and sys.argv[0] != '':
 365            basedir = os.path.split(sys.argv[0])[0]
 366        else:
 367            basedir = os.curdir
 368    else:
 369        # A module w/o __file__ (this includes builtins)
 370        raise ValueError("Can't resolve paths relative to the module " +
 371                         module + " (it has no __file__)")
 372
 373    # Combine the base directory and the path.
 374    return os.path.join(basedir, *(path.split('/')))
 375
 376######################################################################
 377## 2. Example & DocTest
 378######################################################################
 379## - An "example" is a <source, want> pair, where "source" is a
 380##   fragment of source code, and "want" is the expected output for
 381##   "source."  The Example class also includes information about
 382##   where the example was extracted from.
 383##
 384## - A "doctest" is a collection of examples, typically extracted from
 385##   a string (such as an object's docstring).  The DocTest class also
 386##   includes information about where the string was extracted from.
 387
 388class Example:
 389    """
 390    A single doctest example, consisting of source code and expected
 391    output.  `Example` defines the following attributes:
 392
 393      - source: A single Python statement, always ending with a newline.
 394        The constructor adds a newline if needed.
 395
 396      - want: The expected output from running the source code (either
 397        from stdout, or a traceback in case of exception).  `want` ends
 398        with a newline unless it's empty, in which case it's an empty
 399        string.  The constructor adds a newline if needed.
 400
 401      - exc_msg: The exception message generated by the example, if
 402        the example is expected to generate an exception; or `None` if
 403        it is not expected to generate an exception.  This exception
 404        message is compared against the return value of
 405        `traceback.format_exception_only()`.  `exc_msg` ends with a
 406        newline unless it's `None`.  The constructor adds a newline
 407        if needed.
 408
 409      - lineno: The line number within the DocTest string containing
 410        this Example where the Example begins.  This line number is
 411        zero-based, with respect to the beginning of the DocTest.
 412
 413      - indent: The example's indentation in the DocTest string.
 414        I.e., the number of space characters that preceed the
 415        example's first prompt.
 416
 417      - options: A dictionary mapping from option flags to True or
 418        False, which is used to override default options for this
 419        example.  Any option flags not contained in this dictionary
 420        are left at their default value (as specified by the
 421        DocTestRunner's optionflags).  By default, no options are set.
 422    """
 423    def __init__(self, source, want, exc_msg=None, lineno=0, indent=0,
 424                 options=None):
 425        # Normalize inputs.
 426        if not source.endswith('\n'):
 427            source += '\n'
 428        if want and not want.endswith('\n'):
 429            want += '\n'
 430        if exc_msg is not None and not exc_msg.endswith('\n'):
 431            exc_msg += '\n'
 432        # Store properties.
 433        self.source = source
 434        self.want = want
 435        self.lineno = lineno
 436        self.indent = indent
 437        if options is None: options = {}
 438        self.options = options
 439        self.exc_msg = exc_msg
 440
 441class DocTest:
 442    """
 443    A collection of doctest examples that should be run in a single
 444    namespace.  Each `DocTest` defines the following attributes:
 445
 446      - examples: the list of examples.
 447
 448      - globs: The namespace (aka globals) that the examples should
 449        be run in.
 450
 451      - name: A name identifying the DocTest (typically, the name of
 452        the object whose docstring this DocTest was extracted from).
 453
 454      - filename: The name of the file that this DocTest was extracted
 455        from, or `None` if the filename is unknown.
 456
 457      - lineno: The line number within filename where this DocTest
 458        begins, or `None` if the line number is unavailable.  This
 459        line number is zero-based, with respect to the beginning of
 460        the file.
 461
 462      - docstring: The string that the examples were extracted from,
 463        or `None` if the string is unavailable.
 464    """
 465    def __init__(self, examples, globs, name, filename, lineno, docstring):
 466        """
 467        Create a new DocTest containing the given examples.  The
 468        DocTest's globals are initialized with a copy of `globs`.
 469        """
 470        assert not isinstance(examples, basestring), \
 471               "DocTest no longer accepts str; use DocTestParser instead"
 472        self.examples = examples
 473        self.docstring = docstring
 474        self.globs = globs.copy()
 475        self.name = name
 476        self.filename = filename
 477        self.lineno = lineno
 478
 479    def __repr__(self):
 480        if len(self.examples) == 0:
 481            examples = 'no examples'
 482        elif len(self.examples) == 1:
 483            examples = '1 example'
 484        else:
 485            examples = '%d examples' % len(self.examples)
 486        return ('<DocTest %s from %s:%s (%s)>' %
 487                (self.name, self.filename, self.lineno, examples))
 488
 489
 490    # This lets us sort tests by name:
 491    def __cmp__(self, other):
 492        if not isinstance(other, DocTest):
 493            return -1
 494        return cmp((self.name, self.filename, self.lineno, id(self)),
 495                   (other.name, other.filename, other.lineno, id(other)))
 496
 497######################################################################
 498## 3. DocTestParser
 499######################################################################
 500
 501class DocTestParser:
 502    """
 503    A class used to parse strings containing doctest examples.
 504    """
 505    # This regular expression is used to find doctest examples in a
 506    # string.  It defines three groups: `source` is the source code
 507    # (including leading indentation and prompts); `indent` is the
 508    # indentation of the first (PS1) line of the source code; and
 509    # `want` is the expected output (including leading indentation).
 510    _EXAMPLE_RE = re.compile(r'''
 511        # Source consists of a PS1 line followed by zero or more PS2 lines.
 512        (?P<source>
 513            (?:^(?P<indent> [ ]*) >>>    .*)    # PS1 line
 514            (?:\n           [ ]*  \.\.\. .*)*)  # PS2 lines
 515        \n?
 516        # Want consists of any non-blank lines that do not start with PS1.
 517        (?P<want> (?:(?![ ]*$)    # Not a blank line
 518                     (?![ ]*>>>)  # Not a line starting with PS1
 519                     .*$\n?       # But any other line
 520                  )*)
 521        ''', re.MULTILINE | re.VERBOSE)
 522
 523    # A regular expression for handling `want` strings that contain
 524    # expected exceptions.  It divides `want` into three pieces:
 525    #    - the traceback header line (`hdr`)
 526    #    - the traceback stack (`stack`)
 527    #    - the exception message (`msg`), as generated by
 528    #      traceback.format_exception_only()
 529    # `msg` may have multiple lines.  We assume/require that the
 530    # exception message is the first non-indented line starting with a word
 531    # character following the traceback header line.
 532    _EXCEPTION_RE = re.compile(r"""
 533        # Grab the traceback header.  Different versions of Python have
 534        # said different things on the first traceback line.
 535        ^(?P<hdr> Traceback\ \(
 536            (?: most\ recent\ call\ last
 537            |   innermost\ last
 538            ) \) :
 539        )
 540        \s* $                # toss trailing whitespace on the header.
 541        (?P<stack> .*?)      # don't blink: absorb stuff until...
 542        ^ (?P<msg> \w+ .*)   #     a line *starts* with alphanum.
 543        """, re.VERBOSE | re.MULTILINE | re.DOTALL)
 544
 545    # A callable returning a true value iff its argument is a blank line
 546    # or contains a single comment.
 547    _IS_BLANK_OR_COMMENT = re.compile(r'^[ ]*(#.*)?$').match
 548
 549    def parse(self, string, name='<string>'):
 550        """
 551        Divide the given string into examples and intervening text,
 552        and return them as a list of alternating Examples and strings.
 553        Line numbers for the Examples are 0-based.  The optional
 554        argument `name` is a name identifying this string, and is only
 555        used for error messages.
 556        """
 557        string = string.expandtabs()
 558        # If all lines begin with the same indentation, then strip it.
 559        min_indent = self._min_indent(string)
 560        if min_indent > 0:
 561            string = '\n'.join([l[min_indent:] for l in string.split('\n')])
 562
 563        output = []
 564        charno, lineno = 0, 0
 565        # Find all doctest examples in the string:
 566        for m in self._EXAMPLE_RE.finditer(string):
 567            # Add the pre-example text to `output`.
 568            output.append(string[charno:m.start()])
 569            # Update lineno (lines before this example)
 570            lineno += string.count('\n', charno, m.start())
 571            # Extract info from the regexp match.
 572            (source, options, want, exc_msg) = \
 573                     self._parse_example(m, name, lineno)
 574            # Create an Example, and add it to the list.
 575            if not self._IS_BLANK_OR_COMMENT(source):
 576                output.append( Example(source, want, exc_msg,
 577                                    lineno=lineno,
 578                                    indent=min_indent+len(m.group('indent')),
 579                                    options=options) )
 580            # Update lineno (lines inside this example)
 581            lineno += string.count('\n', m.start(), m.end())
 582            # Update charno.
 583            charno = m.end()
 584        # Add any remaining post-example text to `output`.
 585        output.append(string[charno:])
 586        return output
 587
 588    def get_doctest(self, string, globs, name, filename, lineno):
 589        """
 590        Extract all doctest examples from the given string, and
 591        collect them into a `DocTest` object.
 592
 593        `globs`, `name`, `filename`, and `lineno` are attributes for
 594        the new `DocTest` object.  See the documentation for `DocTest`
 595        for more information.
 596        """
 597        return DocTest(self.get_examples(string, name), globs,
 598                       name, filename, lineno, string)
 599
 600    def get_examples(self, string, name='<string>'):
 601        """
 602        Extract all doctest examples from the given string, and return
 603        them as a list of `Example` objects.  Line numbers are
 604        0-based, because it's most common in doctests that nothing
 605        interesting appears on the same line as opening triple-quote,
 606        and so the first interesting line is called \"line 1\" then.
 607
 608        The optional argument `name` is a name identifying this
 609        string, and is only used for error messages.
 610        """
 611        return [x for x in self.parse(string, name)
 612                if isinstance(x, Example)]
 613
 614    def _parse_example(self, m, name, lineno):
 615        """
 616        Given a regular expression match from `_EXAMPLE_RE` (`m`),
 617        return a pair `(source, want)`, where `source` is the matched
 618        example's source code (with prompts and indentation stripped);
 619        and `want` is the example's expected output (with indentation
 620        stripped).
 621
 622        `name` is the string's name, and `lineno` is the line number
 623        where the example starts; both are used for error messages.
 624        """
 625        # Get the example's indentation level.
 626        indent = len(m.group('indent'))
 627
 628        # Divide source into lines; check that they're properly
 629        # indented; and then strip their indentation & prompts.
 630        source_lines = m.group('source').split('\n')
 631        self._check_prompt_blank(source_lines, indent, name, lineno)
 632        self._check_prefix(source_lines[1:], ' '*indent + '.', name, lineno)
 633        source = '\n'.join([sl[indent+4:] for sl in source_lines])
 634
 635        # Divide want into lines; check that it's properly indented; and
 636        # then strip the indentation.  Spaces before the last newline should
 637        # be preserved, so plain rstrip() isn't good enough.
 638        want = m.group('want')
 639        want_lines = want.split('\n')
 640        if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]):
 641            del want_lines[-1]  # forget final newline & spaces after it
 642        self._check_prefix(want_lines, ' '*indent, name,
 643                           lineno + len(source_lines))
 644        want = '\n'.join([wl[indent:] for wl in want_lines])
 645
 646        # If `want` contains a traceback message, then extract it.
 647        m = self._EXCEPTION_RE.match(want)
 648        if m:
 649            exc_msg = m.group('msg')
 650        else:
 651            exc_msg = None
 652
 653        # Extract options from the source.
 654        options = self._find_options(source, name, lineno)
 655
 656        return source, options, want, exc_msg
 657
 658    # This regular expression looks for option directives in the
 659    # source code of an example.  Option directives are comments
 660    # starting with "doctest:".  Warning: this may give false
 661    # positives for string-literals that contain the string
 662    # "#doctest:".  Eliminating these false positives would require
 663    # actually parsing the string; but we limit them by ignoring any
 664    # line containing "#doctest:" that is *followed* by a quote mark.
 665    _OPTION_DIRECTIVE_RE = re.compile(r'#\s*doctest:\s*([^\n\'"]*)$',
 666                                      re.MULTILINE)
 667
 668    def _find_options(self, source, name, lineno):
 669        """
 670        Return a dictionary containing option overrides extracted from
 671        option directives in the given source string.
 672
 673        `name` is the string's name, and `lineno` is the line number
 674        where the example starts; both are used for error messages.
 675        """
 676        options = {}
 677        # (note: with the current regexp, this will match at most once:)
 678        for m in self._OPTION_DIRECTIVE_RE.finditer(source):
 679            option_strings = m.group(1).replace(',', ' ').split()
 680            for option in option_strings:
 681                if (option[0] not in '+-' or
 682                    option[1:] not in OPTIONFLAGS_BY_NAME):
 683                    raise ValueError('line %r of the doctest for %s '
 684                                     'has an invalid option: %r' %
 685                                     (lineno+1, name, option))
 686                flag = OPTIONFLAGS_BY_NAME[option[1:]]
 687                options[flag] = (option[0] == '+')
 688        if options and self._IS_BLANK_OR_COMMENT(source):
 689            raise ValueError('line %r of the doctest for %s has an option '
 690                             'directive on a line with no example: %r' %
 691                             (lineno, name, source))
 692        return options
 693
 694    # This regular expression finds the indentation of every non-blank
 695    # line in a string.
 696    _INDENT_RE = re.compile('^([ ]*)(?=\S)', re.MULTILINE)
 697
 698    def _min_indent(self, s):
 699        "Return the minimum indentation of any non-blank line in `s`"
 700        indents = [len(indent) for indent in self._INDENT_RE.findall(s)]
 701        if len(indents) > 0:
 702            return min(indents)
 703        else:
 704            return 0
 705
 706    def _check_prompt_blank(self, lines, indent, name, lineno):
 707        """
 708        Given the lines of a source string (including prompts and
 709        leading indentation), check to make sure that every prompt is
 710        followed by a space character.  If any line is not followed by
 711        a space character, then raise ValueError.
 712        """
 713        for i, line in enumerate(lines):
 714            if len(line) >= indent+4 and line[indent+3] != ' ':
 715                raise ValueError('line %r of the docstring for %s '
 716                                 'lacks blank after %s: %r' %
 717                                 (lineno+i+1, name,
 718                                  line[indent:indent+3], line))
 719
 720    def _check_prefix(self, lines, prefix, name, lineno):
 721        """
 722        Check that every line in the given list starts with the given
 723        prefix; if any line does not, then raise a ValueError.
 724        """
 725        for i, line in enumerate(lines):
 726            if line and not line.startswith(prefix):
 727                raise ValueError('line %r of the docstring for %s has '
 728                                 'inconsistent leading whitespace: %r' %
 729                                 (lineno+i+1, name, line))
 730
 731
 732######################################################################
 733## 4. DocTest Finder
 734######################################################################
 735
 736class DocTestFinder:
 737    """
 738    A class used to extract the DocTests that are relevant to a given
 739    object, from its docstring and the docstrings of its contained
 740    objects.  Doctests can currently be extracted from the following
 741    object types: modules, functions, classes, methods, staticmethods,
 742    classmethods, and properties.
 743    """
 744
 745    def __init__(self, verbose=False, parser=DocTestParser(),
 746                 recurse=True, exclude_empty=True):
 747        """
 748        Create a new doctest finder.
 749
 750        The optional argument `parser` specifies a class or
 751        function that should be used to create new DocTest objects (or
 752        objects that implement the same interface as DocTest).  The
 753        signature for this factory function should match the signature
 754        of the DocTest constructor.
 755
 756        If the optional argument `recurse` is false, then `find` will
 757        only examine the given object, and not any contained objects.
 758
 759        If the optional argument `exclude_empty` is false, then `find`
 760        will include tests for objects with empty docstrings.
 761        """
 762        self._parser = parser
 763        self._verbose = verbose
 764        self._recurse = recurse
 765        self._exclude_empty = exclude_empty
 766
 767    def find(self, obj, name=None, module=None, globs=None, extraglobs=None):
 768        """
 769        Return a list of the DocTests that are defined by the given
 770        object's docstring, or by any of its contained objects'
 771        docstrings.
 772
 773        The optional parameter `module` is the module that contains
 774        the given object.  If the module is not specified or is None, then
 775        the test finder will attempt to automatically determine the
 776        correct module.  The object's module is used:
 777
 778            - As a default namespace, if `globs` is not specified.
 779            - To prevent the DocTestFinder from extracting DocTests
 780              from objects that are imported from other modules.
 781            - To find the name of the file containing the object.
 782            - To help find the line number of the object within its
 783              file.
 784
 785        Contained objects whose module does not match `module` are ignored.
 786
 787        If `module` is False, no attempt to find the module will be made.
 788        This is obscure, of use mostly in tests:  if `module` is False, or
 789        is None but cannot be found automatically, then all objects are
 790        considered to belong to the (non-existent) module, so all contained
 791        objects will (recursively) be searched for doctests.
 792
 793        The globals for each DocTest is formed by combining `globs`
 794        and `extraglobs` (bindings in `extraglobs` override bindings
 795        in `globs`).  A new copy of the globals dictionary is created
 796        for each DocTest.  If `globs` is not specified, then it
 797        defaults to the module's `__dict__`, if specified, or {}
 798        otherwise.  If `extraglobs` is not specified, then it defaults
 799        to {}.
 800
 801        """
 802        # If name was not specified, then extract it from the object.
 803        if name is None:
 804            name = getattr(obj, '__name__', None)
 805            if name is None:
 806                raise ValueError("DocTestFinder.find: name must be given "
 807                        "when obj.__name__ doesn't exist: %r" %
 808                                 (type(obj),))
 809
 810        # Find the module that contains the given object (if obj is
 811        # a module, then module=obj.).  Note: this may fail, in which
 812        # case module will be None.
 813        if module is False:
 814            module = None
 815        elif module is None:
 816            module = inspect.getmodule(obj)
 817
 818        # Read the module's source code.  This is used by
 819        # DocTestFinder._find_lineno to find the line number for a
 820        # given object's docstring.
 821        try:
 822            file = inspect.getsourcefile(obj) or inspect.getfile(obj)
 823            if module is not None:
 824                # Supply the module globals in case the module was
 825                # originally loaded via a PEP 302 loader and
 826                # file is not a valid filesystem path
 827                source_lines = linecache.getlines(file, module.__dict__)
 828            else:
 829                # No access to a loader, so assume it's a normal
 830                # filesystem path
 831                source_lines = linecache.getlines(file)
 832            if not source_lines:
 833                source_lines = None
 834        except TypeError:
 835            source_lines = None
 836
 837        # Initialize globals, and merge in extraglobs.
 838        if globs is None:
 839            if module is None:
 840                globs = {}
 841            else:
 842                globs = module.__dict__.copy()
 843        else:
 844            globs = globs.copy()
 845        if extraglobs is not None:
 846            globs.update(extraglobs)
 847        if '__name__' not in globs:
 848            globs['__name__'] = '__main__'  # provide a default module name
 849
 850        # Recursively expore `obj`, extracting DocTests.
 851        tests = []
 852        self._find(tests, obj, name, module, source_lines, globs, {})
 853        # Sort the tests by alpha order of names, for consistency in
 854        # verbose-mode output.  This was a feature of doctest in Pythons
 855        # <= 2.3 that got lost by accident in 2.4.  It was repaired in
 856        # 2.4.4 and 2.5.
 857        tests.sort()
 858        return tests
 859
 860    def _from_module(self, module, object):
 861        """
 862        Return true if the given object is defined in the given
 863        module.
 864        """
 865        if module is None:
 866            return True
 867        elif inspect.getmodule(object) is not None:
 868            return module is inspect.getmodule(object)
 869        elif inspect.isfunction(object):
 870            return module.__dict__ is object.func_globals
 871        elif inspect.isclass(object):
 872            return module.__name__ == object.__module__
 873        elif hasattr(object, '__module__'):
 874            return module.__name__ == object.__module__
 875        elif isinstance(object, property):
 876            return True # [XX] no way not be sure.
 877        else:
 878            raise ValueError("object must be a class or function")
 879
 880    def _find(self, tests, obj, name, module, source_lines, globs, seen):
 881        """
 882        Find tests for the given object and any contained objects, and
 883        add them to `tests`.
 884        """
 885        if self._verbose:
 886            print 'Finding tests in %s' % name
 887
 888        # If we've already processed this object, then ignore it.
 889        if id(obj) in seen:
 890            return
 891        seen[id(obj)] = 1
 892
 893        # Find a test for this object, and add it to the list of tests.
 894        test = self._get_test(obj, name, module, globs, source_lines)
 895        if test is not None:
 896            tests.append(test)
 897
 898        # Look for tests in a module's contained objects.
 899        if inspect.ismodule(obj) and self._recurse:
 900            for valname, val in obj.__dict__.items():
 901                valname = '%s.%s' % (name, valname)
 902                # Recurse to functions & classes.
 903                if ((inspect.isfunction(val) or inspect.isclass(val)) and
 904                    self._from_module(module, val)):
 905                    self._find(tests, val, valname, module, source_lines,
 906                               globs, seen)
 907
 908        # Look for tests in a module's __test__ dictionary.
 909        if inspect.ismodule(obj) and self._recurse:
 910            for valname, val in getattr(obj, '__test__', {}).items():
 911                if not isinstance(valname, basestring):
 912                    raise ValueError("DocTestFinder.find: __test__ keys "
 913                                     "must be strings: %r" %
 914                                     (type(valname),))
 915                if not (inspect.isfunction(val) or inspect.isclass(val) or
 916                        inspect.ismethod(val) or inspect.ismodule(val) or
 917                        isinstance(val, basestring)):
 918                    raise ValueError("DocTestFinder.find: __test__ values "
 919                                     "must be strings, functions, methods, "
 920                                     "classes, or modules: %r" %
 921                                     (type(val),))
 922                valname = '%s.__test__.%s' % (name, valname)
 923                self._find(tests, val, valname, module, source_lines,
 924                           globs, seen)
 925
 926        # Look for tests in a class's contained objects.
 927        if inspect.isclass(obj) and self._recurse:
 928            for valname, val in obj.__dict__.items():
 929                # Special handling for staticmethod/classmethod.
 930                if isinstance(val, staticmethod):
 931                    val = getattr(obj, valname)
 932                if isinstance(val, classmethod):
 933                    val = getattr(obj, valname).im_func
 934
 935                # Recurse to methods, properties, and nested classes.
 936                if ((inspect.isfunction(val) or inspect.isclass(val) or
 937                      isinstance(val, property)) and
 938                      self._from_module(module, val)):
 939                    valname = '%s.%s' % (name, valname)
 940                    self._find(tests, val, valname, module, source_lines,
 941                               globs, seen)
 942
 943    def _get_test(self, obj, name, module, globs, source_lines):
 944        """
 945        Return a DocTest for the given object, if it defines a docstring;
 946        otherwise, return None.
 947        """
 948        # Extract the object's docstring.  If it doesn't have one,
 949        # then return None (no test for this object).
 950        if isinstance(obj, basestring):
 951            docstring = obj
 952        else:
 953            try:
 954                if obj.__doc__ is None:
 955                    docstring = ''
 956                else:
 957                    docstring = obj.__doc__
 958                    if not isinstance(docstring, basestring):
 959                        docstring = str(docstring)
 960            except (TypeError, AttributeError):
 961                docstring = ''
 962
 963        # Find the docstring's location in the file.
 964        lineno = self._find_lineno(obj, source_lines)
 965
 966        # Don't bother if the docstring is empty.
 967        if self._exclude_empty and not docstring:
 968            return None
 969
 970        # Return a DocTest for this object.
 971        if module is None:
 972            filename = None
 973        else:
 974            filename = getattr(module, '__file__', module.__name__)
 975            if filename[-4:] in (".pyc", ".pyo"):
 976                filename = filename[:-1]
 977        return self._parser.get_doctest(docstring, globs, name,
 978                                        filename, lineno)
 979
 980    def _find_lineno(self, obj, source_lines):
 981        """
 982        Return a line number of the given object's docstring.  Note:
 983        this method assumes that the object has a docstring.
 984        """
 985        lineno = None
 986
 987        # Find the line number for modules.
 988        if inspect.ismodule(obj):
 989            lineno = 0
 990
 991        # Find the line number for classes.
 992        # Note: this could be fooled if a class is defined multiple
 993        # times in a single file.
 994        if inspect.isclass(obj):
 995            if source_lines is None:
 996                return None
 997            pat = re.compile(r'^\s*class\s*%s\b' %
 998                             getattr(obj, '__name__', '-'))
 999            for i, line in enumerate(source_lines):
1000                if pat.match(line):
1001                    lineno = i
1002                    break
1003
1004        # Find the line number for functions & methods.
1005        if inspect.ismethod(obj): obj = obj.im_func
1006        if inspect.isfunction(obj): obj = obj.func_code
1007        if inspect.istraceback(obj): obj = obj.tb_frame
1008        if inspect.isframe(obj): obj = obj.f_code
1009        if inspect.iscode(obj):
1010            lineno = getattr(obj, 'co_firstlineno', None)-1
1011
1012        # Find the line number where the docstring starts.  Assume
1013        # that it's the first line that begins with a quote mark.
1014        # Note: this could be fooled by a multiline function
1015        # signature, where a continuation line begins with a quote
1016        # mark.
1017        if lineno is not None:
1018            if source_lines is None:
1019                return lineno+1
1020            pat = re.compile('(^|.*:)\s*\w*("|\')')
1021            for lineno in range(lineno, len(source_lines)):
1022                if pat.match(source_lines[lineno]):
1023                    return lineno
1024
1025        # We couldn't find the line number.
1026        return None
1027
1028######################################################################
1029## 5. DocTest Runner
1030######################################################################
1031
1032class DocTestRunner:
1033    """
1034    A class used to run DocTest test cases, and accumulate statistics.
1035    The `run` method is used to process a single DocTest case.  It
1036    returns a tuple `(f, t)`, where `t` is the number of test cases
1037    tried, and `f` is the number of test cases that failed.
1038
1039        >>> tests = DocTestFinder().find(_TestClass)
1040        >>> runner = DocTestRunner(verbose=False)
1041        >>> tests.sort(key = lambda test: test.name)
1042        >>> for test in tests:
1043        ...     print test.name, '->', runner.run(test)
1044        _TestClass -> TestResults(failed=0, attempted=2)
1045        _TestClass.__init__ -> TestResults(failed=0, attempted=2)
1046        _TestClass.get -> TestResults(failed=0, attempted=2)
1047        _TestClass.square -> TestResults(failed=0, attempted=1)
1048
1049    The `summarize` method prints a summary of all the test cases that
1050    have been run by the runner, and returns an aggregated `(f, t)`
1051    tuple:
1052
1053        >>> runner.summarize(verbose=1)
1054        4 items passed all tests:
1055           2 tests in _TestClass
1056           2 tests in _TestClass.__init__
1057           2 tests in _TestClass.get
1058           1 tests in _TestClass.square
1059        7 tests in 4 items.
1060        7 passed and 0 failed.
1061        Test passed.
1062        TestResults(failed=0, attempted=7)
1063
1064    The aggregated number of tried examples and failed examples is
1065    also available via the `tries` and `failures` attributes:
1066
1067        >>> runner.tries
1068        7
1069        >>> runner.failures
1070        0
1071
1072    The comparison between expected outputs and actual outputs is done
1073    by an `OutputChecker`.  This comparison may be customized with a
1074    number of option flags; see the documentation for `testmod` for
1075    more information.  If the option flags are insufficient, then the
1076    comparison may also be customized by passing a subclass of
1077    `OutputChecker` to the constructor.
1078
1079    The test runner's display output can be controlled in two ways.
1080    First, an output function (`out) can be passed to
1081    `TestRunner.run`; this function will be called with strings that
1082    should be displayed.  It defaults to `sys.stdout.write`.  If
1083    capturing the output is not sufficient, then the display output
1084    can be also customized by subclassing DocTestRunner, and
1085    overriding the methods `report_start`, `report_success`,
1086    `report_unexpected_exception`, and `report_failure`.
1087    """
1088    # This divider string is used to separate failure messages, and to
1089    # separate sections of the summary.
1090    DIVIDER = "*" * 70
1091
1092    def __init__(self, checker=None, verbose=None, optionflags=0):
1093        """
1094        Create a new test runner.
1095
1096        Optional keyword arg `checker` is the `OutputChecker` that
1097        should be used to compare the expected outputs and actual
1098        outputs of doctest examples.
1099
1100        Optional keyword arg 'verbose' prints lots of stuff if true,
1101        only failures if false; by default, it's true iff '-v' is in
1102        sys.argv.
1103
1104        Optional argument `optionflags` can be used to control how the
1105        test runner compares expected output to actual output, and how
1106        it displays failures.  See the documentation for `testmod` for
1107        more information.
1108        """
1109        self._checker = checker or OutputChecker()
1110        if verbose is None:
1111            verbose = '-v' in sys.argv
1112        self._verbose = verbose
1113        self.optionflags = optionflags
1114        self.original_optionflags = optionflags
1115
1116        # Keep track of the examples we've run.
1117        self.tries = 0
1118        self.failures = 0
1119        self._name2ft = {}
1120
1121        # Create a fake output target for capturing doctest output.
1122        self._fakeout = _SpoofOut()
1123
1124    #/////////////////////////////////////////////////////////////////
1125    # Reporting methods
1126    #/////////////////////////////////////////////////////////////////
1127
1128    def report_start(self, out, test, example):
1129        """
1130        Report that the test runner is about to process the given
1131        example.  (Only displays a message if verbose=True)
1132        """
1133        if self._verbose:
1134            if example.want:
1135                out('Trying:\n' + _indent(example.source) +
1136                    'Expecting:\n' + _indent(example.want))
1137            else:
1138                out('Trying:\n' + _indent(example.source) +
1139                    'Expecting nothing\n')
1140
1141    def report_success(self, out, test, example, got):
1142        """
1143        Report that the given example ran successfully.  (Only
1144        displays a message if verbose=True)
1145        """
1146        if self._verbose:
1147            out("ok\n")
1148
1149    def report_failure(self, out, test, example, got):
1150        """
1151        Report that the given example failed.
1152        """
1153        out(self._failure_header(test, example) +
1154            self._checker.output_difference(example, got, self.optionflags))
1155
1156    def report_unexpected_exception(self, out, test, example, exc_info):
1157        """
1158        Report that the given example raised an unexpected exception.
1159        """
1160        out(self._failure_header(test, example) +
1161            'Exception raised:\n' + _indent(_exception_traceback(exc_info)))
1162
1163    def _failure_header(self, test, example):
1164        out = [self.DIVIDER]
1165        if test.filename:
1166            if test.lineno is not None and example.lineno is not None:
1167                lineno = test.lineno + example.lineno + 1
1168            else:
1169                lineno = '?'
1170            out.append('File "%s", line %s, in %s' %
1171                       (test.filename, lineno, test.name))
1172        else:
1173            out.append('Line %s, in %s' % (example.lineno+1, test.name))
1174        out.append('Failed example:')
1175        source = example.source
1176        out.append(_indent(source))
1177        return '\n'.join(out)
1178
1179    #/////////////////////////////////////////////////////////////////
1180    # DocTest Running
1181    #/////////////////////////////////////////////////////////////////
1182
1183    def __run(self, test, compileflags, out):
1184        """
1185        Run the examples in `test`.  Write the outcome of each example
1186        with one of the `DocTestRunner.report_*` methods, using the
1187        writer function `out`.  `compileflags` is the set of compiler
1188        flags that should be used to execute examples.  Return a tuple
1189        `(f, t)`, where `t` is the number of examples tried, and `f`
1190        is the number of examples that failed.  The examples are run
1191        in the namespace `test.globs`.
1192        """
1193        # Keep track of the number of failures and tries.
1194        failures = tries = 0
1195
1196        # Save the option flags (since option directives can be used
1197        # to modify them).
1198        original_optionflags = self.optionflags
1199
1200        SUCCESS, FAILURE, BOOM = range(3) # `outcome` state
1201
1202        check = self._checker.check_output
1203
1204        # Process each example.
1205        for examplenum, example in enumerate(test.examples):
1206
1207            # If REPORT_ONLY_FIRST_FAILURE is set, then supress
1208            # reporting after the first failure.
1209            quiet = (self.optionflags & REPORT_ONLY_FIRST_FAILURE and
1210                     failures > 0)
1211
1212            # Merge in the example's options.
1213            self.optionflags = original_optionflags
1214            if example.options:
1215                for (optionflag, val) in example.options.items():
1216                    if val:
1217                        self.optionflags |= optionflag
1218                    else:
1219                        self.optionflags &= ~optionflag
1220
1221            # If 'SKIP' is set, then skip this example.
1222            if self.optionflags & SKIP:
1223                continue
1224
1225            # Record that we started this example.
1226            tries += 1
1227            if not quiet:
1228                self.report_start(out, test, example)
1229
1230            # Use a special filename for compile(), so we can retrieve
1231            # the source code during interactive debugging (see
1232            # __patched_linecache_getlines).
1233            filename = '<doctest %s[%d]>' % (test.name, examplenum)
1234
1235            # Run the example in the given context (globs), and record
1236            # any exception that gets raised.  (But don't intercept
1237            # keyboard interrupts.)
1238            try:
1239                # Don't blink!  This is where the user's code gets run.
1240                exec compile(example.source, filename, "single",
1241                             compileflags, 1) in test.globs
1242                self.debugger.set_continue() # ==== Example Finished ====
1243                exception = None
1244            except KeyboardInterrupt:
1245                raise
1246            except:
1247                exception = sys.exc_info()
1248                self.debugger.set_continue() # ==== Example Finished ====
1249
1250            got = self._fakeout.getvalue()  # the actual output
1251            self._fakeout.truncate(0)
1252            outcome = FAILURE   # guilty until proved innocent or insane
1253
1254            # If the example executed without raising any exceptions,
1255   

Large files files are truncated, but you can click here to view the full file