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