PageRenderTime 271ms CodeModel.GetById 92ms app.highlight 120ms RepoModel.GetById 34ms app.codeStats 2ms

/lib-python/2.7/doctest.py

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

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