/Lib/doctest.py

http://unladen-swallow.googlecode.com/ · Python · 2686 lines · 1927 code · 203 blank · 556 comment · 254 complexity · 7d583fc0f10531949ea1ba679be0b68e MD5 · raw file

Large files are truncated 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. # Provided as-is; use at your own risk; no warranty; no promises; enjoy!
  7. r"""Module doctest -- a framework for running examples in docstrings.
  8. In simplest use, end each module M to be tested with:
  9. def _test():
  10. import doctest
  11. doctest.testmod()
  12. if __name__ == "__main__":
  13. _test()
  14. Then running the module as a script will cause the examples in the
  15. docstrings to get executed and verified:
  16. python M.py
  17. This won't display anything unless an example fails, in which case the
  18. failing example(s) and the cause(s) of the failure(s) are printed to stdout
  19. (why not stderr? because stderr is a lame hack <0.2 wink>), and the final
  20. line of output is "Test failed.".
  21. Run it with the -v switch instead:
  22. python M.py -v
  23. and a detailed report of all examples tried is printed to stdout, along
  24. with assorted summaries at the end.
  25. You can force verbose mode by passing "verbose=True" to testmod, or prohibit
  26. it by passing "verbose=False". In either of those cases, sys.argv is not
  27. examined by testmod.
  28. There are a variety of other ways to run doctests, including integration
  29. with the unittest framework, and support for running non-Python text
  30. files containing doctests. There are also many ways to override parts
  31. of doctest's default behaviors. See the Library Reference Manual for
  32. details.
  33. """
  34. __docformat__ = 'reStructuredText en'
  35. __all__ = [
  36. # 0, Option Flags
  37. 'register_optionflag',
  38. 'DONT_ACCEPT_TRUE_FOR_1',
  39. 'DONT_ACCEPT_BLANKLINE',
  40. 'NORMALIZE_WHITESPACE',
  41. 'ELLIPSIS',
  42. 'SKIP',
  43. 'IGNORE_EXCEPTION_DETAIL',
  44. 'COMPARISON_FLAGS',
  45. 'REPORT_UDIFF',
  46. 'REPORT_CDIFF',
  47. 'REPORT_NDIFF',
  48. 'REPORT_ONLY_FIRST_FAILURE',
  49. 'REPORTING_FLAGS',
  50. # 1. Utility Functions
  51. # 2. Example & DocTest
  52. 'Example',
  53. 'DocTest',
  54. # 3. Doctest Parser
  55. 'DocTestParser',
  56. # 4. Doctest Finder
  57. 'DocTestFinder',
  58. # 5. Doctest Runner
  59. 'DocTestRunner',
  60. 'OutputChecker',
  61. 'DocTestFailure',
  62. 'UnexpectedException',
  63. 'DebugRunner',
  64. # 6. Test Functions
  65. 'testmod',
  66. 'testfile',
  67. 'run_docstring_examples',
  68. # 7. Tester
  69. 'Tester',
  70. # 8. Unittest Support
  71. 'DocTestSuite',
  72. 'DocFileSuite',
  73. 'set_unittest_reportflags',
  74. # 9. Debugging Support
  75. 'script_from_examples',
  76. 'testsource',
  77. 'debug_src',
  78. 'debug',
  79. ]
  80. import __future__
  81. import sys, traceback, inspect, linecache, os, re
  82. import unittest, difflib, pdb, tempfile
  83. import warnings
  84. from StringIO import StringIO
  85. from collections import namedtuple
  86. TestResults = namedtuple('TestResults', 'failed attempted')
  87. # There are 4 basic classes:
  88. # - Example: a <source, want> pair, plus an intra-docstring line number.
  89. # - DocTest: a collection of examples, parsed from a docstring, plus
  90. # info about where the docstring came from (name, filename, lineno).
  91. # - DocTestFinder: extracts DocTests from a given object's docstring and
  92. # its contained objects' docstrings.
  93. # - DocTestRunner: runs DocTest cases, and accumulates statistics.
  94. #
  95. # So the basic picture is:
  96. #
  97. # list of:
  98. # +------+ +---------+ +-------+
  99. # |object| --DocTestFinder-> | DocTest | --DocTestRunner-> |results|
  100. # +------+ +---------+ +-------+
  101. # | Example |
  102. # | ... |
  103. # | Example |
  104. # +---------+
  105. # Option constants.
  106. OPTIONFLAGS_BY_NAME = {}
  107. def register_optionflag(name):
  108. # Create a new flag unless `name` is already known.
  109. return OPTIONFLAGS_BY_NAME.setdefault(name, 1 << len(OPTIONFLAGS_BY_NAME))
  110. DONT_ACCEPT_TRUE_FOR_1 = register_optionflag('DONT_ACCEPT_TRUE_FOR_1')
  111. DONT_ACCEPT_BLANKLINE = register_optionflag('DONT_ACCEPT_BLANKLINE')
  112. NORMALIZE_WHITESPACE = register_optionflag('NORMALIZE_WHITESPACE')
  113. ELLIPSIS = register_optionflag('ELLIPSIS')
  114. SKIP = register_optionflag('SKIP')
  115. IGNORE_EXCEPTION_DETAIL = register_optionflag('IGNORE_EXCEPTION_DETAIL')
  116. COMPARISON_FLAGS = (DONT_ACCEPT_TRUE_FOR_1 |
  117. DONT_ACCEPT_BLANKLINE |
  118. NORMALIZE_WHITESPACE |
  119. ELLIPSIS |
  120. SKIP |
  121. IGNORE_EXCEPTION_DETAIL)
  122. REPORT_UDIFF = register_optionflag('REPORT_UDIFF')
  123. REPORT_CDIFF = register_optionflag('REPORT_CDIFF')
  124. REPORT_NDIFF = register_optionflag('REPORT_NDIFF')
  125. REPORT_ONLY_FIRST_FAILURE = register_optionflag('REPORT_ONLY_FIRST_FAILURE')
  126. REPORTING_FLAGS = (REPORT_UDIFF |
  127. REPORT_CDIFF |
  128. REPORT_NDIFF |
  129. REPORT_ONLY_FIRST_FAILURE)
  130. # Special string markers for use in `want` strings:
  131. BLANKLINE_MARKER = '<BLANKLINE>'
  132. ELLIPSIS_MARKER = '...'
  133. ######################################################################
  134. ## Table of Contents
  135. ######################################################################
  136. # 1. Utility Functions
  137. # 2. Example & DocTest -- store test cases
  138. # 3. DocTest Parser -- extracts examples from strings
  139. # 4. DocTest Finder -- extracts test cases from objects
  140. # 5. DocTest Runner -- runs test cases
  141. # 6. Test Functions -- convenient wrappers for testing
  142. # 7. Tester Class -- for backwards compatibility
  143. # 8. Unittest Support
  144. # 9. Debugging Support
  145. # 10. Example Usage
  146. ######################################################################
  147. ## 1. Utility Functions
  148. ######################################################################
  149. def _extract_future_flags(globs):
  150. """
  151. Return the compiler-flags associated with the future features that
  152. have been imported into the given namespace (globs).
  153. """
  154. flags = 0
  155. for fname in __future__.all_feature_names:
  156. feature = globs.get(fname, None)
  157. if feature is getattr(__future__, fname):
  158. flags |= feature.compiler_flag
  159. return flags
  160. def _normalize_module(module, depth=2):
  161. """
  162. Return the module specified by `module`. In particular:
  163. - If `module` is a module, then return module.
  164. - If `module` is a string, then import and return the
  165. module with that name.
  166. - If `module` is None, then return the calling module.
  167. The calling module is assumed to be the module of
  168. the stack frame at the given depth in the call stack.
  169. """
  170. if inspect.ismodule(module):
  171. return module
  172. elif isinstance(module, (str, unicode)):
  173. return __import__(module, globals(), locals(), ["*"])
  174. elif module is None:
  175. return sys.modules[sys._getframe(depth).f_globals['__name__']]
  176. else:
  177. raise TypeError("Expected a module, string, or None")
  178. def _load_testfile(filename, package, module_relative):
  179. if module_relative:
  180. package = _normalize_module(package, 3)
  181. filename = _module_relative_path(package, filename)
  182. if hasattr(package, '__loader__'):
  183. if hasattr(package.__loader__, 'get_data'):
  184. file_contents = package.__loader__.get_data(filename)
  185. # get_data() opens files as 'rb', so one must do the equivalent
  186. # conversion as universal newlines would do.
  187. return file_contents.replace(os.linesep, '\n'), filename
  188. return open(filename).read(), filename
  189. def _indent(s, indent=4):
  190. """
  191. Add the given number of space characters to the beginning every
  192. non-blank line in `s`, and return the result.
  193. """
  194. # This regexp matches the start of non-blank lines:
  195. return re.sub('(?m)^(?!$)', indent*' ', s)
  196. def _exception_traceback(exc_info):
  197. """
  198. Return a string containing a traceback message for the given
  199. exc_info tuple (as returned by sys.exc_info()).
  200. """
  201. # Get a traceback message.
  202. excout = StringIO()
  203. exc_type, exc_val, exc_tb = exc_info
  204. traceback.print_exception(exc_type, exc_val, exc_tb, file=excout)
  205. return excout.getvalue()
  206. # Override some StringIO methods.
  207. class _SpoofOut(StringIO):
  208. def getvalue(self):
  209. result = StringIO.getvalue(self)
  210. # If anything at all was written, make sure there's a trailing
  211. # newline. There's no way for the expected output to indicate
  212. # that a trailing newline is missing.
  213. if result and not result.endswith("\n"):
  214. result += "\n"
  215. # Prevent softspace from screwing up the next test case, in
  216. # case they used print with a trailing comma in an example.
  217. if hasattr(self, "softspace"):
  218. del self.softspace
  219. return result
  220. def truncate(self, size=None):
  221. StringIO.truncate(self, size)
  222. if hasattr(self, "softspace"):
  223. del self.softspace
  224. # Worst-case linear-time ellipsis matching.
  225. def _ellipsis_match(want, got):
  226. """
  227. Essentially the only subtle case:
  228. >>> _ellipsis_match('aa...aa', 'aaa')
  229. False
  230. """
  231. if ELLIPSIS_MARKER not in want:
  232. return want == got
  233. # Find "the real" strings.
  234. ws = want.split(ELLIPSIS_MARKER)
  235. assert len(ws) >= 2
  236. # Deal with exact matches possibly needed at one or both ends.
  237. startpos, endpos = 0, len(got)
  238. w = ws[0]
  239. if w: # starts with exact match
  240. if got.startswith(w):
  241. startpos = len(w)
  242. del ws[0]
  243. else:
  244. return False
  245. w = ws[-1]
  246. if w: # ends with exact match
  247. if got.endswith(w):
  248. endpos -= len(w)
  249. del ws[-1]
  250. else:
  251. return False
  252. if startpos > endpos:
  253. # Exact end matches required more characters than we have, as in
  254. # _ellipsis_match('aa...aa', 'aaa')
  255. return False
  256. # For the rest, we only need to find the leftmost non-overlapping
  257. # match for each piece. If there's no overall match that way alone,
  258. # there's no overall match period.
  259. for w in ws:
  260. # w may be '' at times, if there are consecutive ellipses, or
  261. # due to an ellipsis at the start or end of `want`. That's OK.
  262. # Search for an empty string succeeds, and doesn't change startpos.
  263. startpos = got.find(w, startpos, endpos)
  264. if startpos < 0:
  265. return False
  266. startpos += len(w)
  267. return True
  268. def _comment_line(line):
  269. "Return a commented form of the given line"
  270. line = line.rstrip()
  271. if line:
  272. return '# '+line
  273. else:
  274. return '#'
  275. class _OutputRedirectingPdb(pdb.Pdb):
  276. """
  277. A specialized version of the python debugger that redirects stdout
  278. to a given stream when interacting with the user. Stdout is *not*
  279. redirected when traced code is executed.
  280. """
  281. def __init__(self, out):
  282. self.__out = out
  283. self.__debugger_used = False
  284. pdb.Pdb.__init__(self, stdout=out)
  285. def set_trace(self, frame=None):
  286. self.__debugger_used = True
  287. if frame is None:
  288. frame = sys._getframe().f_back
  289. pdb.Pdb.set_trace(self, frame)
  290. def set_continue(self):
  291. # Calling set_continue unconditionally would break unit test
  292. # coverage reporting, as Bdb.set_continue calls sys.settrace(None).
  293. if self.__debugger_used:
  294. pdb.Pdb.set_continue(self)
  295. def trace_dispatch(self, *args):
  296. # Redirect stdout to the given stream.
  297. save_stdout = sys.stdout
  298. sys.stdout = self.__out
  299. # Call Pdb's trace dispatch method.
  300. try:
  301. return pdb.Pdb.trace_dispatch(self, *args)
  302. finally:
  303. sys.stdout = save_stdout
  304. # [XX] Normalize with respect to os.path.pardir?
  305. def _module_relative_path(module, path):
  306. if not inspect.ismodule(module):
  307. raise TypeError, 'Expected a module: %r' % module
  308. if path.startswith('/'):
  309. raise ValueError, 'Module-relative files may not have absolute paths'
  310. # Find the base directory for the path.
  311. if hasattr(module, '__file__'):
  312. # A normal module/package
  313. basedir = os.path.split(module.__file__)[0]
  314. elif module.__name__ == '__main__':
  315. # An interactive session.
  316. if len(sys.argv)>0 and sys.argv[0] != '':
  317. basedir = os.path.split(sys.argv[0])[0]
  318. else:
  319. basedir = os.curdir
  320. else:
  321. # A module w/o __file__ (this includes builtins)
  322. raise ValueError("Can't resolve paths relative to the module " +
  323. module + " (it has no __file__)")
  324. # Combine the base directory and the path.
  325. return os.path.join(basedir, *(path.split('/')))
  326. ######################################################################
  327. ## 2. Example & DocTest
  328. ######################################################################
  329. ## - An "example" is a <source, want> pair, where "source" is a
  330. ## fragment of source code, and "want" is the expected output for
  331. ## "source." The Example class also includes information about
  332. ## where the example was extracted from.
  333. ##
  334. ## - A "doctest" is a collection of examples, typically extracted from
  335. ## a string (such as an object's docstring). The DocTest class also
  336. ## includes information about where the string was extracted from.
  337. class Example:
  338. """
  339. A single doctest example, consisting of source code and expected
  340. output. `Example` defines the following attributes:
  341. - source: A single Python statement, always ending with a newline.
  342. The constructor adds a newline if needed.
  343. - want: The expected output from running the source code (either
  344. from stdout, or a traceback in case of exception). `want` ends
  345. with a newline unless it's empty, in which case it's an empty
  346. string. The constructor adds a newline if needed.
  347. - exc_msg: The exception message generated by the example, if
  348. the example is expected to generate an exception; or `None` if
  349. it is not expected to generate an exception. This exception
  350. message is compared against the return value of
  351. `traceback.format_exception_only()`. `exc_msg` ends with a
  352. newline unless it's `None`. The constructor adds a newline
  353. if needed.
  354. - lineno: The line number within the DocTest string containing
  355. this Example where the Example begins. This line number is
  356. zero-based, with respect to the beginning of the DocTest.
  357. - indent: The example's indentation in the DocTest string.
  358. I.e., the number of space characters that preceed the
  359. example's first prompt.
  360. - options: A dictionary mapping from option flags to True or
  361. False, which is used to override default options for this
  362. example. Any option flags not contained in this dictionary
  363. are left at their default value (as specified by the
  364. DocTestRunner's optionflags). By default, no options are set.
  365. """
  366. def __init__(self, source, want, exc_msg=None, lineno=0, indent=0,
  367. options=None):
  368. # Normalize inputs.
  369. if not source.endswith('\n'):
  370. source += '\n'
  371. if want and not want.endswith('\n'):
  372. want += '\n'
  373. if exc_msg is not None and not exc_msg.endswith('\n'):
  374. exc_msg += '\n'
  375. # Store properties.
  376. self.source = source
  377. self.want = want
  378. self.lineno = lineno
  379. self.indent = indent
  380. if options is None: options = {}
  381. self.options = options
  382. self.exc_msg = exc_msg
  383. class DocTest:
  384. """
  385. A collection of doctest examples that should be run in a single
  386. namespace. Each `DocTest` defines the following attributes:
  387. - examples: the list of examples.
  388. - globs: The namespace (aka globals) that the examples should
  389. be run in.
  390. - name: A name identifying the DocTest (typically, the name of
  391. the object whose docstring this DocTest was extracted from).
  392. - filename: The name of the file that this DocTest was extracted
  393. from, or `None` if the filename is unknown.
  394. - lineno: The line number within filename where this DocTest
  395. begins, or `None` if the line number is unavailable. This
  396. line number is zero-based, with respect to the beginning of
  397. the file.
  398. - docstring: The string that the examples were extracted from,
  399. or `None` if the string is unavailable.
  400. """
  401. def __init__(self, examples, globs, name, filename, lineno, docstring):
  402. """
  403. Create a new DocTest containing the given examples. The
  404. DocTest's globals are initialized with a copy of `globs`.
  405. """
  406. assert not isinstance(examples, basestring), \
  407. "DocTest no longer accepts str; use DocTestParser instead"
  408. self.examples = examples
  409. self.docstring = docstring
  410. self.globs = globs.copy()
  411. self.name = name
  412. self.filename = filename
  413. self.lineno = lineno
  414. def __repr__(self):
  415. if len(self.examples) == 0:
  416. examples = 'no examples'
  417. elif len(self.examples) == 1:
  418. examples = '1 example'
  419. else:
  420. examples = '%d examples' % len(self.examples)
  421. return ('<DocTest %s from %s:%s (%s)>' %
  422. (self.name, self.filename, self.lineno, examples))
  423. # This lets us sort tests by name:
  424. def __cmp__(self, other):
  425. if not isinstance(other, DocTest):
  426. return -1
  427. return cmp((self.name, self.filename, self.lineno, id(self)),
  428. (other.name, other.filename, other.lineno, id(other)))
  429. ######################################################################
  430. ## 3. DocTestParser
  431. ######################################################################
  432. class DocTestParser:
  433. """
  434. A class used to parse strings containing doctest examples.
  435. """
  436. # This regular expression is used to find doctest examples in a
  437. # string. It defines three groups: `source` is the source code
  438. # (including leading indentation and prompts); `indent` is the
  439. # indentation of the first (PS1) line of the source code; and
  440. # `want` is the expected output (including leading indentation).
  441. _EXAMPLE_RE = re.compile(r'''
  442. # Source consists of a PS1 line followed by zero or more PS2 lines.
  443. (?P<source>
  444. (?:^(?P<indent> [ ]*) >>> .*) # PS1 line
  445. (?:\n [ ]* \.\.\. .*)*) # PS2 lines
  446. \n?
  447. # Want consists of any non-blank lines that do not start with PS1.
  448. (?P<want> (?:(?![ ]*$) # Not a blank line
  449. (?![ ]*>>>) # Not a line starting with PS1
  450. .*$\n? # But any other line
  451. )*)
  452. ''', re.MULTILINE | re.VERBOSE)
  453. # A regular expression for handling `want` strings that contain
  454. # expected exceptions. It divides `want` into three pieces:
  455. # - the traceback header line (`hdr`)
  456. # - the traceback stack (`stack`)
  457. # - the exception message (`msg`), as generated by
  458. # traceback.format_exception_only()
  459. # `msg` may have multiple lines. We assume/require that the
  460. # exception message is the first non-indented line starting with a word
  461. # character following the traceback header line.
  462. _EXCEPTION_RE = re.compile(r"""
  463. # Grab the traceback header. Different versions of Python have
  464. # said different things on the first traceback line.
  465. ^(?P<hdr> Traceback\ \(
  466. (?: most\ recent\ call\ last
  467. | innermost\ last
  468. ) \) :
  469. )
  470. \s* $ # toss trailing whitespace on the header.
  471. (?P<stack> .*?) # don't blink: absorb stuff until...
  472. ^ (?P<msg> \w+ .*) # a line *starts* with alphanum.
  473. """, re.VERBOSE | re.MULTILINE | re.DOTALL)
  474. # A callable returning a true value iff its argument is a blank line
  475. # or contains a single comment.
  476. _IS_BLANK_OR_COMMENT = re.compile(r'^[ ]*(#.*)?$').match
  477. def parse(self, string, name='<string>'):
  478. """
  479. Divide the given string into examples and intervening text,
  480. and return them as a list of alternating Examples and strings.
  481. Line numbers for the Examples are 0-based. The optional
  482. argument `name` is a name identifying this string, and is only
  483. used for error messages.
  484. """
  485. string = string.expandtabs()
  486. # If all lines begin with the same indentation, then strip it.
  487. min_indent = self._min_indent(string)
  488. if min_indent > 0:
  489. string = '\n'.join([l[min_indent:] for l in string.split('\n')])
  490. output = []
  491. charno, lineno = 0, 0
  492. # Find all doctest examples in the string:
  493. for m in self._EXAMPLE_RE.finditer(string):
  494. # Add the pre-example text to `output`.
  495. output.append(string[charno:m.start()])
  496. # Update lineno (lines before this example)
  497. lineno += string.count('\n', charno, m.start())
  498. # Extract info from the regexp match.
  499. (source, options, want, exc_msg) = \
  500. self._parse_example(m, name, lineno)
  501. # Create an Example, and add it to the list.
  502. if not self._IS_BLANK_OR_COMMENT(source):
  503. output.append( Example(source, want, exc_msg,
  504. lineno=lineno,
  505. indent=min_indent+len(m.group('indent')),
  506. options=options) )
  507. # Update lineno (lines inside this example)
  508. lineno += string.count('\n', m.start(), m.end())
  509. # Update charno.
  510. charno = m.end()
  511. # Add any remaining post-example text to `output`.
  512. output.append(string[charno:])
  513. return output
  514. def get_doctest(self, string, globs, name, filename, lineno):
  515. """
  516. Extract all doctest examples from the given string, and
  517. collect them into a `DocTest` object.
  518. `globs`, `name`, `filename`, and `lineno` are attributes for
  519. the new `DocTest` object. See the documentation for `DocTest`
  520. for more information.
  521. """
  522. return DocTest(self.get_examples(string, name), globs,
  523. name, filename, lineno, string)
  524. def get_examples(self, string, name='<string>'):
  525. """
  526. Extract all doctest examples from the given string, and return
  527. them as a list of `Example` objects. Line numbers are
  528. 0-based, because it's most common in doctests that nothing
  529. interesting appears on the same line as opening triple-quote,
  530. and so the first interesting line is called \"line 1\" then.
  531. The optional argument `name` is a name identifying this
  532. string, and is only used for error messages.
  533. """
  534. return [x for x in self.parse(string, name)
  535. if isinstance(x, Example)]
  536. def _parse_example(self, m, name, lineno):
  537. """
  538. Given a regular expression match from `_EXAMPLE_RE` (`m`),
  539. return a pair `(source, want)`, where `source` is the matched
  540. example's source code (with prompts and indentation stripped);
  541. and `want` is the example's expected output (with indentation
  542. stripped).
  543. `name` is the string's name, and `lineno` is the line number
  544. where the example starts; both are used for error messages.
  545. """
  546. # Get the example's indentation level.
  547. indent = len(m.group('indent'))
  548. # Divide source into lines; check that they're properly
  549. # indented; and then strip their indentation & prompts.
  550. source_lines = m.group('source').split('\n')
  551. self._check_prompt_blank(source_lines, indent, name, lineno)
  552. self._check_prefix(source_lines[1:], ' '*indent + '.', name, lineno)
  553. source = '\n'.join([sl[indent+4:] for sl in source_lines])
  554. # Divide want into lines; check that it's properly indented; and
  555. # then strip the indentation. Spaces before the last newline should
  556. # be preserved, so plain rstrip() isn't good enough.
  557. want = m.group('want')
  558. want_lines = want.split('\n')
  559. if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]):
  560. del want_lines[-1] # forget final newline & spaces after it
  561. self._check_prefix(want_lines, ' '*indent, name,
  562. lineno + len(source_lines))
  563. want = '\n'.join([wl[indent:] for wl in want_lines])
  564. # If `want` contains a traceback message, then extract it.
  565. m = self._EXCEPTION_RE.match(want)
  566. if m:
  567. exc_msg = m.group('msg')
  568. else:
  569. exc_msg = None
  570. # Extract options from the source.
  571. options = self._find_options(source, name, lineno)
  572. return source, options, want, exc_msg
  573. # This regular expression looks for option directives in the
  574. # source code of an example. Option directives are comments
  575. # starting with "doctest:". Warning: this may give false
  576. # positives for string-literals that contain the string
  577. # "#doctest:". Eliminating these false positives would require
  578. # actually parsing the string; but we limit them by ignoring any
  579. # line containing "#doctest:" that is *followed* by a quote mark.
  580. _OPTION_DIRECTIVE_RE = re.compile(r'#\s*doctest:\s*([^\n\'"]*)$',
  581. re.MULTILINE)
  582. def _find_options(self, source, name, lineno):
  583. """
  584. Return a dictionary containing option overrides extracted from
  585. option directives in the given source string.
  586. `name` is the string's name, and `lineno` is the line number
  587. where the example starts; both are used for error messages.
  588. """
  589. options = {}
  590. # (note: with the current regexp, this will match at most once:)
  591. for m in self._OPTION_DIRECTIVE_RE.finditer(source):
  592. option_strings = m.group(1).replace(',', ' ').split()
  593. for option in option_strings:
  594. if (option[0] not in '+-' or
  595. option[1:] not in OPTIONFLAGS_BY_NAME):
  596. raise ValueError('line %r of the doctest for %s '
  597. 'has an invalid option: %r' %
  598. (lineno+1, name, option))
  599. flag = OPTIONFLAGS_BY_NAME[option[1:]]
  600. options[flag] = (option[0] == '+')
  601. if options and self._IS_BLANK_OR_COMMENT(source):
  602. raise ValueError('line %r of the doctest for %s has an option '
  603. 'directive on a line with no example: %r' %
  604. (lineno, name, source))
  605. return options
  606. # This regular expression finds the indentation of every non-blank
  607. # line in a string.
  608. _INDENT_RE = re.compile('^([ ]*)(?=\S)', re.MULTILINE)
  609. def _min_indent(self, s):
  610. "Return the minimum indentation of any non-blank line in `s`"
  611. indents = [len(indent) for indent in self._INDENT_RE.findall(s)]
  612. if len(indents) > 0:
  613. return min(indents)
  614. else:
  615. return 0
  616. def _check_prompt_blank(self, lines, indent, name, lineno):
  617. """
  618. Given the lines of a source string (including prompts and
  619. leading indentation), check to make sure that every prompt is
  620. followed by a space character. If any line is not followed by
  621. a space character, then raise ValueError.
  622. """
  623. for i, line in enumerate(lines):
  624. if len(line) >= indent+4 and line[indent+3] != ' ':
  625. raise ValueError('line %r of the docstring for %s '
  626. 'lacks blank after %s: %r' %
  627. (lineno+i+1, name,
  628. line[indent:indent+3], line))
  629. def _check_prefix(self, lines, prefix, name, lineno):
  630. """
  631. Check that every line in the given list starts with the given
  632. prefix; if any line does not, then raise a ValueError.
  633. """
  634. for i, line in enumerate(lines):
  635. if line and not line.startswith(prefix):
  636. raise ValueError('line %r of the docstring for %s has '
  637. 'inconsistent leading whitespace: %r' %
  638. (lineno+i+1, name, line))
  639. ######################################################################
  640. ## 4. DocTest Finder
  641. ######################################################################
  642. class DocTestFinder:
  643. """
  644. A class used to extract the DocTests that are relevant to a given
  645. object, from its docstring and the docstrings of its contained
  646. objects. Doctests can currently be extracted from the following
  647. object types: modules, functions, classes, methods, staticmethods,
  648. classmethods, and properties.
  649. """
  650. def __init__(self, verbose=False, parser=DocTestParser(),
  651. recurse=True, exclude_empty=True):
  652. """
  653. Create a new doctest finder.
  654. The optional argument `parser` specifies a class or
  655. function that should be used to create new DocTest objects (or
  656. objects that implement the same interface as DocTest). The
  657. signature for this factory function should match the signature
  658. of the DocTest constructor.
  659. If the optional argument `recurse` is false, then `find` will
  660. only examine the given object, and not any contained objects.
  661. If the optional argument `exclude_empty` is false, then `find`
  662. will include tests for objects with empty docstrings.
  663. """
  664. self._parser = parser
  665. self._verbose = verbose
  666. self._recurse = recurse
  667. self._exclude_empty = exclude_empty
  668. def find(self, obj, name=None, module=None, globs=None, extraglobs=None):
  669. """
  670. Return a list of the DocTests that are defined by the given
  671. object's docstring, or by any of its contained objects'
  672. docstrings.
  673. The optional parameter `module` is the module that contains
  674. the given object. If the module is not specified or is None, then
  675. the test finder will attempt to automatically determine the
  676. correct module. The object's module is used:
  677. - As a default namespace, if `globs` is not specified.
  678. - To prevent the DocTestFinder from extracting DocTests
  679. from objects that are imported from other modules.
  680. - To find the name of the file containing the object.
  681. - To help find the line number of the object within its
  682. file.
  683. Contained objects whose module does not match `module` are ignored.
  684. If `module` is False, no attempt to find the module will be made.
  685. This is obscure, of use mostly in tests: if `module` is False, or
  686. is None but cannot be found automatically, then all objects are
  687. considered to belong to the (non-existent) module, so all contained
  688. objects will (recursively) be searched for doctests.
  689. The globals for each DocTest is formed by combining `globs`
  690. and `extraglobs` (bindings in `extraglobs` override bindings
  691. in `globs`). A new copy of the globals dictionary is created
  692. for each DocTest. If `globs` is not specified, then it
  693. defaults to the module's `__dict__`, if specified, or {}
  694. otherwise. If `extraglobs` is not specified, then it defaults
  695. to {}.
  696. """
  697. # If name was not specified, then extract it from the object.
  698. if name is None:
  699. name = getattr(obj, '__name__', None)
  700. if name is None:
  701. raise ValueError("DocTestFinder.find: name must be given "
  702. "when obj.__name__ doesn't exist: %r" %
  703. (type(obj),))
  704. # Find the module that contains the given object (if obj is
  705. # a module, then module=obj.). Note: this may fail, in which
  706. # case module will be None.
  707. if module is False:
  708. module = None
  709. elif module is None:
  710. module = inspect.getmodule(obj)
  711. # Read the module's source code. This is used by
  712. # DocTestFinder._find_lineno to find the line number for a
  713. # given object's docstring.
  714. try:
  715. file = inspect.getsourcefile(obj) or inspect.getfile(obj)
  716. if module is not None:
  717. # Supply the module globals in case the module was
  718. # originally loaded via a PEP 302 loader and
  719. # file is not a valid filesystem path
  720. source_lines = linecache.getlines(file, module.__dict__)
  721. else:
  722. # No access to a loader, so assume it's a normal
  723. # filesystem path
  724. source_lines = linecache.getlines(file)
  725. if not source_lines:
  726. source_lines = None
  727. except TypeError:
  728. source_lines = None
  729. # Initialize globals, and merge in extraglobs.
  730. if globs is None:
  731. if module is None:
  732. globs = {}
  733. else:
  734. globs = module.__dict__.copy()
  735. else:
  736. globs = globs.copy()
  737. if extraglobs is not None:
  738. globs.update(extraglobs)
  739. if '__name__' not in globs:
  740. globs['__name__'] = '__main__' # provide a default module name
  741. # Recursively expore `obj`, extracting DocTests.
  742. tests = []
  743. self._find(tests, obj, name, module, source_lines, globs, {})
  744. # Sort the tests by alpha order of names, for consistency in
  745. # verbose-mode output. This was a feature of doctest in Pythons
  746. # <= 2.3 that got lost by accident in 2.4. It was repaired in
  747. # 2.4.4 and 2.5.
  748. tests.sort()
  749. return tests
  750. def _from_module(self, module, object):
  751. """
  752. Return true if the given object is defined in the given
  753. module.
  754. """
  755. if module is None:
  756. return True
  757. elif inspect.getmodule(object) is not None:
  758. return module is inspect.getmodule(object)
  759. elif inspect.isfunction(object):
  760. return module.__dict__ is object.func_globals
  761. elif inspect.isclass(object):
  762. return module.__name__ == object.__module__
  763. elif hasattr(object, '__module__'):
  764. return module.__name__ == object.__module__
  765. elif isinstance(object, property):
  766. return True # [XX] no way not be sure.
  767. else:
  768. raise ValueError("object must be a class or function")
  769. def _find(self, tests, obj, name, module, source_lines, globs, seen):
  770. """
  771. Find tests for the given object and any contained objects, and
  772. add them to `tests`.
  773. """
  774. if self._verbose:
  775. print 'Finding tests in %s' % name
  776. # If we've already processed this object, then ignore it.
  777. if id(obj) in seen:
  778. return
  779. seen[id(obj)] = 1
  780. # Find a test for this object, and add it to the list of tests.
  781. test = self._get_test(obj, name, module, globs, source_lines)
  782. if test is not None:
  783. tests.append(test)
  784. # Look for tests in a module's contained objects.
  785. if inspect.ismodule(obj) and self._recurse:
  786. for valname, val in obj.__dict__.items():
  787. valname = '%s.%s' % (name, valname)
  788. # Recurse to functions & classes.
  789. if ((inspect.isfunction(val) or inspect.isclass(val)) and
  790. self._from_module(module, val)):
  791. self._find(tests, val, valname, module, source_lines,
  792. globs, seen)
  793. # Look for tests in a module's __test__ dictionary.
  794. if inspect.ismodule(obj) and self._recurse:
  795. for valname, val in getattr(obj, '__test__', {}).items():
  796. if not isinstance(valname, basestring):
  797. raise ValueError("DocTestFinder.find: __test__ keys "
  798. "must be strings: %r" %
  799. (type(valname),))
  800. if not (inspect.isfunction(val) or inspect.isclass(val) or
  801. inspect.ismethod(val) or inspect.ismodule(val) or
  802. isinstance(val, basestring)):
  803. raise ValueError("DocTestFinder.find: __test__ values "
  804. "must be strings, functions, methods, "
  805. "classes, or modules: %r" %
  806. (type(val),))
  807. valname = '%s.__test__.%s' % (name, valname)
  808. self._find(tests, val, valname, module, source_lines,
  809. globs, seen)
  810. # Look for tests in a class's contained objects.
  811. if inspect.isclass(obj) and self._recurse:
  812. for valname, val in obj.__dict__.items():
  813. # Special handling for staticmethod/classmethod.
  814. if isinstance(val, staticmethod):
  815. val = getattr(obj, valname)
  816. if isinstance(val, classmethod):
  817. val = getattr(obj, valname).im_func
  818. # Recurse to methods, properties, and nested classes.
  819. if ((inspect.isfunction(val) or inspect.isclass(val) or
  820. isinstance(val, property)) and
  821. self._from_module(module, val)):
  822. valname = '%s.%s' % (name, valname)
  823. self._find(tests, val, valname, module, source_lines,
  824. globs, seen)
  825. def _get_test(self, obj, name, module, globs, source_lines):
  826. """
  827. Return a DocTest for the given object, if it defines a docstring;
  828. otherwise, return None.
  829. """
  830. # Extract the object's docstring. If it doesn't have one,
  831. # then return None (no test for this object).
  832. if isinstance(obj, basestring):
  833. docstring = obj
  834. else:
  835. try:
  836. if obj.__doc__ is None:
  837. docstring = ''
  838. else:
  839. docstring = obj.__doc__
  840. if not isinstance(docstring, basestring):
  841. docstring = str(docstring)
  842. except (TypeError, AttributeError):
  843. docstring = ''
  844. # Find the docstring's location in the file.
  845. lineno = self._find_lineno(obj, source_lines)
  846. # Don't bother if the docstring is empty.
  847. if self._exclude_empty and not docstring:
  848. return None
  849. # Return a DocTest for this object.
  850. if module is None:
  851. filename = None
  852. else:
  853. filename = getattr(module, '__file__', module.__name__)
  854. if filename[-4:] in (".pyc", ".pyo"):
  855. filename = filename[:-1]
  856. return self._parser.get_doctest(docstring, globs, name,
  857. filename, lineno)
  858. def _find_lineno(self, obj, source_lines):
  859. """
  860. Return a line number of the given object's docstring. Note:
  861. this method assumes that the object has a docstring.
  862. """
  863. lineno = None
  864. # Find the line number for modules.
  865. if inspect.ismodule(obj):
  866. lineno = 0
  867. # Find the line number for classes.
  868. # Note: this could be fooled if a class is defined multiple
  869. # times in a single file.
  870. if inspect.isclass(obj):
  871. if source_lines is None:
  872. return None
  873. pat = re.compile(r'^\s*class\s*%s\b' %
  874. getattr(obj, '__name__', '-'))
  875. for i, line in enumerate(source_lines):
  876. if pat.match(line):
  877. lineno = i
  878. break
  879. # Find the line number for functions & methods.
  880. if inspect.ismethod(obj): obj = obj.im_func
  881. if inspect.isfunction(obj): obj = obj.func_code
  882. if inspect.istraceback(obj): obj = obj.tb_frame
  883. if inspect.isframe(obj): obj = obj.f_code
  884. if inspect.iscode(obj):
  885. lineno = getattr(obj, 'co_firstlineno', None)-1
  886. # Find the line number where the docstring starts. Assume
  887. # that it's the first line that begins with a quote mark.
  888. # Note: this could be fooled by a multiline function
  889. # signature, where a continuation line begins with a quote
  890. # mark.
  891. if lineno is not None:
  892. if source_lines is None:
  893. return lineno+1
  894. pat = re.compile('(^|.*:)\s*\w*("|\')')
  895. for lineno in range(lineno, len(source_lines)):
  896. if pat.match(source_lines[lineno]):
  897. return lineno
  898. # We couldn't find the line number.
  899. return None
  900. ######################################################################
  901. ## 5. DocTest Runner
  902. ######################################################################
  903. class DocTestRunner:
  904. """
  905. A class used to run DocTest test cases, and accumulate statistics.
  906. The `run` method is used to process a single DocTest case. It
  907. returns a tuple `(f, t)`, where `t` is the number of test cases
  908. tried, and `f` is the number of test cases that failed.
  909. >>> tests = DocTestFinder().find(_TestClass)
  910. >>> runner = DocTestRunner(verbose=False)
  911. >>> tests.sort(key = lambda test: test.name)
  912. >>> for test in tests:
  913. ... print test.name, '->', runner.run(test)
  914. _TestClass -> TestResults(failed=0, attempted=2)
  915. _TestClass.__init__ -> TestResults(failed=0, attempted=2)
  916. _TestClass.get -> TestResults(failed=0, attempted=2)
  917. _TestClass.square -> TestResults(failed=0, attempted=1)
  918. The `summarize` method prints a summary of all the test cases that
  919. have been run by the runner, and returns an aggregated `(f, t)`
  920. tuple:
  921. >>> runner.summarize(verbose=1)
  922. 4 items passed all tests:
  923. 2 tests in _TestClass
  924. 2 tests in _TestClass.__init__
  925. 2 tests in _TestClass.get
  926. 1 tests in _TestClass.square
  927. 7 tests in 4 items.
  928. 7 passed and 0 failed.
  929. Test passed.
  930. TestResults(failed=0, attempted=7)
  931. The aggregated number of tried examples and failed examples is
  932. also available via the `tries` and `failures` attributes:
  933. >>> runner.tries
  934. 7
  935. >>> runner.failures
  936. 0
  937. The comparison between expected outputs and actual outputs is done
  938. by an `OutputChecker`. This comparison may be customized with a
  939. number of option flags; see the documentation for `testmod` for
  940. more information. If the option flags are insufficient, then the
  941. comparison may also be customized by passing a subclass of
  942. `OutputChecker` to the constructor.
  943. The test runner's display output can be controlled in two ways.
  944. First, an output function (`out) can be passed to
  945. `TestRunner.run`; this function will be called with strings that
  946. should be displayed. It defaults to `sys.stdout.write`. If
  947. capturing the output is not sufficient, then the display output
  948. can be also customized by subclassing DocTestRunner, and
  949. overriding the methods `report_start`, `report_success`,
  950. `report_unexpected_exception`, and `report_failure`.
  951. """
  952. # This divider string is used to separate failure messages, and to
  953. # separate sections of the summary.
  954. DIVIDER = "*" * 70
  955. def __init__(self, checker=None, verbose=None, optionflags=0):
  956. """
  957. Create a new test runner.
  958. Optional keyword arg `checker` is the `OutputChecker` that
  959. should be used to compare the expected outputs and actual
  960. outputs of doctest examples.
  961. Optional keyword arg 'verbose' prints lots of stuff if true,
  962. only failures if false; by default, it's true iff '-v' is in
  963. sys.argv.
  964. Optional argument `optionflags` can be used to control how the
  965. test runner compares expected output to actual output, and how
  966. it displays failures. See the documentation for `testmod` for
  967. more information.
  968. """
  969. self._checker = checker or OutputChecker()
  970. if verbose is None:
  971. verbose = '-v' in sys.argv
  972. self._verbose = verbose
  973. self.optionflags = optionflags
  974. self.original_optionflags = optionflags
  975. # Keep track of the examples we've run.
  976. self.tries = 0
  977. self.failures = 0
  978. self._name2ft = {}
  979. # Create a fake output target for capturing doctest output.
  980. self._fakeout = _SpoofOut()
  981. #/////////////////////////////////////////////////////////////////
  982. # Reporting methods
  983. #/////////////////////////////////////////////////////////////////
  984. def report_start(self, out, test, example):
  985. """
  986. Report that the test runner is about to process the given
  987. example. (Only displays a message if verbose=True)
  988. """
  989. if self._verbose:
  990. if example.want:
  991. out('Trying:\n' + _indent(example.source) +
  992. 'Expecting:\n' + _indent(example.want))
  993. else:
  994. out('Trying:\n' + _indent(example.source) +
  995. 'Expecting nothing\n')
  996. def report_success(self, out, test, example, got):
  997. """
  998. Report that the given example ran successfully. (Only
  999. displays a message if verbose=True)
  1000. """
  1001. if self._verbose:
  1002. out("ok\n")
  1003. def report_failure(self, out, test, example, got):
  1004. """
  1005. Report that the given example failed.
  1006. """
  1007. out(self._failure_header(test, example) +
  1008. self._checker.output_difference(example, got, self.optionflags))
  1009. def report_unexpected_exception(self, out, test, example, exc_info):
  1010. """
  1011. Report that the given example raised an unexpected exception.
  1012. """
  1013. out(self._failure_header(test, example) +
  1014. 'Exception raised:\n' + _indent(_exception_traceback(exc_info)))
  1015. def _failure_header(self, test, example):
  1016. out = [self.DIVIDER]
  1017. if test.filename:
  1018. if test.lineno is not None and example.lineno is not None:
  1019. lineno = test.lineno + example.lineno + 1
  1020. else:
  1021. lineno = '?'
  1022. out.append('File "%s", line %s, in %s' %
  1023. (test.filename, lineno, test.name))
  1024. else:
  1025. out.append('Line %s, in %s' % (example.lineno+1, test.name))
  1026. out.append('Failed example:')
  1027. source = example.source
  1028. out.append(_indent(source))
  1029. return '\n'.join(out)
  1030. #/////////////////////////////////////////////////////////////////
  1031. # DocTest Running
  1032. #/////////////////////////////////////////////////////////////////
  1033. def __run(self, test, compileflags, out):
  1034. """
  1035. Run the examples in `test`. Write the outcome of each example
  1036. with one of the `DocTestRunner.report_*` methods, using the
  1037. writer function `out`. `compileflags` is the set of compiler
  1038. flags that should be used to execute examples. Return a tuple
  1039. `(f, t)`, where `t` is the number of examples tried, and `f`
  1040. is the number of examples that failed. The examples are run
  1041. in the namespace `test.globs`.
  1042. """
  1043. # Keep track of the number of failures and tries.
  1044. failures = tries = 0
  1045. # Save the option flags (since option directives can be used
  1046. # to modify them).
  1047. original_optionflags = self.optionflags
  1048. SUCCESS, FAILURE, BOOM = range(3) # `outcome` state
  1049. check = self._checker.check_output
  1050. # Process each example.
  1051. for examplenum, example in enumerate(test.examples):
  1052. # If REPORT_ONLY_FIRST_FAILURE is set, then supress
  1053. # reporting after the first failure.
  1054. quiet = (self.optionflags & REPORT_ONLY_FIRST_FAILURE and
  1055. failures > 0)
  1056. # Merge in the example's options.
  1057. self.optionflags = original_optionflags
  1058. if example.options:
  1059. for (optionflag, val) in example.options.items():
  1060. if val:
  1061. self.optionflags |= optionflag
  1062. else:
  1063. self.optionflags &= ~optionflag
  1064. # If 'SKIP' is set, then skip this example.
  1065. if self.optionflags & SKIP:
  1066. continue
  1067. # Record that we started this example.
  1068. tries += 1
  1069. if not quiet:
  1070. self.report_start(out, test, example)
  1071. # Use a special filename for compile(), so we can retrieve
  1072. # the source code during interactive debugging (see
  1073. # __patched_linecache_getlines).
  1074. filename = '<doctest %s[%d]>' % (test.name, examplenum)
  1075. # Run the example in the given context (globs), and record
  1076. # any exception that gets raised. (But don't intercept
  1077. # keyboard interrupts.)
  1078. try:
  1079. # Don't blink! This is where the user's code gets run.
  1080. exec compile(example.source, filename, "single",
  1081. compileflags, 1) in test.globs
  1082. self.debugger.set_continue() # ==== Example Finished ====
  1083. exception = None
  1084. except KeyboardInterrupt:
  1085. raise
  1086. except:
  1087. exception = sys.exc_info()
  1088. self.debugger.set_continue() # ==== Example Finished ====
  1089. got = self._fakeout.getvalue() # the actual output
  1090. self._fakeout.truncate(0)
  1091. outcome = FAILURE # guilty until proved innocent or insane
  1092. # If the example executed without raising any exceptions,…