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