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