Lib/doctest.py

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