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