/Lib/doctest.py
Python | 2686 lines | 2629 code | 13 blank | 44 comment | 38 complexity | 7d583fc0f10531949ea1ba679be0b68e MD5 | raw file
Large files files are truncated, but you can click here to view the full file
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 if module is not None: 824 # Supply the module globals in case the module was 825 # originally loaded via a PEP 302 loader and 826 # file is not a valid filesystem path 827 source_lines = linecache.getlines(file, module.__dict__) 828 else: 829 # No access to a loader, so assume it's a normal 830 # filesystem path 831 source_lines = linecache.getlines(file) 832 if not source_lines: 833 source_lines = None 834 except TypeError: 835 source_lines = None 836 837 # Initialize globals, and merge in extraglobs. 838 if globs is None: 839 if module is None: 840 globs = {} 841 else: 842 globs = module.__dict__.copy() 843 else: 844 globs = globs.copy() 845 if extraglobs is not None: 846 globs.update(extraglobs) 847 if '__name__' not in globs: 848 globs['__name__'] = '__main__' # provide a default module name 849 850 # Recursively expore `obj`, extracting DocTests. 851 tests = [] 852 self._find(tests, obj, name, module, source_lines, globs, {}) 853 # Sort the tests by alpha order of names, for consistency in 854 # verbose-mode output. This was a feature of doctest in Pythons 855 # <= 2.3 that got lost by accident in 2.4. It was repaired in 856 # 2.4.4 and 2.5. 857 tests.sort() 858 return tests 859 860 def _from_module(self, module, object): 861 """ 862 Return true if the given object is defined in the given 863 module. 864 """ 865 if module is None: 866 return True 867 elif inspect.getmodule(object) is not None: 868 return module is inspect.getmodule(object) 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 hasattr(object, '__module__'): 874 return module.__name__ == object.__module__ 875 elif isinstance(object, property): 876 return True # [XX] no way not be sure. 877 else: 878 raise ValueError("object must be a class or function") 879 880 def _find(self, tests, obj, name, module, source_lines, globs, seen): 881 """ 882 Find tests for the given object and any contained objects, and 883 add them to `tests`. 884 """ 885 if self._verbose: 886 print 'Finding tests in %s' % name 887 888 # If we've already processed this object, then ignore it. 889 if id(obj) in seen: 890 return 891 seen[id(obj)] = 1 892 893 # Find a test for this object, and add it to the list of tests. 894 test = self._get_test(obj, name, module, globs, source_lines) 895 if test is not None: 896 tests.append(test) 897 898 # Look for tests in a module's contained objects. 899 if inspect.ismodule(obj) and self._recurse: 900 for valname, val in obj.__dict__.items(): 901 valname = '%s.%s' % (name, valname) 902 # Recurse to functions & classes. 903 if ((inspect.isfunction(val) or inspect.isclass(val)) and 904 self._from_module(module, val)): 905 self._find(tests, val, valname, module, source_lines, 906 globs, seen) 907 908 # Look for tests in a module's __test__ dictionary. 909 if inspect.ismodule(obj) and self._recurse: 910 for valname, val in getattr(obj, '__test__', {}).items(): 911 if not isinstance(valname, basestring): 912 raise ValueError("DocTestFinder.find: __test__ keys " 913 "must be strings: %r" % 914 (type(valname),)) 915 if not (inspect.isfunction(val) or inspect.isclass(val) or 916 inspect.ismethod(val) or inspect.ismodule(val) or 917 isinstance(val, basestring)): 918 raise ValueError("DocTestFinder.find: __test__ values " 919 "must be strings, functions, methods, " 920 "classes, or modules: %r" % 921 (type(val),)) 922 valname = '%s.__test__.%s' % (name, valname) 923 self._find(tests, val, valname, module, source_lines, 924 globs, seen) 925 926 # Look for tests in a class's contained objects. 927 if inspect.isclass(obj) and self._recurse: 928 for valname, val in obj.__dict__.items(): 929 # Special handling for staticmethod/classmethod. 930 if isinstance(val, staticmethod): 931 val = getattr(obj, valname) 932 if isinstance(val, classmethod): 933 val = getattr(obj, valname).im_func 934 935 # Recurse to methods, properties, and nested classes. 936 if ((inspect.isfunction(val) or inspect.isclass(val) or 937 isinstance(val, property)) and 938 self._from_module(module, val)): 939 valname = '%s.%s' % (name, valname) 940 self._find(tests, val, valname, module, source_lines, 941 globs, seen) 942 943 def _get_test(self, obj, name, module, globs, source_lines): 944 """ 945 Return a DocTest for the given object, if it defines a docstring; 946 otherwise, return None. 947 """ 948 # Extract the object's docstring. If it doesn't have one, 949 # then return None (no test for this object). 950 if isinstance(obj, basestring): 951 docstring = obj 952 else: 953 try: 954 if obj.__doc__ is None: 955 docstring = '' 956 else: 957 docstring = obj.__doc__ 958 if not isinstance(docstring, basestring): 959 docstring = str(docstring) 960 except (TypeError, AttributeError): 961 docstring = '' 962 963 # Find the docstring's location in the file. 964 lineno = self._find_lineno(obj, source_lines) 965 966 # Don't bother if the docstring is empty. 967 if self._exclude_empty and not docstring: 968 return None 969 970 # Return a DocTest for this object. 971 if module is None: 972 filename = None 973 else: 974 filename = getattr(module, '__file__', module.__name__) 975 if filename[-4:] in (".pyc", ".pyo"): 976 filename = filename[:-1] 977 return self._parser.get_doctest(docstring, globs, name, 978 filename, lineno) 979 980 def _find_lineno(self, obj, source_lines): 981 """ 982 Return a line number of the given object's docstring. Note: 983 this method assumes that the object has a docstring. 984 """ 985 lineno = None 986 987 # Find the line number for modules. 988 if inspect.ismodule(obj): 989 lineno = 0 990 991 # Find the line number for classes. 992 # Note: this could be fooled if a class is defined multiple 993 # times in a single file. 994 if inspect.isclass(obj): 995 if source_lines is None: 996 return None 997 pat = re.compile(r'^\s*class\s*%s\b' % 998 getattr(obj, '__name__', '-')) 999 for i, line in enumerate(source_lines): 1000 if pat.match(line): 1001 lineno = i 1002 break 1003 1004 # Find the line number for functions & methods. 1005 if inspect.ismethod(obj): obj = obj.im_func 1006 if inspect.isfunction(obj): obj = obj.func_code 1007 if inspect.istraceback(obj): obj = obj.tb_frame 1008 if inspect.isframe(obj): obj = obj.f_code 1009 if inspect.iscode(obj): 1010 lineno = getattr(obj, 'co_firstlineno', None)-1 1011 1012 # Find the line number where the docstring starts. Assume 1013 # that it's the first line that begins with a quote mark. 1014 # Note: this could be fooled by a multiline function 1015 # signature, where a continuation line begins with a quote 1016 # mark. 1017 if lineno is not None: 1018 if source_lines is None: 1019 return lineno+1 1020 pat = re.compile('(^|.*:)\s*\w*("|\')') 1021 for lineno in range(lineno, len(source_lines)): 1022 if pat.match(source_lines[lineno]): 1023 return lineno 1024 1025 # We couldn't find the line number. 1026 return None 1027 1028###################################################################### 1029## 5. DocTest Runner 1030###################################################################### 1031 1032class DocTestRunner: 1033 """ 1034 A class used to run DocTest test cases, and accumulate statistics. 1035 The `run` method is used to process a single DocTest case. It 1036 returns a tuple `(f, t)`, where `t` is the number of test cases 1037 tried, and `f` is the number of test cases that failed. 1038 1039 >>> tests = DocTestFinder().find(_TestClass) 1040 >>> runner = DocTestRunner(verbose=False) 1041 >>> tests.sort(key = lambda test: test.name) 1042 >>> for test in tests: 1043 ... print test.name, '->', runner.run(test) 1044 _TestClass -> TestResults(failed=0, attempted=2) 1045 _TestClass.__init__ -> TestResults(failed=0, attempted=2) 1046 _TestClass.get -> TestResults(failed=0, attempted=2) 1047 _TestClass.square -> TestResults(failed=0, attempted=1) 1048 1049 The `summarize` method prints a summary of all the test cases that 1050 have been run by the runner, and returns an aggregated `(f, t)` 1051 tuple: 1052 1053 >>> runner.summarize(verbose=1) 1054 4 items passed all tests: 1055 2 tests in _TestClass 1056 2 tests in _TestClass.__init__ 1057 2 tests in _TestClass.get 1058 1 tests in _TestClass.square 1059 7 tests in 4 items. 1060 7 passed and 0 failed. 1061 Test passed. 1062 TestResults(failed=0, attempted=7) 1063 1064 The aggregated number of tried examples and failed examples is 1065 also available via the `tries` and `failures` attributes: 1066 1067 >>> runner.tries 1068 7 1069 >>> runner.failures 1070 0 1071 1072 The comparison between expected outputs and actual outputs is done 1073 by an `OutputChecker`. This comparison may be customized with a 1074 number of option flags; see the documentation for `testmod` for 1075 more information. If the option flags are insufficient, then the 1076 comparison may also be customized by passing a subclass of 1077 `OutputChecker` to the constructor. 1078 1079 The test runner's display output can be controlled in two ways. 1080 First, an output function (`out) can be passed to 1081 `TestRunner.run`; this function will be called with strings that 1082 should be displayed. It defaults to `sys.stdout.write`. If 1083 capturing the output is not sufficient, then the display output 1084 can be also customized by subclassing DocTestRunner, and 1085 overriding the methods `report_start`, `report_success`, 1086 `report_unexpected_exception`, and `report_failure`. 1087 """ 1088 # This divider string is used to separate failure messages, and to 1089 # separate sections of the summary. 1090 DIVIDER = "*" * 70 1091 1092 def __init__(self, checker=None, verbose=None, optionflags=0): 1093 """ 1094 Create a new test runner. 1095 1096 Optional keyword arg `checker` is the `OutputChecker` that 1097 should be used to compare the expected outputs and actual 1098 outputs of doctest examples. 1099 1100 Optional keyword arg 'verbose' prints lots of stuff if true, 1101 only failures if false; by default, it's true iff '-v' is in 1102 sys.argv. 1103 1104 Optional argument `optionflags` can be used to control how the 1105 test runner compares expected output to actual output, and how 1106 it displays failures. See the documentation for `testmod` for 1107 more information. 1108 """ 1109 self._checker = checker or OutputChecker() 1110 if verbose is None: 1111 verbose = '-v' in sys.argv 1112 self._verbose = verbose 1113 self.optionflags = optionflags 1114 self.original_optionflags = optionflags 1115 1116 # Keep track of the examples we've run. 1117 self.tries = 0 1118 self.failures = 0 1119 self._name2ft = {} 1120 1121 # Create a fake output target for capturing doctest output. 1122 self._fakeout = _SpoofOut() 1123 1124 #///////////////////////////////////////////////////////////////// 1125 # Reporting methods 1126 #///////////////////////////////////////////////////////////////// 1127 1128 def report_start(self, out, test, example): 1129 """ 1130 Report that the test runner is about to process the given 1131 example. (Only displays a message if verbose=True) 1132 """ 1133 if self._verbose: 1134 if example.want: 1135 out('Trying:\n' + _indent(example.source) + 1136 'Expecting:\n' + _indent(example.want)) 1137 else: 1138 out('Trying:\n' + _indent(example.source) + 1139 'Expecting nothing\n') 1140 1141 def report_success(self, out, test, example, got): 1142 """ 1143 Report that the given example ran successfully. (Only 1144 displays a message if verbose=True) 1145 """ 1146 if self._verbose: 1147 out("ok\n") 1148 1149 def report_failure(self, out, test, example, got): 1150 """ 1151 Report that the given example failed. 1152 """ 1153 out(self._failure_header(test, example) + 1154 self._checker.output_difference(example, got, self.optionflags)) 1155 1156 def report_unexpected_exception(self, out, test, example, exc_info): 1157 """ 1158 Report that the given example raised an unexpected exception. 1159 """ 1160 out(self._failure_header(test, example) + 1161 'Exception raised:\n' + _indent(_exception_traceback(exc_info))) 1162 1163 def _failure_header(self, test, example): 1164 out = [self.DIVIDER] 1165 if test.filename: 1166 if test.lineno is not None and example.lineno is not None: 1167 lineno = test.lineno + example.lineno + 1 1168 else: 1169 lineno = '?' 1170 out.append('File "%s", line %s, in %s' % 1171 (test.filename, lineno, test.name)) 1172 else: 1173 out.append('Line %s, in %s' % (example.lineno+1, test.name)) 1174 out.append('Failed example:') 1175 source = example.source 1176 out.append(_indent(source)) 1177 return '\n'.join(out) 1178 1179 #///////////////////////////////////////////////////////////////// 1180 # DocTest Running 1181 #///////////////////////////////////////////////////////////////// 1182 1183 def __run(self, test, compileflags, out): 1184 """ 1185 Run the examples in `test`. Write the outcome of each example 1186 with one of the `DocTestRunner.report_*` methods, using the 1187 writer function `out`. `compileflags` is the set of compiler 1188 flags that should be used to execute examples. Return a tuple 1189 `(f, t)`, where `t` is the number of examples tried, and `f` 1190 is the number of examples that failed. The examples are run 1191 in the namespace `test.globs`. 1192 """ 1193 # Keep track of the number of failures and tries. 1194 failures = tries = 0 1195 1196 # Save the option flags (since option directives can be used 1197 # to modify them). 1198 original_optionflags = self.optionflags 1199 1200 SUCCESS, FAILURE, BOOM = range(3) # `outcome` state 1201 1202 check = self._checker.check_output 1203 1204 # Process each example. 1205 for examplenum, example in enumerate(test.examples): 1206 1207 # If REPORT_ONLY_FIRST_FAILURE is set, then supress 1208 # reporting after the first failure. 1209 quiet = (self.optionflags & REPORT_ONLY_FIRST_FAILURE and 1210 failures > 0) 1211 1212 # Merge in the example's options. 1213 self.optionflags = original_optionflags 1214 if example.options: 1215 for (optionflag, val) in example.options.items(): 1216 if val: 1217 self.optionflags |= optionflag 1218 else: 1219 self.optionflags &= ~optionflag 1220 1221 # If 'SKIP' is set, then skip this example. 1222 if self.optionflags & SKIP: 1223 continue 1224 1225 # Record that we started this example. 1226 tries += 1 1227 if not quiet: 1228 self.report_start(out, test, example) 1229 1230 # Use a special filename for compile(), so we can retrieve 1231 # the source code during interactive debugging (see 1232 # __patched_linecache_getlines). 1233 filename = '<doctest %s[%d]>' % (test.name, examplenum) 1234 1235 # Run the example in the given context (globs), and record 1236 # any exception that gets raised. (But don't intercept 1237 # keyboard interrupts.) 1238 try: 1239 # Don't blink! This is where the user's code gets run. 1240 exec compile(example.source, filename, "single", 1241 compileflags, 1) in test.globs 1242 self.debugger.set_continue() # ==== Example Finished ==== 1243 exception = None 1244 except KeyboardInterrupt: 1245 raise 1246 except: 1247 exception = sys.exc_info() 1248 self.debugger.set_continue() # ==== Example Finished ==== 1249 1250 got = self._fakeout.getvalue() # the actual output 1251 self._fakeout.truncate(0) 1252 outcome = FAILURE # guilty until proved innocent or insane 1253 1254 # If the example executed without raising any exceptions, 1255 …
Large files files are truncated, but you can click here to view the full file