blob: bb9f43229d4f58c4c0548a1f0eabb9398aca91e5 [file] [log] [blame]
Tim Peters4fd9e2f2001-08-18 00:05:50 +00001# Module doctest.
Tim Peters8485b562004-08-04 18:46:34 +00002# Released to the public domain 16-Jan-2001, by Tim Peters (tim@python.org).
Tim Peters19397e52004-08-06 22:02:59 +00003# Major enhancements and refactoring by:
Tim Peters8485b562004-08-04 18:46:34 +00004# Jim Fulton
5# Edward Loper
Tim Peters8a7d2d52001-01-16 07:10:57 +00006
7# Provided as-is; use at your own risk; no warranty; no promises; enjoy!
8
Martin v. Löwis92816de2004-05-31 19:01:00 +00009r"""Module doctest -- a framework for running examples in docstrings.
Tim Peters8a7d2d52001-01-16 07:10:57 +000010
Tim Peters80e53142004-08-09 04:34:45 +000011In simplest use, end each module M to be tested with:
Tim Peters8a7d2d52001-01-16 07:10:57 +000012
13def _test():
Tim Peters80e53142004-08-09 04:34:45 +000014 import doctest
Tim Peters48983fc2004-09-25 02:41:28 +000015 doctest.testmod()
Tim Peters8a7d2d52001-01-16 07:10:57 +000016
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
Tim Peters80e53142004-08-09 04:34:45 +000037You 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
Tim Peters8a7d2d52001-01-16 07:10:57 +000039examined by testmod.
40
Tim Peters80e53142004-08-09 04:34:45 +000041There 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.
Tim Peters8a7d2d52001-01-16 07:10:57 +000046"""
Tim Peters48983fc2004-09-25 02:41:28 +000047
Edward Loper8e4a34b2004-08-12 02:34:27 +000048__docformat__ = 'reStructuredText en'
Tim Peters8a7d2d52001-01-16 07:10:57 +000049
Tim Peters4fd9e2f2001-08-18 00:05:50 +000050__all__ = [
Edward Loperb7503ff2004-08-19 19:19:03 +000051 # 0, Option Flags
52 'register_optionflag',
53 'DONT_ACCEPT_TRUE_FOR_1',
54 'DONT_ACCEPT_BLANKLINE',
55 'NORMALIZE_WHITESPACE',
56 'ELLIPSIS',
Thomas Wouters477c8d52006-05-27 19:21:47 +000057 'SKIP',
Tim Peters1fbf9c52004-09-04 17:21:02 +000058 'IGNORE_EXCEPTION_DETAIL',
Tim Petersba601962004-09-04 15:04:06 +000059 'COMPARISON_FLAGS',
Edward Loper71f55af2004-08-26 01:41:51 +000060 'REPORT_UDIFF',
61 'REPORT_CDIFF',
62 'REPORT_NDIFF',
Jim Fultonf54bad42004-08-28 14:57:56 +000063 'REPORT_ONLY_FIRST_FAILURE',
Tim Petersba601962004-09-04 15:04:06 +000064 'REPORTING_FLAGS',
R David Murray5a9d7062012-11-21 15:09:21 -050065 'FAIL_FAST',
Edward Loperb7503ff2004-08-19 19:19:03 +000066 # 1. Utility Functions
Edward Loperb7503ff2004-08-19 19:19:03 +000067 # 2. Example & DocTest
Tim Peters8485b562004-08-04 18:46:34 +000068 'Example',
69 'DocTest',
Edward Loperb7503ff2004-08-19 19:19:03 +000070 # 3. Doctest Parser
71 'DocTestParser',
72 # 4. Doctest Finder
Tim Peters8485b562004-08-04 18:46:34 +000073 'DocTestFinder',
Edward Loperb7503ff2004-08-19 19:19:03 +000074 # 5. Doctest Runner
Tim Peters8485b562004-08-04 18:46:34 +000075 'DocTestRunner',
Edward Loperb7503ff2004-08-19 19:19:03 +000076 'OutputChecker',
77 'DocTestFailure',
78 'UnexpectedException',
79 'DebugRunner',
80 # 6. Test Functions
Tim Peters4fd9e2f2001-08-18 00:05:50 +000081 'testmod',
Edward Loper052d0cd2004-09-19 17:19:33 +000082 'testfile',
Tim Peters4fd9e2f2001-08-18 00:05:50 +000083 'run_docstring_examples',
Georg Brandlcc80bfe2008-05-12 18:06:23 +000084 # 7. Unittest Support
Tim Petersdb3756d2003-06-29 05:30:48 +000085 'DocTestSuite',
Edward Loperb7503ff2004-08-19 19:19:03 +000086 'DocFileSuite',
Tim Peters9d02a7c2004-09-26 01:50:24 +000087 'set_unittest_reportflags',
Georg Brandlcc80bfe2008-05-12 18:06:23 +000088 # 8. Debugging Support
Edward Loperb7503ff2004-08-19 19:19:03 +000089 'script_from_examples',
Tim Petersdb3756d2003-06-29 05:30:48 +000090 'testsource',
Edward Loperb7503ff2004-08-19 19:19:03 +000091 'debug_src',
Tim Petersdb3756d2003-06-29 05:30:48 +000092 'debug',
Tim Peters4fd9e2f2001-08-18 00:05:50 +000093]
Tim Peters8a7d2d52001-01-16 07:10:57 +000094
Tim Peters4fd9e2f2001-08-18 00:05:50 +000095import __future__
R David Murray5707d502013-06-23 14:24:13 -040096import argparse
Victor Stinner12b8d142011-06-30 17:35:55 +020097import difflib
98import inspect
99import linecache
100import os
101import pdb
102import re
103import sys
104import traceback
105import unittest
Guido van Rossum34d19282007-08-09 01:03:29 +0000106from io import StringIO
Christian Heimes25bb7832008-01-11 16:17:00 +0000107from collections import namedtuple
108
109TestResults = namedtuple('TestResults', 'failed attempted')
Tim Peters7402f792001-10-02 03:53:41 +0000110
Tim Peters19397e52004-08-06 22:02:59 +0000111# There are 4 basic classes:
112# - Example: a <source, want> pair, plus an intra-docstring line number.
113# - DocTest: a collection of examples, parsed from a docstring, plus
114# info about where the docstring came from (name, filename, lineno).
115# - DocTestFinder: extracts DocTests from a given object's docstring and
116# its contained objects' docstrings.
117# - DocTestRunner: runs DocTest cases, and accumulates statistics.
118#
119# So the basic picture is:
120#
121# list of:
122# +------+ +---------+ +-------+
123# |object| --DocTestFinder-> | DocTest | --DocTestRunner-> |results|
124# +------+ +---------+ +-------+
125# | Example |
126# | ... |
127# | Example |
128# +---------+
129
Edward Loperac20f572004-08-12 02:02:24 +0000130# Option constants.
Tim Peters38330fe2004-08-30 16:19:24 +0000131
Edward Loperac20f572004-08-12 02:02:24 +0000132OPTIONFLAGS_BY_NAME = {}
133def register_optionflag(name):
Thomas Wouters477c8d52006-05-27 19:21:47 +0000134 # Create a new flag unless `name` is already known.
135 return OPTIONFLAGS_BY_NAME.setdefault(name, 1 << len(OPTIONFLAGS_BY_NAME))
Edward Loperac20f572004-08-12 02:02:24 +0000136
137DONT_ACCEPT_TRUE_FOR_1 = register_optionflag('DONT_ACCEPT_TRUE_FOR_1')
138DONT_ACCEPT_BLANKLINE = register_optionflag('DONT_ACCEPT_BLANKLINE')
139NORMALIZE_WHITESPACE = register_optionflag('NORMALIZE_WHITESPACE')
140ELLIPSIS = register_optionflag('ELLIPSIS')
Thomas Wouters477c8d52006-05-27 19:21:47 +0000141SKIP = register_optionflag('SKIP')
Tim Peters1fbf9c52004-09-04 17:21:02 +0000142IGNORE_EXCEPTION_DETAIL = register_optionflag('IGNORE_EXCEPTION_DETAIL')
Tim Peters38330fe2004-08-30 16:19:24 +0000143
144COMPARISON_FLAGS = (DONT_ACCEPT_TRUE_FOR_1 |
145 DONT_ACCEPT_BLANKLINE |
146 NORMALIZE_WHITESPACE |
Tim Peters1fbf9c52004-09-04 17:21:02 +0000147 ELLIPSIS |
Thomas Wouters477c8d52006-05-27 19:21:47 +0000148 SKIP |
Edward Loper7d88a582004-09-28 05:50:57 +0000149 IGNORE_EXCEPTION_DETAIL)
Tim Peters38330fe2004-08-30 16:19:24 +0000150
Edward Loper71f55af2004-08-26 01:41:51 +0000151REPORT_UDIFF = register_optionflag('REPORT_UDIFF')
152REPORT_CDIFF = register_optionflag('REPORT_CDIFF')
153REPORT_NDIFF = register_optionflag('REPORT_NDIFF')
Edward Lopera89f88d2004-08-26 02:45:51 +0000154REPORT_ONLY_FIRST_FAILURE = register_optionflag('REPORT_ONLY_FIRST_FAILURE')
R David Murray5a9d7062012-11-21 15:09:21 -0500155FAIL_FAST = register_optionflag('FAIL_FAST')
Edward Loperac20f572004-08-12 02:02:24 +0000156
Tim Peters38330fe2004-08-30 16:19:24 +0000157REPORTING_FLAGS = (REPORT_UDIFF |
158 REPORT_CDIFF |
159 REPORT_NDIFF |
R David Murray5a9d7062012-11-21 15:09:21 -0500160 REPORT_ONLY_FIRST_FAILURE |
161 FAIL_FAST)
Tim Peters38330fe2004-08-30 16:19:24 +0000162
Edward Loperac20f572004-08-12 02:02:24 +0000163# Special string markers for use in `want` strings:
164BLANKLINE_MARKER = '<BLANKLINE>'
165ELLIPSIS_MARKER = '...'
166
Tim Peters8485b562004-08-04 18:46:34 +0000167######################################################################
168## Table of Contents
169######################################################################
Edward Loper7c748462004-08-09 02:06:06 +0000170# 1. Utility Functions
171# 2. Example & DocTest -- store test cases
172# 3. DocTest Parser -- extracts examples from strings
173# 4. DocTest Finder -- extracts test cases from objects
174# 5. DocTest Runner -- runs test cases
175# 6. Test Functions -- convenient wrappers for testing
Georg Brandl31835852008-05-12 17:38:56 +0000176# 7. Unittest Support
177# 8. Debugging Support
178# 9. Example Usage
Tim Peters8a7d2d52001-01-16 07:10:57 +0000179
Tim Peters8485b562004-08-04 18:46:34 +0000180######################################################################
181## 1. Utility Functions
182######################################################################
Tim Peters8a7d2d52001-01-16 07:10:57 +0000183
Tim Peters8485b562004-08-04 18:46:34 +0000184def _extract_future_flags(globs):
185 """
186 Return the compiler-flags associated with the future features that
187 have been imported into the given namespace (globs).
188 """
189 flags = 0
190 for fname in __future__.all_feature_names:
191 feature = globs.get(fname, None)
192 if feature is getattr(__future__, fname):
193 flags |= feature.compiler_flag
194 return flags
Tim Peters7402f792001-10-02 03:53:41 +0000195
Tim Peters8485b562004-08-04 18:46:34 +0000196def _normalize_module(module, depth=2):
197 """
198 Return the module specified by `module`. In particular:
199 - If `module` is a module, then return module.
200 - If `module` is a string, then import and return the
201 module with that name.
202 - If `module` is None, then return the calling module.
203 The calling module is assumed to be the module of
204 the stack frame at the given depth in the call stack.
205 """
206 if inspect.ismodule(module):
207 return module
Walter Dörwaldaa97f042007-05-03 21:05:51 +0000208 elif isinstance(module, str):
Tim Peters8485b562004-08-04 18:46:34 +0000209 return __import__(module, globals(), locals(), ["*"])
210 elif module is None:
211 return sys.modules[sys._getframe(depth).f_globals['__name__']]
212 else:
213 raise TypeError("Expected a module, string, or None")
Tim Peters7402f792001-10-02 03:53:41 +0000214
Guido van Rossum1b81e7b2007-08-29 03:53:53 +0000215def _load_testfile(filename, package, module_relative, encoding):
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000216 if module_relative:
217 package = _normalize_module(package, 3)
218 filename = _module_relative_path(package, filename)
Brett Cannon4c14b5d2013-05-04 13:56:58 -0400219 if getattr(package, '__loader__', None) is not None:
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000220 if hasattr(package.__loader__, 'get_data'):
Guido van Rossumcd4d4522007-11-22 00:30:02 +0000221 file_contents = package.__loader__.get_data(filename)
222 file_contents = file_contents.decode(encoding)
223 # get_data() opens files as 'rb', so one must do the equivalent
224 # conversion as universal newlines would do.
225 return file_contents.replace(os.linesep, '\n'), filename
Antoine Pitrou92f60ed2010-10-14 22:11:44 +0000226 with open(filename, encoding=encoding) as f:
227 return f.read(), filename
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000228
Edward Loperaacf0832004-08-26 01:19:50 +0000229def _indent(s, indent=4):
Tim Peters8485b562004-08-04 18:46:34 +0000230 """
Florent Xicluna59250852010-02-27 14:21:57 +0000231 Add the given number of space characters to the beginning of
232 every non-blank line in `s`, and return the result.
Tim Peters8485b562004-08-04 18:46:34 +0000233 """
Edward Loperaacf0832004-08-26 01:19:50 +0000234 # This regexp matches the start of non-blank lines:
235 return re.sub('(?m)^(?!$)', indent*' ', s)
Tim Peters8a7d2d52001-01-16 07:10:57 +0000236
Edward Loper8e4a34b2004-08-12 02:34:27 +0000237def _exception_traceback(exc_info):
238 """
239 Return a string containing a traceback message for the given
240 exc_info tuple (as returned by sys.exc_info()).
241 """
242 # Get a traceback message.
243 excout = StringIO()
244 exc_type, exc_val, exc_tb = exc_info
245 traceback.print_exception(exc_type, exc_val, exc_tb, file=excout)
246 return excout.getvalue()
247
Tim Peters8485b562004-08-04 18:46:34 +0000248# Override some StringIO methods.
249class _SpoofOut(StringIO):
250 def getvalue(self):
251 result = StringIO.getvalue(self)
252 # If anything at all was written, make sure there's a trailing
253 # newline. There's no way for the expected output to indicate
254 # that a trailing newline is missing.
255 if result and not result.endswith("\n"):
256 result += "\n"
Tim Peters8485b562004-08-04 18:46:34 +0000257 return result
Tim Peters8a7d2d52001-01-16 07:10:57 +0000258
Guido van Rossum79139b22007-02-09 23:20:19 +0000259 def truncate(self, size=None):
Antoine Pitroub3d77002010-01-31 23:12:29 +0000260 self.seek(size)
261 StringIO.truncate(self)
Tim Peters8a7d2d52001-01-16 07:10:57 +0000262
Tim Peters26b3ebb2004-08-19 08:10:08 +0000263# Worst-case linear-time ellipsis matching.
Tim Petersb0a04e12004-08-20 02:08:04 +0000264def _ellipsis_match(want, got):
Tim Petersdc5de3b2004-08-19 14:06:20 +0000265 """
266 Essentially the only subtle case:
Tim Petersb0a04e12004-08-20 02:08:04 +0000267 >>> _ellipsis_match('aa...aa', 'aaa')
Tim Petersdc5de3b2004-08-19 14:06:20 +0000268 False
269 """
Tim Peters26b3ebb2004-08-19 08:10:08 +0000270 if ELLIPSIS_MARKER not in want:
271 return want == got
Tim Petersdc5de3b2004-08-19 14:06:20 +0000272
Tim Peters26b3ebb2004-08-19 08:10:08 +0000273 # Find "the real" strings.
274 ws = want.split(ELLIPSIS_MARKER)
275 assert len(ws) >= 2
Tim Peters26b3ebb2004-08-19 08:10:08 +0000276
Tim Petersdc5de3b2004-08-19 14:06:20 +0000277 # Deal with exact matches possibly needed at one or both ends.
278 startpos, endpos = 0, len(got)
279 w = ws[0]
280 if w: # starts with exact match
281 if got.startswith(w):
282 startpos = len(w)
283 del ws[0]
284 else:
285 return False
286 w = ws[-1]
287 if w: # ends with exact match
288 if got.endswith(w):
289 endpos -= len(w)
290 del ws[-1]
291 else:
292 return False
293
294 if startpos > endpos:
295 # Exact end matches required more characters than we have, as in
Tim Petersb0a04e12004-08-20 02:08:04 +0000296 # _ellipsis_match('aa...aa', 'aaa')
Tim Petersdc5de3b2004-08-19 14:06:20 +0000297 return False
298
299 # For the rest, we only need to find the leftmost non-overlapping
300 # match for each piece. If there's no overall match that way alone,
301 # there's no overall match period.
Tim Peters26b3ebb2004-08-19 08:10:08 +0000302 for w in ws:
303 # w may be '' at times, if there are consecutive ellipses, or
304 # due to an ellipsis at the start or end of `want`. That's OK.
Tim Petersdc5de3b2004-08-19 14:06:20 +0000305 # Search for an empty string succeeds, and doesn't change startpos.
306 startpos = got.find(w, startpos, endpos)
307 if startpos < 0:
Tim Peters26b3ebb2004-08-19 08:10:08 +0000308 return False
Tim Petersdc5de3b2004-08-19 14:06:20 +0000309 startpos += len(w)
Tim Peters26b3ebb2004-08-19 08:10:08 +0000310
Tim Petersdc5de3b2004-08-19 14:06:20 +0000311 return True
Tim Peters26b3ebb2004-08-19 08:10:08 +0000312
Edward Loper00f8da72004-08-26 18:05:07 +0000313def _comment_line(line):
314 "Return a commented form of the given line"
315 line = line.rstrip()
316 if line:
317 return '# '+line
318 else:
319 return '#'
320
Tim Petersf9a07f22013-12-03 21:02:05 -0600321def _strip_exception_details(msg):
322 # Support for IGNORE_EXCEPTION_DETAIL.
323 # Get rid of everything except the exception name; in particular, drop
324 # the possibly dotted module path (if any) and the exception message (if
325 # any). We assume that a colon is never part of a dotted name, or of an
326 # exception name.
327 # E.g., given
328 # "foo.bar.MyError: la di da"
329 # return "MyError"
330 # Or for "abc.def" or "abc.def:\n" return "def".
331
332 start, end = 0, len(msg)
333 # The exception name must appear on the first line.
334 i = msg.find("\n")
335 if i >= 0:
336 end = i
337 # retain up to the first colon (if any)
338 i = msg.find(':', 0, end)
339 if i >= 0:
340 end = i
341 # retain just the exception name
342 i = msg.rfind('.', 0, end)
343 if i >= 0:
344 start = i+1
345 return msg[start: end]
346
Edward Loper2de91ba2004-08-27 02:07:46 +0000347class _OutputRedirectingPdb(pdb.Pdb):
348 """
349 A specialized version of the python debugger that redirects stdout
350 to a given stream when interacting with the user. Stdout is *not*
351 redirected when traced code is executed.
352 """
353 def __init__(self, out):
354 self.__out = out
Guido van Rossum0d3fb8a2007-11-26 23:23:18 +0000355 self.__debugger_used = False
Georg Brandl34748cd2010-12-04 17:11:36 +0000356 # do not play signal games in the pdb
357 pdb.Pdb.__init__(self, stdout=out, nosigint=True)
Georg Brandld72e0432010-07-30 09:59:28 +0000358 # still use input() to get user input
359 self.use_rawinput = 1
Edward Loper2de91ba2004-08-27 02:07:46 +0000360
Guido van Rossum0d3fb8a2007-11-26 23:23:18 +0000361 def set_trace(self, frame=None):
362 self.__debugger_used = True
363 if frame is None:
364 frame = sys._getframe().f_back
365 pdb.Pdb.set_trace(self, frame)
366
367 def set_continue(self):
368 # Calling set_continue unconditionally would break unit test
369 # coverage reporting, as Bdb.set_continue calls sys.settrace(None).
370 if self.__debugger_used:
371 pdb.Pdb.set_continue(self)
372
Edward Loper2de91ba2004-08-27 02:07:46 +0000373 def trace_dispatch(self, *args):
374 # Redirect stdout to the given stream.
375 save_stdout = sys.stdout
376 sys.stdout = self.__out
377 # Call Pdb's trace dispatch method.
Tim Petersd7bbbbc2004-11-08 22:30:28 +0000378 try:
379 return pdb.Pdb.trace_dispatch(self, *args)
380 finally:
Tim Petersd7bbbbc2004-11-08 22:30:28 +0000381 sys.stdout = save_stdout
Edward Loper2de91ba2004-08-27 02:07:46 +0000382
Edward Lopera2fc7ec2004-09-21 03:24:24 +0000383# [XX] Normalize with respect to os.path.pardir?
Edward Loper052d0cd2004-09-19 17:19:33 +0000384def _module_relative_path(module, path):
385 if not inspect.ismodule(module):
Collin Winterce36ad82007-08-30 01:19:48 +0000386 raise TypeError('Expected a module: %r' % module)
Edward Loper052d0cd2004-09-19 17:19:33 +0000387 if path.startswith('/'):
Collin Winterce36ad82007-08-30 01:19:48 +0000388 raise ValueError('Module-relative files may not have absolute paths')
Edward Loper052d0cd2004-09-19 17:19:33 +0000389
390 # Find the base directory for the path.
391 if hasattr(module, '__file__'):
392 # A normal module/package
393 basedir = os.path.split(module.__file__)[0]
394 elif module.__name__ == '__main__':
395 # An interactive session.
396 if len(sys.argv)>0 and sys.argv[0] != '':
397 basedir = os.path.split(sys.argv[0])[0]
398 else:
399 basedir = os.curdir
400 else:
401 # A module w/o __file__ (this includes builtins)
402 raise ValueError("Can't resolve paths relative to the module " +
403 module + " (it has no __file__)")
404
405 # Combine the base directory and the path.
406 return os.path.join(basedir, *(path.split('/')))
407
Tim Peters8485b562004-08-04 18:46:34 +0000408######################################################################
409## 2. Example & DocTest
410######################################################################
411## - An "example" is a <source, want> pair, where "source" is a
412## fragment of source code, and "want" is the expected output for
413## "source." The Example class also includes information about
414## where the example was extracted from.
415##
Edward Lopera1ef6112004-08-09 16:14:41 +0000416## - A "doctest" is a collection of examples, typically extracted from
417## a string (such as an object's docstring). The DocTest class also
418## includes information about where the string was extracted from.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000419
Tim Peters8485b562004-08-04 18:46:34 +0000420class Example:
421 """
422 A single doctest example, consisting of source code and expected
Edward Lopera1ef6112004-08-09 16:14:41 +0000423 output. `Example` defines the following attributes:
Tim Peters8a7d2d52001-01-16 07:10:57 +0000424
Edward Loper74bca7a2004-08-12 02:27:44 +0000425 - source: A single Python statement, always ending with a newline.
Tim Petersbb431472004-08-09 03:51:46 +0000426 The constructor adds a newline if needed.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000427
Edward Loper74bca7a2004-08-12 02:27:44 +0000428 - want: The expected output from running the source code (either
Tim Petersbb431472004-08-09 03:51:46 +0000429 from stdout, or a traceback in case of exception). `want` ends
430 with a newline unless it's empty, in which case it's an empty
431 string. The constructor adds a newline if needed.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000432
Edward Lopera6b68322004-08-26 00:05:43 +0000433 - exc_msg: The exception message generated by the example, if
434 the example is expected to generate an exception; or `None` if
435 it is not expected to generate an exception. This exception
436 message is compared against the return value of
437 `traceback.format_exception_only()`. `exc_msg` ends with a
438 newline unless it's `None`. The constructor adds a newline
439 if needed.
440
Edward Loper74bca7a2004-08-12 02:27:44 +0000441 - lineno: The line number within the DocTest string containing
Tim Peters8485b562004-08-04 18:46:34 +0000442 this Example where the Example begins. This line number is
443 zero-based, with respect to the beginning of the DocTest.
Edward Loper74bca7a2004-08-12 02:27:44 +0000444
445 - indent: The example's indentation in the DocTest string.
Ezio Melotti30b9d5d2013-08-17 15:50:46 +0300446 I.e., the number of space characters that precede the
Edward Loper74bca7a2004-08-12 02:27:44 +0000447 example's first prompt.
448
449 - options: A dictionary mapping from option flags to True or
450 False, which is used to override default options for this
451 example. Any option flags not contained in this dictionary
452 are left at their default value (as specified by the
453 DocTestRunner's optionflags). By default, no options are set.
Tim Peters8485b562004-08-04 18:46:34 +0000454 """
Edward Lopera6b68322004-08-26 00:05:43 +0000455 def __init__(self, source, want, exc_msg=None, lineno=0, indent=0,
456 options=None):
Tim Petersbb431472004-08-09 03:51:46 +0000457 # Normalize inputs.
458 if not source.endswith('\n'):
459 source += '\n'
460 if want and not want.endswith('\n'):
461 want += '\n'
Edward Lopera6b68322004-08-26 00:05:43 +0000462 if exc_msg is not None and not exc_msg.endswith('\n'):
463 exc_msg += '\n'
Tim Peters8485b562004-08-04 18:46:34 +0000464 # Store properties.
465 self.source = source
466 self.want = want
467 self.lineno = lineno
Edward Loper74bca7a2004-08-12 02:27:44 +0000468 self.indent = indent
469 if options is None: options = {}
470 self.options = options
Edward Lopera6b68322004-08-26 00:05:43 +0000471 self.exc_msg = exc_msg
Tim Peters8a7d2d52001-01-16 07:10:57 +0000472
Antoine Pitrou2bc801c2011-12-18 19:27:45 +0100473 def __eq__(self, other):
474 if type(self) is not type(other):
475 return NotImplemented
476
477 return self.source == other.source and \
478 self.want == other.want and \
479 self.lineno == other.lineno and \
480 self.indent == other.indent and \
481 self.options == other.options and \
482 self.exc_msg == other.exc_msg
483
484 def __ne__(self, other):
485 return not self == other
486
Antoine Pitrou165b1282011-12-18 20:20:17 +0100487 def __hash__(self):
488 return hash((self.source, self.want, self.lineno, self.indent,
489 self.exc_msg))
Antoine Pitrou2bc801c2011-12-18 19:27:45 +0100490
Tim Peters8485b562004-08-04 18:46:34 +0000491class DocTest:
492 """
493 A collection of doctest examples that should be run in a single
Edward Lopera1ef6112004-08-09 16:14:41 +0000494 namespace. Each `DocTest` defines the following attributes:
Tim Peters8a7d2d52001-01-16 07:10:57 +0000495
Tim Peters8485b562004-08-04 18:46:34 +0000496 - examples: the list of examples.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000497
Tim Peters8485b562004-08-04 18:46:34 +0000498 - globs: The namespace (aka globals) that the examples should
499 be run in.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000500
Tim Peters8485b562004-08-04 18:46:34 +0000501 - name: A name identifying the DocTest (typically, the name of
502 the object whose docstring this DocTest was extracted from).
Tim Peters8a7d2d52001-01-16 07:10:57 +0000503
Tim Peters8485b562004-08-04 18:46:34 +0000504 - filename: The name of the file that this DocTest was extracted
Edward Lopera1ef6112004-08-09 16:14:41 +0000505 from, or `None` if the filename is unknown.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000506
Tim Peters8485b562004-08-04 18:46:34 +0000507 - lineno: The line number within filename where this DocTest
Edward Lopera1ef6112004-08-09 16:14:41 +0000508 begins, or `None` if the line number is unavailable. This
509 line number is zero-based, with respect to the beginning of
510 the file.
511
512 - docstring: The string that the examples were extracted from,
513 or `None` if the string is unavailable.
Tim Peters8485b562004-08-04 18:46:34 +0000514 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000515 def __init__(self, examples, globs, name, filename, lineno, docstring):
Tim Peters8485b562004-08-04 18:46:34 +0000516 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000517 Create a new DocTest containing the given examples. The
518 DocTest's globals are initialized with a copy of `globs`.
Tim Peters8485b562004-08-04 18:46:34 +0000519 """
Guido van Rossum3172c5d2007-10-16 18:12:55 +0000520 assert not isinstance(examples, str), \
Edward Lopera1ef6112004-08-09 16:14:41 +0000521 "DocTest no longer accepts str; use DocTestParser instead"
522 self.examples = examples
523 self.docstring = docstring
Tim Peters8485b562004-08-04 18:46:34 +0000524 self.globs = globs.copy()
Tim Peters8485b562004-08-04 18:46:34 +0000525 self.name = name
526 self.filename = filename
527 self.lineno = lineno
Tim Peters8485b562004-08-04 18:46:34 +0000528
529 def __repr__(self):
530 if len(self.examples) == 0:
531 examples = 'no examples'
532 elif len(self.examples) == 1:
533 examples = '1 example'
534 else:
535 examples = '%d examples' % len(self.examples)
Serhiy Storchaka465e60e2014-07-25 23:36:00 +0300536 return ('<%s %s from %s:%s (%s)>' %
537 (self.__class__.__name__,
538 self.name, self.filename, self.lineno, examples))
Tim Peters8485b562004-08-04 18:46:34 +0000539
Antoine Pitrou2bc801c2011-12-18 19:27:45 +0100540 def __eq__(self, other):
541 if type(self) is not type(other):
542 return NotImplemented
543
544 return self.examples == other.examples and \
545 self.docstring == other.docstring and \
546 self.globs == other.globs and \
547 self.name == other.name and \
548 self.filename == other.filename and \
549 self.lineno == other.lineno
550
551 def __ne__(self, other):
552 return not self == other
Tim Peters8485b562004-08-04 18:46:34 +0000553
Antoine Pitrou165b1282011-12-18 20:20:17 +0100554 def __hash__(self):
555 return hash((self.docstring, self.name, self.filename, self.lineno))
556
Tim Peters8485b562004-08-04 18:46:34 +0000557 # This lets us sort tests by name:
Guido van Rossum47b9ff62006-08-24 00:41:19 +0000558 def __lt__(self, other):
Tim Peters8485b562004-08-04 18:46:34 +0000559 if not isinstance(other, DocTest):
Guido van Rossum47b9ff62006-08-24 00:41:19 +0000560 return NotImplemented
561 return ((self.name, self.filename, self.lineno, id(self))
562 <
563 (other.name, other.filename, other.lineno, id(other)))
Tim Peters8485b562004-08-04 18:46:34 +0000564
565######################################################################
Edward Loperb7503ff2004-08-19 19:19:03 +0000566## 3. DocTestParser
Edward Loper7c748462004-08-09 02:06:06 +0000567######################################################################
568
Edward Lopera1ef6112004-08-09 16:14:41 +0000569class DocTestParser:
Edward Loper7c748462004-08-09 02:06:06 +0000570 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000571 A class used to parse strings containing doctest examples.
Edward Loper7c748462004-08-09 02:06:06 +0000572 """
Edward Loper8e4a34b2004-08-12 02:34:27 +0000573 # This regular expression is used to find doctest examples in a
574 # string. It defines three groups: `source` is the source code
575 # (including leading indentation and prompts); `indent` is the
576 # indentation of the first (PS1) line of the source code; and
577 # `want` is the expected output (including leading indentation).
Edward Loper7c748462004-08-09 02:06:06 +0000578 _EXAMPLE_RE = re.compile(r'''
Tim Petersd40a92b2004-08-09 03:28:45 +0000579 # Source consists of a PS1 line followed by zero or more PS2 lines.
580 (?P<source>
581 (?:^(?P<indent> [ ]*) >>> .*) # PS1 line
582 (?:\n [ ]* \.\.\. .*)*) # PS2 lines
583 \n?
584 # Want consists of any non-blank lines that do not start with PS1.
585 (?P<want> (?:(?![ ]*$) # Not a blank line
586 (?![ ]*>>>) # Not a line starting with PS1
Serhiy Storchaka1ca66ed2013-08-19 22:59:31 +0300587 .+$\n? # But any other line
Tim Petersd40a92b2004-08-09 03:28:45 +0000588 )*)
589 ''', re.MULTILINE | re.VERBOSE)
Edward Loper8e4a34b2004-08-12 02:34:27 +0000590
Edward Lopera6b68322004-08-26 00:05:43 +0000591 # A regular expression for handling `want` strings that contain
592 # expected exceptions. It divides `want` into three pieces:
593 # - the traceback header line (`hdr`)
594 # - the traceback stack (`stack`)
595 # - the exception message (`msg`), as generated by
596 # traceback.format_exception_only()
597 # `msg` may have multiple lines. We assume/require that the
598 # exception message is the first non-indented line starting with a word
599 # character following the traceback header line.
600 _EXCEPTION_RE = re.compile(r"""
601 # Grab the traceback header. Different versions of Python have
602 # said different things on the first traceback line.
603 ^(?P<hdr> Traceback\ \(
604 (?: most\ recent\ call\ last
605 | innermost\ last
606 ) \) :
607 )
608 \s* $ # toss trailing whitespace on the header.
609 (?P<stack> .*?) # don't blink: absorb stuff until...
610 ^ (?P<msg> \w+ .*) # a line *starts* with alphanum.
611 """, re.VERBOSE | re.MULTILINE | re.DOTALL)
612
Tim Peters7ea48dd2004-08-13 01:52:59 +0000613 # A callable returning a true value iff its argument is a blank line
614 # or contains a single comment.
Edward Loper8e4a34b2004-08-12 02:34:27 +0000615 _IS_BLANK_OR_COMMENT = re.compile(r'^[ ]*(#.*)?$').match
Edward Loper7c748462004-08-09 02:06:06 +0000616
Edward Loper00f8da72004-08-26 18:05:07 +0000617 def parse(self, string, name='<string>'):
618 """
619 Divide the given string into examples and intervening text,
620 and return them as a list of alternating Examples and strings.
621 Line numbers for the Examples are 0-based. The optional
622 argument `name` is a name identifying this string, and is only
623 used for error messages.
624 """
625 string = string.expandtabs()
626 # If all lines begin with the same indentation, then strip it.
627 min_indent = self._min_indent(string)
628 if min_indent > 0:
629 string = '\n'.join([l[min_indent:] for l in string.split('\n')])
630
631 output = []
632 charno, lineno = 0, 0
633 # Find all doctest examples in the string:
Edward Loper2de91ba2004-08-27 02:07:46 +0000634 for m in self._EXAMPLE_RE.finditer(string):
Edward Loper00f8da72004-08-26 18:05:07 +0000635 # Add the pre-example text to `output`.
636 output.append(string[charno:m.start()])
637 # Update lineno (lines before this example)
638 lineno += string.count('\n', charno, m.start())
639 # Extract info from the regexp match.
640 (source, options, want, exc_msg) = \
641 self._parse_example(m, name, lineno)
642 # Create an Example, and add it to the list.
643 if not self._IS_BLANK_OR_COMMENT(source):
644 output.append( Example(source, want, exc_msg,
645 lineno=lineno,
646 indent=min_indent+len(m.group('indent')),
647 options=options) )
648 # Update lineno (lines inside this example)
649 lineno += string.count('\n', m.start(), m.end())
650 # Update charno.
651 charno = m.end()
652 # Add any remaining post-example text to `output`.
653 output.append(string[charno:])
654 return output
655
Edward Lopera1ef6112004-08-09 16:14:41 +0000656 def get_doctest(self, string, globs, name, filename, lineno):
Edward Loper7c748462004-08-09 02:06:06 +0000657 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000658 Extract all doctest examples from the given string, and
659 collect them into a `DocTest` object.
660
661 `globs`, `name`, `filename`, and `lineno` are attributes for
662 the new `DocTest` object. See the documentation for `DocTest`
663 for more information.
664 """
665 return DocTest(self.get_examples(string, name), globs,
666 name, filename, lineno, string)
667
668 def get_examples(self, string, name='<string>'):
669 """
670 Extract all doctest examples from the given string, and return
671 them as a list of `Example` objects. Line numbers are
672 0-based, because it's most common in doctests that nothing
673 interesting appears on the same line as opening triple-quote,
674 and so the first interesting line is called \"line 1\" then.
675
676 The optional argument `name` is a name identifying this
677 string, and is only used for error messages.
Edward Loper7c748462004-08-09 02:06:06 +0000678 """
Edward Loper00f8da72004-08-26 18:05:07 +0000679 return [x for x in self.parse(string, name)
680 if isinstance(x, Example)]
Edward Loper7c748462004-08-09 02:06:06 +0000681
Edward Loper74bca7a2004-08-12 02:27:44 +0000682 def _parse_example(self, m, name, lineno):
683 """
684 Given a regular expression match from `_EXAMPLE_RE` (`m`),
685 return a pair `(source, want)`, where `source` is the matched
686 example's source code (with prompts and indentation stripped);
687 and `want` is the example's expected output (with indentation
688 stripped).
689
690 `name` is the string's name, and `lineno` is the line number
691 where the example starts; both are used for error messages.
692 """
Edward Loper7c748462004-08-09 02:06:06 +0000693 # Get the example's indentation level.
694 indent = len(m.group('indent'))
695
696 # Divide source into lines; check that they're properly
697 # indented; and then strip their indentation & prompts.
698 source_lines = m.group('source').split('\n')
Edward Lopera1ef6112004-08-09 16:14:41 +0000699 self._check_prompt_blank(source_lines, indent, name, lineno)
Tim Petersc5049152004-08-22 17:34:58 +0000700 self._check_prefix(source_lines[1:], ' '*indent + '.', name, lineno)
Edward Loper7c748462004-08-09 02:06:06 +0000701 source = '\n'.join([sl[indent+4:] for sl in source_lines])
Edward Loper7c748462004-08-09 02:06:06 +0000702
Tim Petersc5049152004-08-22 17:34:58 +0000703 # Divide want into lines; check that it's properly indented; and
704 # then strip the indentation. Spaces before the last newline should
705 # be preserved, so plain rstrip() isn't good enough.
Jim Fulton07a349c2004-08-22 14:10:00 +0000706 want = m.group('want')
Jim Fulton07a349c2004-08-22 14:10:00 +0000707 want_lines = want.split('\n')
Tim Petersc5049152004-08-22 17:34:58 +0000708 if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]):
709 del want_lines[-1] # forget final newline & spaces after it
Edward Lopera1ef6112004-08-09 16:14:41 +0000710 self._check_prefix(want_lines, ' '*indent, name,
Tim Petersc5049152004-08-22 17:34:58 +0000711 lineno + len(source_lines))
Edward Loper7c748462004-08-09 02:06:06 +0000712 want = '\n'.join([wl[indent:] for wl in want_lines])
Edward Loper7c748462004-08-09 02:06:06 +0000713
Edward Lopera6b68322004-08-26 00:05:43 +0000714 # If `want` contains a traceback message, then extract it.
715 m = self._EXCEPTION_RE.match(want)
716 if m:
717 exc_msg = m.group('msg')
718 else:
719 exc_msg = None
720
Edward Loper00f8da72004-08-26 18:05:07 +0000721 # Extract options from the source.
722 options = self._find_options(source, name, lineno)
723
724 return source, options, want, exc_msg
Edward Loper7c748462004-08-09 02:06:06 +0000725
Edward Loper74bca7a2004-08-12 02:27:44 +0000726 # This regular expression looks for option directives in the
727 # source code of an example. Option directives are comments
728 # starting with "doctest:". Warning: this may give false
729 # positives for string-literals that contain the string
730 # "#doctest:". Eliminating these false positives would require
731 # actually parsing the string; but we limit them by ignoring any
732 # line containing "#doctest:" that is *followed* by a quote mark.
733 _OPTION_DIRECTIVE_RE = re.compile(r'#\s*doctest:\s*([^\n\'"]*)$',
734 re.MULTILINE)
735
736 def _find_options(self, source, name, lineno):
737 """
738 Return a dictionary containing option overrides extracted from
739 option directives in the given source string.
740
741 `name` is the string's name, and `lineno` is the line number
742 where the example starts; both are used for error messages.
743 """
744 options = {}
745 # (note: with the current regexp, this will match at most once:)
746 for m in self._OPTION_DIRECTIVE_RE.finditer(source):
747 option_strings = m.group(1).replace(',', ' ').split()
748 for option in option_strings:
749 if (option[0] not in '+-' or
750 option[1:] not in OPTIONFLAGS_BY_NAME):
751 raise ValueError('line %r of the doctest for %s '
752 'has an invalid option: %r' %
753 (lineno+1, name, option))
754 flag = OPTIONFLAGS_BY_NAME[option[1:]]
755 options[flag] = (option[0] == '+')
756 if options and self._IS_BLANK_OR_COMMENT(source):
757 raise ValueError('line %r of the doctest for %s has an option '
758 'directive on a line with no example: %r' %
759 (lineno, name, source))
760 return options
761
Edward Lopera5db6002004-08-12 02:41:30 +0000762 # This regular expression finds the indentation of every non-blank
763 # line in a string.
Edward Loper00f8da72004-08-26 18:05:07 +0000764 _INDENT_RE = re.compile('^([ ]*)(?=\S)', re.MULTILINE)
Edward Lopera5db6002004-08-12 02:41:30 +0000765
766 def _min_indent(self, s):
767 "Return the minimum indentation of any non-blank line in `s`"
Edward Loper00f8da72004-08-26 18:05:07 +0000768 indents = [len(indent) for indent in self._INDENT_RE.findall(s)]
769 if len(indents) > 0:
770 return min(indents)
Tim Petersdd0e4752004-08-09 03:31:56 +0000771 else:
Edward Loper00f8da72004-08-26 18:05:07 +0000772 return 0
Edward Loper7c748462004-08-09 02:06:06 +0000773
Edward Lopera1ef6112004-08-09 16:14:41 +0000774 def _check_prompt_blank(self, lines, indent, name, lineno):
Edward Loper74bca7a2004-08-12 02:27:44 +0000775 """
776 Given the lines of a source string (including prompts and
777 leading indentation), check to make sure that every prompt is
778 followed by a space character. If any line is not followed by
779 a space character, then raise ValueError.
780 """
Edward Loper7c748462004-08-09 02:06:06 +0000781 for i, line in enumerate(lines):
782 if len(line) >= indent+4 and line[indent+3] != ' ':
783 raise ValueError('line %r of the docstring for %s '
784 'lacks blank after %s: %r' %
Edward Lopera1ef6112004-08-09 16:14:41 +0000785 (lineno+i+1, name,
Edward Loper7c748462004-08-09 02:06:06 +0000786 line[indent:indent+3], line))
787
Edward Lopera1ef6112004-08-09 16:14:41 +0000788 def _check_prefix(self, lines, prefix, name, lineno):
Edward Loper74bca7a2004-08-12 02:27:44 +0000789 """
790 Check that every line in the given list starts with the given
791 prefix; if any line does not, then raise a ValueError.
792 """
Edward Loper7c748462004-08-09 02:06:06 +0000793 for i, line in enumerate(lines):
794 if line and not line.startswith(prefix):
795 raise ValueError('line %r of the docstring for %s has '
796 'inconsistent leading whitespace: %r' %
Edward Lopera1ef6112004-08-09 16:14:41 +0000797 (lineno+i+1, name, line))
Edward Loper7c748462004-08-09 02:06:06 +0000798
799
800######################################################################
801## 4. DocTest Finder
Tim Peters8485b562004-08-04 18:46:34 +0000802######################################################################
803
804class DocTestFinder:
805 """
806 A class used to extract the DocTests that are relevant to a given
807 object, from its docstring and the docstrings of its contained
808 objects. Doctests can currently be extracted from the following
809 object types: modules, functions, classes, methods, staticmethods,
810 classmethods, and properties.
Tim Peters8485b562004-08-04 18:46:34 +0000811 """
812
Edward Lopera1ef6112004-08-09 16:14:41 +0000813 def __init__(self, verbose=False, parser=DocTestParser(),
Thomas Wouters73e5a5b2006-06-08 15:35:45 +0000814 recurse=True, exclude_empty=True):
Tim Peters8485b562004-08-04 18:46:34 +0000815 """
816 Create a new doctest finder.
817
Edward Lopera1ef6112004-08-09 16:14:41 +0000818 The optional argument `parser` specifies a class or
Tim Peters19397e52004-08-06 22:02:59 +0000819 function that should be used to create new DocTest objects (or
Tim Peters161c9632004-08-08 03:38:33 +0000820 objects that implement the same interface as DocTest). The
Tim Peters19397e52004-08-06 22:02:59 +0000821 signature for this factory function should match the signature
822 of the DocTest constructor.
823
Tim Peters8485b562004-08-04 18:46:34 +0000824 If the optional argument `recurse` is false, then `find` will
825 only examine the given object, and not any contained objects.
Edward Loper32ddbf72004-09-13 05:47:24 +0000826
Tim Peters958cc892004-09-13 14:53:28 +0000827 If the optional argument `exclude_empty` is false, then `find`
828 will include tests for objects with empty docstrings.
Tim Peters8485b562004-08-04 18:46:34 +0000829 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000830 self._parser = parser
Tim Peters8485b562004-08-04 18:46:34 +0000831 self._verbose = verbose
Tim Peters8485b562004-08-04 18:46:34 +0000832 self._recurse = recurse
Edward Loper32ddbf72004-09-13 05:47:24 +0000833 self._exclude_empty = exclude_empty
Tim Peters8485b562004-08-04 18:46:34 +0000834
Thomas Wouters73e5a5b2006-06-08 15:35:45 +0000835 def find(self, obj, name=None, module=None, globs=None, extraglobs=None):
Tim Peters8485b562004-08-04 18:46:34 +0000836 """
837 Return a list of the DocTests that are defined by the given
838 object's docstring, or by any of its contained objects'
839 docstrings.
840
841 The optional parameter `module` is the module that contains
Tim Petersf3f57472004-08-08 06:11:48 +0000842 the given object. If the module is not specified or is None, then
843 the test finder will attempt to automatically determine the
Tim Peters8485b562004-08-04 18:46:34 +0000844 correct module. The object's module is used:
845
846 - As a default namespace, if `globs` is not specified.
847 - To prevent the DocTestFinder from extracting DocTests
Tim Petersf3f57472004-08-08 06:11:48 +0000848 from objects that are imported from other modules.
Tim Peters8485b562004-08-04 18:46:34 +0000849 - To find the name of the file containing the object.
850 - To help find the line number of the object within its
851 file.
852
Tim Petersf3f57472004-08-08 06:11:48 +0000853 Contained objects whose module does not match `module` are ignored.
854
855 If `module` is False, no attempt to find the module will be made.
856 This is obscure, of use mostly in tests: if `module` is False, or
857 is None but cannot be found automatically, then all objects are
858 considered to belong to the (non-existent) module, so all contained
859 objects will (recursively) be searched for doctests.
860
Tim Peters8485b562004-08-04 18:46:34 +0000861 The globals for each DocTest is formed by combining `globs`
862 and `extraglobs` (bindings in `extraglobs` override bindings
863 in `globs`). A new copy of the globals dictionary is created
864 for each DocTest. If `globs` is not specified, then it
865 defaults to the module's `__dict__`, if specified, or {}
866 otherwise. If `extraglobs` is not specified, then it defaults
867 to {}.
868
Tim Peters8485b562004-08-04 18:46:34 +0000869 """
870 # If name was not specified, then extract it from the object.
871 if name is None:
872 name = getattr(obj, '__name__', None)
873 if name is None:
874 raise ValueError("DocTestFinder.find: name must be given "
875 "when obj.__name__ doesn't exist: %r" %
876 (type(obj),))
877
878 # Find the module that contains the given object (if obj is
879 # a module, then module=obj.). Note: this may fail, in which
880 # case module will be None.
Tim Petersf3f57472004-08-08 06:11:48 +0000881 if module is False:
882 module = None
883 elif module is None:
Tim Peters8485b562004-08-04 18:46:34 +0000884 module = inspect.getmodule(obj)
885
886 # Read the module's source code. This is used by
887 # DocTestFinder._find_lineno to find the line number for a
888 # given object's docstring.
889 try:
R. David Murray58641de2009-06-12 15:33:19 +0000890 file = inspect.getsourcefile(obj)
Tim Peters8485b562004-08-04 18:46:34 +0000891 except TypeError:
892 source_lines = None
R. David Murray58641de2009-06-12 15:33:19 +0000893 else:
894 if not file:
895 # Check to see if it's one of our special internal "files"
896 # (see __patched_linecache_getlines).
897 file = inspect.getfile(obj)
898 if not file[0]+file[-2:] == '<]>': file = None
R. David Murray765b9762009-07-15 14:16:54 +0000899 if file is None:
900 source_lines = None
R. David Murray58641de2009-06-12 15:33:19 +0000901 else:
902 if module is not None:
903 # Supply the module globals in case the module was
904 # originally loaded via a PEP 302 loader and
905 # file is not a valid filesystem path
906 source_lines = linecache.getlines(file, module.__dict__)
907 else:
908 # No access to a loader, so assume it's a normal
909 # filesystem path
910 source_lines = linecache.getlines(file)
911 if not source_lines:
912 source_lines = None
Tim Peters8485b562004-08-04 18:46:34 +0000913
914 # Initialize globals, and merge in extraglobs.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000915 if globs is None:
Tim Peters8485b562004-08-04 18:46:34 +0000916 if module is None:
917 globs = {}
918 else:
919 globs = module.__dict__.copy()
920 else:
921 globs = globs.copy()
922 if extraglobs is not None:
923 globs.update(extraglobs)
Raymond Hettinger0f055172009-01-27 10:06:09 +0000924 if '__name__' not in globs:
925 globs['__name__'] = '__main__' # provide a default module name
Tim Peters8a7d2d52001-01-16 07:10:57 +0000926
Ezio Melotti30b9d5d2013-08-17 15:50:46 +0300927 # Recursively explore `obj`, extracting DocTests.
Tim Peters8485b562004-08-04 18:46:34 +0000928 tests = []
Tim Petersf3f57472004-08-08 06:11:48 +0000929 self._find(tests, obj, name, module, source_lines, globs, {})
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000930 # Sort the tests by alpha order of names, for consistency in
931 # verbose-mode output. This was a feature of doctest in Pythons
932 # <= 2.3 that got lost by accident in 2.4. It was repaired in
933 # 2.4.4 and 2.5.
934 tests.sort()
Tim Peters8485b562004-08-04 18:46:34 +0000935 return tests
936
Tim Peters8485b562004-08-04 18:46:34 +0000937 def _from_module(self, module, object):
938 """
939 Return true if the given object is defined in the given
940 module.
941 """
942 if module is None:
943 return True
Benjamin Peterson6cadba72008-11-19 22:38:29 +0000944 elif inspect.getmodule(object) is not None:
945 return module is inspect.getmodule(object)
Tim Peters8485b562004-08-04 18:46:34 +0000946 elif inspect.isfunction(object):
Neal Norwitz221085d2007-02-25 20:55:47 +0000947 return module.__dict__ is object.__globals__
Zachary Warea4b7a752013-11-24 01:19:09 -0600948 elif inspect.ismethoddescriptor(object):
Zachary Wareeee44f22014-02-06 15:46:38 -0600949 if hasattr(object, '__objclass__'):
950 obj_mod = object.__objclass__.__module__
951 elif hasattr(object, '__module__'):
952 obj_mod = object.__module__
953 else:
954 return True # [XX] no easy way to tell otherwise
955 return module.__name__ == obj_mod
Tim Peters8485b562004-08-04 18:46:34 +0000956 elif inspect.isclass(object):
957 return module.__name__ == object.__module__
Tim Peters8485b562004-08-04 18:46:34 +0000958 elif hasattr(object, '__module__'):
959 return module.__name__ == object.__module__
960 elif isinstance(object, property):
961 return True # [XX] no way not be sure.
962 else:
963 raise ValueError("object must be a class or function")
964
Tim Petersf3f57472004-08-08 06:11:48 +0000965 def _find(self, tests, obj, name, module, source_lines, globs, seen):
Tim Peters8485b562004-08-04 18:46:34 +0000966 """
967 Find tests for the given object and any contained objects, and
968 add them to `tests`.
969 """
970 if self._verbose:
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000971 print('Finding tests in %s' % name)
Tim Peters8485b562004-08-04 18:46:34 +0000972
973 # If we've already processed this object, then ignore it.
974 if id(obj) in seen:
975 return
976 seen[id(obj)] = 1
977
978 # Find a test for this object, and add it to the list of tests.
979 test = self._get_test(obj, name, module, globs, source_lines)
980 if test is not None:
981 tests.append(test)
982
983 # Look for tests in a module's contained objects.
984 if inspect.ismodule(obj) and self._recurse:
985 for valname, val in obj.__dict__.items():
Tim Peters8485b562004-08-04 18:46:34 +0000986 valname = '%s.%s' % (name, valname)
987 # Recurse to functions & classes.
Yury Selivanovb532df62014-12-08 15:00:05 -0500988 if ((inspect.isroutine(inspect.unwrap(val))
989 or inspect.isclass(val)) and
Tim Petersf3f57472004-08-08 06:11:48 +0000990 self._from_module(module, val)):
Tim Peters8485b562004-08-04 18:46:34 +0000991 self._find(tests, val, valname, module, source_lines,
Tim Petersf3f57472004-08-08 06:11:48 +0000992 globs, seen)
Tim Peters8485b562004-08-04 18:46:34 +0000993
994 # Look for tests in a module's __test__ dictionary.
995 if inspect.ismodule(obj) and self._recurse:
996 for valname, val in getattr(obj, '__test__', {}).items():
Guido van Rossum3172c5d2007-10-16 18:12:55 +0000997 if not isinstance(valname, str):
Tim Peters8485b562004-08-04 18:46:34 +0000998 raise ValueError("DocTestFinder.find: __test__ keys "
999 "must be strings: %r" %
1000 (type(valname),))
Zachary Warea4b7a752013-11-24 01:19:09 -06001001 if not (inspect.isroutine(val) or inspect.isclass(val) or
1002 inspect.ismodule(val) or isinstance(val, str)):
Tim Peters8485b562004-08-04 18:46:34 +00001003 raise ValueError("DocTestFinder.find: __test__ values "
1004 "must be strings, functions, methods, "
1005 "classes, or modules: %r" %
1006 (type(val),))
Tim Petersc5684782004-09-13 01:07:12 +00001007 valname = '%s.__test__.%s' % (name, valname)
Tim Peters8485b562004-08-04 18:46:34 +00001008 self._find(tests, val, valname, module, source_lines,
Tim Petersf3f57472004-08-08 06:11:48 +00001009 globs, seen)
Tim Peters8485b562004-08-04 18:46:34 +00001010
1011 # Look for tests in a class's contained objects.
1012 if inspect.isclass(obj) and self._recurse:
1013 for valname, val in obj.__dict__.items():
Tim Peters8485b562004-08-04 18:46:34 +00001014 # Special handling for staticmethod/classmethod.
1015 if isinstance(val, staticmethod):
1016 val = getattr(obj, valname)
1017 if isinstance(val, classmethod):
Christian Heimesff737952007-11-27 10:40:20 +00001018 val = getattr(obj, valname).__func__
Tim Peters8485b562004-08-04 18:46:34 +00001019
1020 # Recurse to methods, properties, and nested classes.
Zachary Warea4b7a752013-11-24 01:19:09 -06001021 if ((inspect.isroutine(val) or inspect.isclass(val) or
Tim Petersf3f57472004-08-08 06:11:48 +00001022 isinstance(val, property)) and
1023 self._from_module(module, val)):
Tim Peters8485b562004-08-04 18:46:34 +00001024 valname = '%s.%s' % (name, valname)
1025 self._find(tests, val, valname, module, source_lines,
Tim Petersf3f57472004-08-08 06:11:48 +00001026 globs, seen)
Tim Peters8485b562004-08-04 18:46:34 +00001027
1028 def _get_test(self, obj, name, module, globs, source_lines):
1029 """
1030 Return a DocTest for the given object, if it defines a docstring;
1031 otherwise, return None.
1032 """
1033 # Extract the object's docstring. If it doesn't have one,
1034 # then return None (no test for this object).
Guido van Rossum3172c5d2007-10-16 18:12:55 +00001035 if isinstance(obj, str):
Tim Peters8485b562004-08-04 18:46:34 +00001036 docstring = obj
1037 else:
1038 try:
1039 if obj.__doc__ is None:
Edward Loper32ddbf72004-09-13 05:47:24 +00001040 docstring = ''
1041 else:
Jim Fulton7d428782004-10-13 14:15:32 +00001042 docstring = obj.__doc__
Guido van Rossum3172c5d2007-10-16 18:12:55 +00001043 if not isinstance(docstring, str):
Jim Fulton7d428782004-10-13 14:15:32 +00001044 docstring = str(docstring)
Tim Peters8485b562004-08-04 18:46:34 +00001045 except (TypeError, AttributeError):
Edward Loper32ddbf72004-09-13 05:47:24 +00001046 docstring = ''
Tim Peters8485b562004-08-04 18:46:34 +00001047
1048 # Find the docstring's location in the file.
1049 lineno = self._find_lineno(obj, source_lines)
1050
Edward Loper32ddbf72004-09-13 05:47:24 +00001051 # Don't bother if the docstring is empty.
1052 if self._exclude_empty and not docstring:
1053 return None
1054
Tim Peters8485b562004-08-04 18:46:34 +00001055 # Return a DocTest for this object.
1056 if module is None:
1057 filename = None
1058 else:
1059 filename = getattr(module, '__file__', module.__name__)
Jim Fulton07a349c2004-08-22 14:10:00 +00001060 if filename[-4:] in (".pyc", ".pyo"):
1061 filename = filename[:-1]
Edward Lopera1ef6112004-08-09 16:14:41 +00001062 return self._parser.get_doctest(docstring, globs, name,
1063 filename, lineno)
Tim Peters8485b562004-08-04 18:46:34 +00001064
1065 def _find_lineno(self, obj, source_lines):
1066 """
1067 Return a line number of the given object's docstring. Note:
1068 this method assumes that the object has a docstring.
1069 """
1070 lineno = None
1071
1072 # Find the line number for modules.
1073 if inspect.ismodule(obj):
1074 lineno = 0
1075
1076 # Find the line number for classes.
1077 # Note: this could be fooled if a class is defined multiple
1078 # times in a single file.
1079 if inspect.isclass(obj):
1080 if source_lines is None:
1081 return None
1082 pat = re.compile(r'^\s*class\s*%s\b' %
1083 getattr(obj, '__name__', '-'))
1084 for i, line in enumerate(source_lines):
1085 if pat.match(line):
1086 lineno = i
1087 break
1088
1089 # Find the line number for functions & methods.
Christian Heimesff737952007-11-27 10:40:20 +00001090 if inspect.ismethod(obj): obj = obj.__func__
Neal Norwitz221085d2007-02-25 20:55:47 +00001091 if inspect.isfunction(obj): obj = obj.__code__
Tim Peters8485b562004-08-04 18:46:34 +00001092 if inspect.istraceback(obj): obj = obj.tb_frame
1093 if inspect.isframe(obj): obj = obj.f_code
1094 if inspect.iscode(obj):
1095 lineno = getattr(obj, 'co_firstlineno', None)-1
1096
1097 # Find the line number where the docstring starts. Assume
1098 # that it's the first line that begins with a quote mark.
1099 # Note: this could be fooled by a multiline function
1100 # signature, where a continuation line begins with a quote
1101 # mark.
1102 if lineno is not None:
1103 if source_lines is None:
1104 return lineno+1
1105 pat = re.compile('(^|.*:)\s*\w*("|\')')
1106 for lineno in range(lineno, len(source_lines)):
1107 if pat.match(source_lines[lineno]):
1108 return lineno
1109
1110 # We couldn't find the line number.
1111 return None
1112
1113######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00001114## 5. DocTest Runner
Tim Peters8485b562004-08-04 18:46:34 +00001115######################################################################
1116
Tim Peters8485b562004-08-04 18:46:34 +00001117class DocTestRunner:
1118 """
1119 A class used to run DocTest test cases, and accumulate statistics.
1120 The `run` method is used to process a single DocTest case. It
1121 returns a tuple `(f, t)`, where `t` is the number of test cases
1122 tried, and `f` is the number of test cases that failed.
1123
1124 >>> tests = DocTestFinder().find(_TestClass)
1125 >>> runner = DocTestRunner(verbose=False)
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00001126 >>> tests.sort(key = lambda test: test.name)
Tim Peters8485b562004-08-04 18:46:34 +00001127 >>> for test in tests:
Guido van Rossum7131f842007-02-09 20:13:25 +00001128 ... print(test.name, '->', runner.run(test))
Christian Heimes25bb7832008-01-11 16:17:00 +00001129 _TestClass -> TestResults(failed=0, attempted=2)
1130 _TestClass.__init__ -> TestResults(failed=0, attempted=2)
1131 _TestClass.get -> TestResults(failed=0, attempted=2)
1132 _TestClass.square -> TestResults(failed=0, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +00001133
1134 The `summarize` method prints a summary of all the test cases that
1135 have been run by the runner, and returns an aggregated `(f, t)`
1136 tuple:
1137
1138 >>> runner.summarize(verbose=1)
1139 4 items passed all tests:
1140 2 tests in _TestClass
1141 2 tests in _TestClass.__init__
1142 2 tests in _TestClass.get
1143 1 tests in _TestClass.square
1144 7 tests in 4 items.
1145 7 passed and 0 failed.
1146 Test passed.
Christian Heimes25bb7832008-01-11 16:17:00 +00001147 TestResults(failed=0, attempted=7)
Tim Peters8485b562004-08-04 18:46:34 +00001148
1149 The aggregated number of tried examples and failed examples is
1150 also available via the `tries` and `failures` attributes:
1151
1152 >>> runner.tries
1153 7
1154 >>> runner.failures
1155 0
1156
1157 The comparison between expected outputs and actual outputs is done
Edward Loper34fcb142004-08-09 02:45:41 +00001158 by an `OutputChecker`. This comparison may be customized with a
1159 number of option flags; see the documentation for `testmod` for
1160 more information. If the option flags are insufficient, then the
1161 comparison may also be customized by passing a subclass of
1162 `OutputChecker` to the constructor.
Tim Peters8485b562004-08-04 18:46:34 +00001163
1164 The test runner's display output can be controlled in two ways.
1165 First, an output function (`out) can be passed to
1166 `TestRunner.run`; this function will be called with strings that
1167 should be displayed. It defaults to `sys.stdout.write`. If
1168 capturing the output is not sufficient, then the display output
1169 can be also customized by subclassing DocTestRunner, and
1170 overriding the methods `report_start`, `report_success`,
1171 `report_unexpected_exception`, and `report_failure`.
1172 """
1173 # This divider string is used to separate failure messages, and to
1174 # separate sections of the summary.
1175 DIVIDER = "*" * 70
1176
Edward Loper34fcb142004-08-09 02:45:41 +00001177 def __init__(self, checker=None, verbose=None, optionflags=0):
Tim Peters8485b562004-08-04 18:46:34 +00001178 """
1179 Create a new test runner.
1180
Edward Loper34fcb142004-08-09 02:45:41 +00001181 Optional keyword arg `checker` is the `OutputChecker` that
1182 should be used to compare the expected outputs and actual
1183 outputs of doctest examples.
1184
Tim Peters8485b562004-08-04 18:46:34 +00001185 Optional keyword arg 'verbose' prints lots of stuff if true,
1186 only failures if false; by default, it's true iff '-v' is in
1187 sys.argv.
1188
1189 Optional argument `optionflags` can be used to control how the
1190 test runner compares expected output to actual output, and how
1191 it displays failures. See the documentation for `testmod` for
1192 more information.
1193 """
Edward Loper34fcb142004-08-09 02:45:41 +00001194 self._checker = checker or OutputChecker()
Tim Peters8a7d2d52001-01-16 07:10:57 +00001195 if verbose is None:
Tim Peters8485b562004-08-04 18:46:34 +00001196 verbose = '-v' in sys.argv
1197 self._verbose = verbose
Tim Peters6ebe61f2003-06-27 20:48:05 +00001198 self.optionflags = optionflags
Jim Fulton07a349c2004-08-22 14:10:00 +00001199 self.original_optionflags = optionflags
Tim Peters6ebe61f2003-06-27 20:48:05 +00001200
Tim Peters8485b562004-08-04 18:46:34 +00001201 # Keep track of the examples we've run.
1202 self.tries = 0
1203 self.failures = 0
1204 self._name2ft = {}
Tim Peters8a7d2d52001-01-16 07:10:57 +00001205
Tim Peters8485b562004-08-04 18:46:34 +00001206 # Create a fake output target for capturing doctest output.
1207 self._fakeout = _SpoofOut()
Tim Peters4fd9e2f2001-08-18 00:05:50 +00001208
Tim Peters8485b562004-08-04 18:46:34 +00001209 #/////////////////////////////////////////////////////////////////
Tim Peters8485b562004-08-04 18:46:34 +00001210 # Reporting methods
1211 #/////////////////////////////////////////////////////////////////
Tim Peters17111f32001-10-03 04:08:26 +00001212
Tim Peters8485b562004-08-04 18:46:34 +00001213 def report_start(self, out, test, example):
Tim Peters8a7d2d52001-01-16 07:10:57 +00001214 """
Tim Peters8485b562004-08-04 18:46:34 +00001215 Report that the test runner is about to process the given
1216 example. (Only displays a message if verbose=True)
1217 """
1218 if self._verbose:
Edward Loperaacf0832004-08-26 01:19:50 +00001219 if example.want:
1220 out('Trying:\n' + _indent(example.source) +
1221 'Expecting:\n' + _indent(example.want))
1222 else:
1223 out('Trying:\n' + _indent(example.source) +
1224 'Expecting nothing\n')
Tim Peters8a7d2d52001-01-16 07:10:57 +00001225
Tim Peters8485b562004-08-04 18:46:34 +00001226 def report_success(self, out, test, example, got):
1227 """
1228 Report that the given example ran successfully. (Only
1229 displays a message if verbose=True)
1230 """
1231 if self._verbose:
1232 out("ok\n")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001233
Tim Peters8485b562004-08-04 18:46:34 +00001234 def report_failure(self, out, test, example, got):
1235 """
1236 Report that the given example failed.
1237 """
Edward Loper8e4a34b2004-08-12 02:34:27 +00001238 out(self._failure_header(test, example) +
Edward Loperca9111e2004-08-26 03:00:24 +00001239 self._checker.output_difference(example, got, self.optionflags))
Tim Peters7402f792001-10-02 03:53:41 +00001240
Tim Peters8485b562004-08-04 18:46:34 +00001241 def report_unexpected_exception(self, out, test, example, exc_info):
1242 """
1243 Report that the given example raised an unexpected exception.
1244 """
Edward Loper8e4a34b2004-08-12 02:34:27 +00001245 out(self._failure_header(test, example) +
Edward Loperaacf0832004-08-26 01:19:50 +00001246 'Exception raised:\n' + _indent(_exception_traceback(exc_info)))
Tim Peters7402f792001-10-02 03:53:41 +00001247
Edward Loper8e4a34b2004-08-12 02:34:27 +00001248 def _failure_header(self, test, example):
Jim Fulton07a349c2004-08-22 14:10:00 +00001249 out = [self.DIVIDER]
1250 if test.filename:
1251 if test.lineno is not None and example.lineno is not None:
1252 lineno = test.lineno + example.lineno + 1
1253 else:
1254 lineno = '?'
1255 out.append('File "%s", line %s, in %s' %
1256 (test.filename, lineno, test.name))
Tim Peters8485b562004-08-04 18:46:34 +00001257 else:
Jim Fulton07a349c2004-08-22 14:10:00 +00001258 out.append('Line %s, in %s' % (example.lineno+1, test.name))
1259 out.append('Failed example:')
1260 source = example.source
Edward Loperaacf0832004-08-26 01:19:50 +00001261 out.append(_indent(source))
1262 return '\n'.join(out)
Tim Peters7402f792001-10-02 03:53:41 +00001263
Tim Peters8485b562004-08-04 18:46:34 +00001264 #/////////////////////////////////////////////////////////////////
1265 # DocTest Running
1266 #/////////////////////////////////////////////////////////////////
Tim Peters7402f792001-10-02 03:53:41 +00001267
Tim Peters8485b562004-08-04 18:46:34 +00001268 def __run(self, test, compileflags, out):
Tim Peters8a7d2d52001-01-16 07:10:57 +00001269 """
Tim Peters8485b562004-08-04 18:46:34 +00001270 Run the examples in `test`. Write the outcome of each example
1271 with one of the `DocTestRunner.report_*` methods, using the
1272 writer function `out`. `compileflags` is the set of compiler
1273 flags that should be used to execute examples. Return a tuple
1274 `(f, t)`, where `t` is the number of examples tried, and `f`
1275 is the number of examples that failed. The examples are run
1276 in the namespace `test.globs`.
1277 """
1278 # Keep track of the number of failures and tries.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001279 failures = tries = 0
Tim Peters8485b562004-08-04 18:46:34 +00001280
1281 # Save the option flags (since option directives can be used
1282 # to modify them).
1283 original_optionflags = self.optionflags
1284
Tim Peters1fbf9c52004-09-04 17:21:02 +00001285 SUCCESS, FAILURE, BOOM = range(3) # `outcome` state
1286
1287 check = self._checker.check_output
1288
Tim Peters8485b562004-08-04 18:46:34 +00001289 # Process each example.
Edward Loper2de91ba2004-08-27 02:07:46 +00001290 for examplenum, example in enumerate(test.examples):
1291
Ezio Melotti13925002011-03-16 11:05:33 +02001292 # If REPORT_ONLY_FIRST_FAILURE is set, then suppress
Edward Lopera89f88d2004-08-26 02:45:51 +00001293 # reporting after the first failure.
1294 quiet = (self.optionflags & REPORT_ONLY_FIRST_FAILURE and
1295 failures > 0)
1296
Edward Loper74bca7a2004-08-12 02:27:44 +00001297 # Merge in the example's options.
1298 self.optionflags = original_optionflags
1299 if example.options:
1300 for (optionflag, val) in example.options.items():
1301 if val:
1302 self.optionflags |= optionflag
1303 else:
1304 self.optionflags &= ~optionflag
Tim Peters8485b562004-08-04 18:46:34 +00001305
Thomas Wouters477c8d52006-05-27 19:21:47 +00001306 # If 'SKIP' is set, then skip this example.
1307 if self.optionflags & SKIP:
1308 continue
1309
Tim Peters8485b562004-08-04 18:46:34 +00001310 # Record that we started this example.
1311 tries += 1
Edward Lopera89f88d2004-08-26 02:45:51 +00001312 if not quiet:
1313 self.report_start(out, test, example)
Tim Peters8485b562004-08-04 18:46:34 +00001314
Edward Loper2de91ba2004-08-27 02:07:46 +00001315 # Use a special filename for compile(), so we can retrieve
1316 # the source code during interactive debugging (see
1317 # __patched_linecache_getlines).
1318 filename = '<doctest %s[%d]>' % (test.name, examplenum)
1319
Tim Peters8485b562004-08-04 18:46:34 +00001320 # Run the example in the given context (globs), and record
1321 # any exception that gets raised. (But don't intercept
1322 # keyboard interrupts.)
1323 try:
Tim Peters208ca702004-08-09 04:12:36 +00001324 # Don't blink! This is where the user's code gets run.
Georg Brandl7cae87c2006-09-06 06:51:57 +00001325 exec(compile(example.source, filename, "single",
1326 compileflags, 1), test.globs)
Edward Loper2de91ba2004-08-27 02:07:46 +00001327 self.debugger.set_continue() # ==== Example Finished ====
Tim Peters8485b562004-08-04 18:46:34 +00001328 exception = None
1329 except KeyboardInterrupt:
1330 raise
1331 except:
1332 exception = sys.exc_info()
Edward Loper2de91ba2004-08-27 02:07:46 +00001333 self.debugger.set_continue() # ==== Example Finished ====
Tim Peters8485b562004-08-04 18:46:34 +00001334
Tim Peters208ca702004-08-09 04:12:36 +00001335 got = self._fakeout.getvalue() # the actual output
Tim Peters8485b562004-08-04 18:46:34 +00001336 self._fakeout.truncate(0)
Tim Peters1fbf9c52004-09-04 17:21:02 +00001337 outcome = FAILURE # guilty until proved innocent or insane
Tim Peters8485b562004-08-04 18:46:34 +00001338
1339 # If the example executed without raising any exceptions,
Tim Peters1fbf9c52004-09-04 17:21:02 +00001340 # verify its output.
Tim Peters8485b562004-08-04 18:46:34 +00001341 if exception is None:
Tim Peters1fbf9c52004-09-04 17:21:02 +00001342 if check(example.want, got, self.optionflags):
1343 outcome = SUCCESS
Tim Peters8485b562004-08-04 18:46:34 +00001344
Tim Peters1fbf9c52004-09-04 17:21:02 +00001345 # The example raised an exception: check if it was expected.
Tim Peters8485b562004-08-04 18:46:34 +00001346 else:
Benjamin Petersoneec3d712008-06-11 15:59:43 +00001347 exc_msg = traceback.format_exception_only(*exception[:2])[-1]
Tim Peters1fbf9c52004-09-04 17:21:02 +00001348 if not quiet:
Benjamin Petersoneec3d712008-06-11 15:59:43 +00001349 got += _exception_traceback(exception)
Tim Peters8485b562004-08-04 18:46:34 +00001350
Tim Peters1fbf9c52004-09-04 17:21:02 +00001351 # If `example.exc_msg` is None, then we weren't expecting
1352 # an exception.
Edward Lopera6b68322004-08-26 00:05:43 +00001353 if example.exc_msg is None:
Tim Peters1fbf9c52004-09-04 17:21:02 +00001354 outcome = BOOM
1355
1356 # We expected an exception: see whether it matches.
1357 elif check(example.exc_msg, exc_msg, self.optionflags):
1358 outcome = SUCCESS
1359
1360 # Another chance if they didn't care about the detail.
1361 elif self.optionflags & IGNORE_EXCEPTION_DETAIL:
Tim Petersf9a07f22013-12-03 21:02:05 -06001362 if check(_strip_exception_details(example.exc_msg),
1363 _strip_exception_details(exc_msg),
1364 self.optionflags):
Tim Peters1fbf9c52004-09-04 17:21:02 +00001365 outcome = SUCCESS
1366
1367 # Report the outcome.
1368 if outcome is SUCCESS:
1369 if not quiet:
1370 self.report_success(out, test, example, got)
1371 elif outcome is FAILURE:
1372 if not quiet:
1373 self.report_failure(out, test, example, got)
1374 failures += 1
1375 elif outcome is BOOM:
1376 if not quiet:
1377 self.report_unexpected_exception(out, test, example,
Benjamin Petersoneec3d712008-06-11 15:59:43 +00001378 exception)
Tim Peters1fbf9c52004-09-04 17:21:02 +00001379 failures += 1
1380 else:
1381 assert False, ("unknown outcome", outcome)
Tim Peters8485b562004-08-04 18:46:34 +00001382
R David Murray5a9d7062012-11-21 15:09:21 -05001383 if failures and self.optionflags & FAIL_FAST:
1384 break
1385
Tim Peters8485b562004-08-04 18:46:34 +00001386 # Restore the option flags (in case they were modified)
1387 self.optionflags = original_optionflags
1388
1389 # Record and return the number of failures and tries.
1390 self.__record_outcome(test, failures, tries)
Christian Heimes25bb7832008-01-11 16:17:00 +00001391 return TestResults(failures, tries)
Tim Peters8a7d2d52001-01-16 07:10:57 +00001392
Tim Peters8485b562004-08-04 18:46:34 +00001393 def __record_outcome(self, test, f, t):
1394 """
1395 Record the fact that the given DocTest (`test`) generated `f`
1396 failures out of `t` tried examples.
1397 """
1398 f2, t2 = self._name2ft.get(test.name, (0,0))
1399 self._name2ft[test.name] = (f+f2, t+t2)
1400 self.failures += f
1401 self.tries += t
1402
Edward Loper2de91ba2004-08-27 02:07:46 +00001403 __LINECACHE_FILENAME_RE = re.compile(r'<doctest '
Florent Xiclunad9f57632010-10-14 20:56:20 +00001404 r'(?P<name>.+)'
Edward Loper2de91ba2004-08-27 02:07:46 +00001405 r'\[(?P<examplenum>\d+)\]>$')
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00001406 def __patched_linecache_getlines(self, filename, module_globals=None):
Edward Loper2de91ba2004-08-27 02:07:46 +00001407 m = self.__LINECACHE_FILENAME_RE.match(filename)
1408 if m and m.group('name') == self.test.name:
1409 example = self.test.examples[int(m.group('examplenum'))]
Ezio Melottid8b509b2011-09-28 17:37:55 +03001410 return example.source.splitlines(keepends=True)
Edward Loper2de91ba2004-08-27 02:07:46 +00001411 else:
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00001412 return self.save_linecache_getlines(filename, module_globals)
Edward Loper2de91ba2004-08-27 02:07:46 +00001413
Tim Peters8485b562004-08-04 18:46:34 +00001414 def run(self, test, compileflags=None, out=None, clear_globs=True):
1415 """
1416 Run the examples in `test`, and display the results using the
1417 writer function `out`.
1418
1419 The examples are run in the namespace `test.globs`. If
1420 `clear_globs` is true (the default), then this namespace will
1421 be cleared after the test runs, to help with garbage
1422 collection. If you would like to examine the namespace after
1423 the test completes, then use `clear_globs=False`.
1424
1425 `compileflags` gives the set of flags that should be used by
1426 the Python compiler when running the examples. If not
1427 specified, then it will default to the set of future-import
1428 flags that apply to `globs`.
1429
1430 The output of each example is checked using
1431 `DocTestRunner.check_output`, and the results are formatted by
1432 the `DocTestRunner.report_*` methods.
1433 """
Edward Loper2de91ba2004-08-27 02:07:46 +00001434 self.test = test
1435
Tim Peters8485b562004-08-04 18:46:34 +00001436 if compileflags is None:
1437 compileflags = _extract_future_flags(test.globs)
Jim Fulton356fd192004-08-09 11:34:47 +00001438
Tim Peters6c542b72004-08-09 16:43:36 +00001439 save_stdout = sys.stdout
Tim Peters8485b562004-08-04 18:46:34 +00001440 if out is None:
Florent Xicluna59250852010-02-27 14:21:57 +00001441 encoding = save_stdout.encoding
1442 if encoding is None or encoding.lower() == 'utf-8':
1443 out = save_stdout.write
1444 else:
1445 # Use backslashreplace error handling on write
1446 def out(s):
1447 s = str(s.encode(encoding, 'backslashreplace'), encoding)
1448 save_stdout.write(s)
Tim Peters6c542b72004-08-09 16:43:36 +00001449 sys.stdout = self._fakeout
Tim Peters8485b562004-08-04 18:46:34 +00001450
Edward Loper2de91ba2004-08-27 02:07:46 +00001451 # Patch pdb.set_trace to restore sys.stdout during interactive
1452 # debugging (so it's not still redirected to self._fakeout).
1453 # Note that the interactive output will go to *our*
1454 # save_stdout, even if that's not the real sys.stdout; this
1455 # allows us to write test cases for the set_trace behavior.
Brett Cannon31f59292011-02-21 19:29:56 +00001456 save_trace = sys.gettrace()
Tim Peters6c542b72004-08-09 16:43:36 +00001457 save_set_trace = pdb.set_trace
Edward Loper2de91ba2004-08-27 02:07:46 +00001458 self.debugger = _OutputRedirectingPdb(save_stdout)
1459 self.debugger.reset()
1460 pdb.set_trace = self.debugger.set_trace
1461
1462 # Patch linecache.getlines, so we can see the example's source
1463 # when we're inside the debugger.
1464 self.save_linecache_getlines = linecache.getlines
1465 linecache.getlines = self.__patched_linecache_getlines
1466
Georg Brandl25fbb892010-07-30 09:23:23 +00001467 # Make sure sys.displayhook just prints the value to stdout
1468 save_displayhook = sys.displayhook
1469 sys.displayhook = sys.__displayhook__
1470
Tim Peters8485b562004-08-04 18:46:34 +00001471 try:
Tim Peters8485b562004-08-04 18:46:34 +00001472 return self.__run(test, compileflags, out)
1473 finally:
Tim Peters6c542b72004-08-09 16:43:36 +00001474 sys.stdout = save_stdout
1475 pdb.set_trace = save_set_trace
Brett Cannon31f59292011-02-21 19:29:56 +00001476 sys.settrace(save_trace)
Edward Loper2de91ba2004-08-27 02:07:46 +00001477 linecache.getlines = self.save_linecache_getlines
Georg Brandl25fbb892010-07-30 09:23:23 +00001478 sys.displayhook = save_displayhook
Tim Peters8485b562004-08-04 18:46:34 +00001479 if clear_globs:
1480 test.globs.clear()
Benjamin Petersonfbf66bd2008-07-29 15:55:50 +00001481 import builtins
1482 builtins._ = None
Tim Peters8485b562004-08-04 18:46:34 +00001483
1484 #/////////////////////////////////////////////////////////////////
1485 # Summarization
1486 #/////////////////////////////////////////////////////////////////
Tim Peters8a7d2d52001-01-16 07:10:57 +00001487 def summarize(self, verbose=None):
1488 """
Tim Peters8485b562004-08-04 18:46:34 +00001489 Print a summary of all the test cases that have been run by
1490 this DocTestRunner, and return a tuple `(f, t)`, where `f` is
1491 the total number of failed examples, and `t` is the total
1492 number of tried examples.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001493
Tim Peters8485b562004-08-04 18:46:34 +00001494 The optional `verbose` argument controls how detailed the
1495 summary is. If the verbosity is not specified, then the
1496 DocTestRunner's verbosity is used.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001497 """
Tim Peters8a7d2d52001-01-16 07:10:57 +00001498 if verbose is None:
Tim Peters8485b562004-08-04 18:46:34 +00001499 verbose = self._verbose
Tim Peters8a7d2d52001-01-16 07:10:57 +00001500 notests = []
1501 passed = []
1502 failed = []
1503 totalt = totalf = 0
Tim Peters8485b562004-08-04 18:46:34 +00001504 for x in self._name2ft.items():
Tim Peters8a7d2d52001-01-16 07:10:57 +00001505 name, (f, t) = x
1506 assert f <= t
Tim Peters8485b562004-08-04 18:46:34 +00001507 totalt += t
1508 totalf += f
Tim Peters8a7d2d52001-01-16 07:10:57 +00001509 if t == 0:
1510 notests.append(name)
1511 elif f == 0:
1512 passed.append( (name, t) )
1513 else:
1514 failed.append(x)
1515 if verbose:
1516 if notests:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001517 print(len(notests), "items had no tests:")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001518 notests.sort()
1519 for thing in notests:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001520 print(" ", thing)
Tim Peters8a7d2d52001-01-16 07:10:57 +00001521 if passed:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001522 print(len(passed), "items passed all tests:")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001523 passed.sort()
1524 for thing, count in passed:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001525 print(" %3d tests in %s" % (count, thing))
Tim Peters8a7d2d52001-01-16 07:10:57 +00001526 if failed:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001527 print(self.DIVIDER)
1528 print(len(failed), "items had failures:")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001529 failed.sort()
1530 for thing, (f, t) in failed:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001531 print(" %3d of %3d in %s" % (f, t, thing))
Tim Peters8a7d2d52001-01-16 07:10:57 +00001532 if verbose:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001533 print(totalt, "tests in", len(self._name2ft), "items.")
1534 print(totalt - totalf, "passed and", totalf, "failed.")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001535 if totalf:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001536 print("***Test Failed***", totalf, "failures.")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001537 elif verbose:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001538 print("Test passed.")
Christian Heimes25bb7832008-01-11 16:17:00 +00001539 return TestResults(totalf, totalt)
Tim Peters8a7d2d52001-01-16 07:10:57 +00001540
Tim Peters82076ef2004-09-13 00:52:51 +00001541 #/////////////////////////////////////////////////////////////////
1542 # Backward compatibility cruft to maintain doctest.master.
1543 #/////////////////////////////////////////////////////////////////
1544 def merge(self, other):
1545 d = self._name2ft
1546 for name, (f, t) in other._name2ft.items():
1547 if name in d:
Nick Coghlan38622002008-12-15 12:01:34 +00001548 # Don't print here by default, since doing
1549 # so breaks some of the buildbots
1550 #print("*** DocTestRunner.merge: '" + name + "' in both" \
1551 # " testers; summing outcomes.")
Tim Peters82076ef2004-09-13 00:52:51 +00001552 f2, t2 = d[name]
1553 f = f + f2
1554 t = t + t2
1555 d[name] = f, t
1556
Edward Loper34fcb142004-08-09 02:45:41 +00001557class OutputChecker:
1558 """
1559 A class used to check the whether the actual output from a doctest
1560 example matches the expected output. `OutputChecker` defines two
1561 methods: `check_output`, which compares a given pair of outputs,
1562 and returns true if they match; and `output_difference`, which
1563 returns a string describing the differences between two outputs.
1564 """
Georg Brandl559e5d72008-06-11 18:37:52 +00001565 def _toAscii(self, s):
1566 """
1567 Convert string to hex-escaped ASCII string.
1568 """
1569 return str(s.encode('ASCII', 'backslashreplace'), "ASCII")
1570
Edward Loper34fcb142004-08-09 02:45:41 +00001571 def check_output(self, want, got, optionflags):
1572 """
Edward Loper74bca7a2004-08-12 02:27:44 +00001573 Return True iff the actual output from an example (`got`)
1574 matches the expected output (`want`). These strings are
1575 always considered to match if they are identical; but
1576 depending on what option flags the test runner is using,
1577 several non-exact match types are also possible. See the
1578 documentation for `TestRunner` for more information about
1579 option flags.
Edward Loper34fcb142004-08-09 02:45:41 +00001580 """
Georg Brandl559e5d72008-06-11 18:37:52 +00001581
1582 # If `want` contains hex-escaped character such as "\u1234",
1583 # then `want` is a string of six characters(e.g. [\,u,1,2,3,4]).
1584 # On the other hand, `got` could be an another sequence of
1585 # characters such as [\u1234], so `want` and `got` should
1586 # be folded to hex-escaped ASCII string to compare.
1587 got = self._toAscii(got)
1588 want = self._toAscii(want)
1589
Edward Loper34fcb142004-08-09 02:45:41 +00001590 # Handle the common case first, for efficiency:
1591 # if they're string-identical, always return true.
1592 if got == want:
1593 return True
1594
1595 # The values True and False replaced 1 and 0 as the return
1596 # value for boolean comparisons in Python 2.3.
1597 if not (optionflags & DONT_ACCEPT_TRUE_FOR_1):
1598 if (got,want) == ("True\n", "1\n"):
1599 return True
1600 if (got,want) == ("False\n", "0\n"):
1601 return True
1602
1603 # <BLANKLINE> can be used as a special sequence to signify a
1604 # blank line, unless the DONT_ACCEPT_BLANKLINE flag is used.
1605 if not (optionflags & DONT_ACCEPT_BLANKLINE):
1606 # Replace <BLANKLINE> in want with a blank line.
1607 want = re.sub('(?m)^%s\s*?$' % re.escape(BLANKLINE_MARKER),
1608 '', want)
1609 # If a line in got contains only spaces, then remove the
1610 # spaces.
1611 got = re.sub('(?m)^\s*?$', '', got)
1612 if got == want:
1613 return True
1614
1615 # This flag causes doctest to ignore any differences in the
1616 # contents of whitespace strings. Note that this can be used
Tim Peters3fa8c202004-08-23 21:43:39 +00001617 # in conjunction with the ELLIPSIS flag.
Tim Peters1cf3aa62004-08-19 06:49:33 +00001618 if optionflags & NORMALIZE_WHITESPACE:
Edward Loper34fcb142004-08-09 02:45:41 +00001619 got = ' '.join(got.split())
1620 want = ' '.join(want.split())
1621 if got == want:
1622 return True
1623
1624 # The ELLIPSIS flag says to let the sequence "..." in `want`
Tim Peters26b3ebb2004-08-19 08:10:08 +00001625 # match any substring in `got`.
Tim Peters1cf3aa62004-08-19 06:49:33 +00001626 if optionflags & ELLIPSIS:
Tim Petersb0a04e12004-08-20 02:08:04 +00001627 if _ellipsis_match(want, got):
Edward Loper34fcb142004-08-09 02:45:41 +00001628 return True
1629
1630 # We didn't find any match; return false.
1631 return False
1632
Tim Petersc6cbab02004-08-22 19:43:28 +00001633 # Should we do a fancy diff?
1634 def _do_a_fancy_diff(self, want, got, optionflags):
1635 # Not unless they asked for a fancy diff.
Edward Loper71f55af2004-08-26 01:41:51 +00001636 if not optionflags & (REPORT_UDIFF |
1637 REPORT_CDIFF |
1638 REPORT_NDIFF):
Tim Petersc6cbab02004-08-22 19:43:28 +00001639 return False
Tim Peters5b799c12004-08-26 05:21:59 +00001640
Tim Petersc6cbab02004-08-22 19:43:28 +00001641 # If expected output uses ellipsis, a meaningful fancy diff is
Tim Peters5b799c12004-08-26 05:21:59 +00001642 # too hard ... or maybe not. In two real-life failures Tim saw,
1643 # a diff was a major help anyway, so this is commented out.
1644 # [todo] _ellipsis_match() knows which pieces do and don't match,
1645 # and could be the basis for a kick-ass diff in this case.
1646 ##if optionflags & ELLIPSIS and ELLIPSIS_MARKER in want:
1647 ## return False
1648
Tim Petersc6cbab02004-08-22 19:43:28 +00001649 # ndiff does intraline difference marking, so can be useful even
Tim Peters5b799c12004-08-26 05:21:59 +00001650 # for 1-line differences.
Edward Loper71f55af2004-08-26 01:41:51 +00001651 if optionflags & REPORT_NDIFF:
Tim Petersc6cbab02004-08-22 19:43:28 +00001652 return True
Tim Peters5b799c12004-08-26 05:21:59 +00001653
Tim Petersc6cbab02004-08-22 19:43:28 +00001654 # The other diff types need at least a few lines to be helpful.
1655 return want.count('\n') > 2 and got.count('\n') > 2
1656
Edward Loperca9111e2004-08-26 03:00:24 +00001657 def output_difference(self, example, got, optionflags):
Edward Loper34fcb142004-08-09 02:45:41 +00001658 """
1659 Return a string describing the differences between the
Edward Loperca9111e2004-08-26 03:00:24 +00001660 expected output for a given example (`example`) and the actual
1661 output (`got`). `optionflags` is the set of option flags used
1662 to compare `want` and `got`.
Edward Loper34fcb142004-08-09 02:45:41 +00001663 """
Edward Loperca9111e2004-08-26 03:00:24 +00001664 want = example.want
Edward Loper68ba9a62004-08-12 02:43:49 +00001665 # If <BLANKLINE>s are being used, then replace blank lines
1666 # with <BLANKLINE> in the actual output string.
Edward Loper34fcb142004-08-09 02:45:41 +00001667 if not (optionflags & DONT_ACCEPT_BLANKLINE):
Edward Loper68ba9a62004-08-12 02:43:49 +00001668 got = re.sub('(?m)^[ ]*(?=\n)', BLANKLINE_MARKER, got)
Edward Loper34fcb142004-08-09 02:45:41 +00001669
Tim Peters5b799c12004-08-26 05:21:59 +00001670 # Check if we should use diff.
Tim Petersc6cbab02004-08-22 19:43:28 +00001671 if self._do_a_fancy_diff(want, got, optionflags):
Edward Loper34fcb142004-08-09 02:45:41 +00001672 # Split want & got into lines.
Ezio Melottid8b509b2011-09-28 17:37:55 +03001673 want_lines = want.splitlines(keepends=True)
1674 got_lines = got.splitlines(keepends=True)
Edward Loper34fcb142004-08-09 02:45:41 +00001675 # Use difflib to find their differences.
Edward Loper71f55af2004-08-26 01:41:51 +00001676 if optionflags & REPORT_UDIFF:
Edward Loper56629292004-08-26 01:31:56 +00001677 diff = difflib.unified_diff(want_lines, got_lines, n=2)
1678 diff = list(diff)[2:] # strip the diff header
1679 kind = 'unified diff with -expected +actual'
Edward Loper71f55af2004-08-26 01:41:51 +00001680 elif optionflags & REPORT_CDIFF:
Edward Loper56629292004-08-26 01:31:56 +00001681 diff = difflib.context_diff(want_lines, got_lines, n=2)
1682 diff = list(diff)[2:] # strip the diff header
1683 kind = 'context diff with expected followed by actual'
Edward Loper71f55af2004-08-26 01:41:51 +00001684 elif optionflags & REPORT_NDIFF:
Tim Petersc6cbab02004-08-22 19:43:28 +00001685 engine = difflib.Differ(charjunk=difflib.IS_CHARACTER_JUNK)
1686 diff = list(engine.compare(want_lines, got_lines))
1687 kind = 'ndiff with -expected +actual'
Edward Loper34fcb142004-08-09 02:45:41 +00001688 else:
1689 assert 0, 'Bad diff option'
1690 # Remove trailing whitespace on diff output.
1691 diff = [line.rstrip() + '\n' for line in diff]
Edward Loperaacf0832004-08-26 01:19:50 +00001692 return 'Differences (%s):\n' % kind + _indent(''.join(diff))
Edward Loper34fcb142004-08-09 02:45:41 +00001693
1694 # If we're not using diff, then simply list the expected
1695 # output followed by the actual output.
Edward Loperaacf0832004-08-26 01:19:50 +00001696 if want and got:
1697 return 'Expected:\n%sGot:\n%s' % (_indent(want), _indent(got))
1698 elif want:
1699 return 'Expected:\n%sGot nothing\n' % _indent(want)
1700 elif got:
1701 return 'Expected nothing\nGot:\n%s' % _indent(got)
1702 else:
1703 return 'Expected nothing\nGot nothing\n'
Edward Loper34fcb142004-08-09 02:45:41 +00001704
Tim Peters19397e52004-08-06 22:02:59 +00001705class DocTestFailure(Exception):
1706 """A DocTest example has failed in debugging mode.
1707
1708 The exception instance has variables:
1709
1710 - test: the DocTest object being run
1711
Neal Norwitzc082cb72006-08-29 05:40:08 +00001712 - example: the Example object that failed
Tim Peters19397e52004-08-06 22:02:59 +00001713
1714 - got: the actual output
1715 """
1716 def __init__(self, test, example, got):
1717 self.test = test
1718 self.example = example
1719 self.got = got
1720
1721 def __str__(self):
1722 return str(self.test)
1723
1724class UnexpectedException(Exception):
1725 """A DocTest example has encountered an unexpected exception
1726
1727 The exception instance has variables:
1728
1729 - test: the DocTest object being run
1730
Guido van Rossum6a2a2a02006-08-26 20:37:44 +00001731 - example: the Example object that failed
Tim Peters19397e52004-08-06 22:02:59 +00001732
1733 - exc_info: the exception info
1734 """
1735 def __init__(self, test, example, exc_info):
1736 self.test = test
1737 self.example = example
1738 self.exc_info = exc_info
1739
1740 def __str__(self):
1741 return str(self.test)
Tim Petersd1b78272004-08-07 06:03:09 +00001742
Tim Peters19397e52004-08-06 22:02:59 +00001743class DebugRunner(DocTestRunner):
1744 r"""Run doc tests but raise an exception as soon as there is a failure.
1745
1746 If an unexpected exception occurs, an UnexpectedException is raised.
1747 It contains the test, the example, and the original exception:
1748
1749 >>> runner = DebugRunner(verbose=False)
Edward Lopera1ef6112004-08-09 16:14:41 +00001750 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
1751 ... {}, 'foo', 'foo.py', 0)
Tim Peters19397e52004-08-06 22:02:59 +00001752 >>> try:
1753 ... runner.run(test)
Guido van Rossumb940e112007-01-10 16:19:56 +00001754 ... except UnexpectedException as f:
1755 ... failure = f
Tim Peters19397e52004-08-06 22:02:59 +00001756
1757 >>> failure.test is test
1758 True
1759
1760 >>> failure.example.want
1761 '42\n'
1762
1763 >>> exc_info = failure.exc_info
Collin Winter828f04a2007-08-31 00:04:24 +00001764 >>> raise exc_info[1] # Already has the traceback
Tim Peters19397e52004-08-06 22:02:59 +00001765 Traceback (most recent call last):
1766 ...
1767 KeyError
1768
1769 We wrap the original exception to give the calling application
1770 access to the test and example information.
1771
1772 If the output doesn't match, then a DocTestFailure is raised:
1773
Edward Lopera1ef6112004-08-09 16:14:41 +00001774 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00001775 ... >>> x = 1
1776 ... >>> x
1777 ... 2
1778 ... ''', {}, 'foo', 'foo.py', 0)
1779
1780 >>> try:
1781 ... runner.run(test)
Guido van Rossumb940e112007-01-10 16:19:56 +00001782 ... except DocTestFailure as f:
1783 ... failure = f
Tim Peters19397e52004-08-06 22:02:59 +00001784
1785 DocTestFailure objects provide access to the test:
1786
1787 >>> failure.test is test
1788 True
1789
1790 As well as to the example:
1791
1792 >>> failure.example.want
1793 '2\n'
1794
1795 and the actual output:
1796
1797 >>> failure.got
1798 '1\n'
1799
1800 If a failure or error occurs, the globals are left intact:
1801
1802 >>> del test.globs['__builtins__']
1803 >>> test.globs
1804 {'x': 1}
1805
Edward Lopera1ef6112004-08-09 16:14:41 +00001806 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00001807 ... >>> x = 2
1808 ... >>> raise KeyError
1809 ... ''', {}, 'foo', 'foo.py', 0)
1810
1811 >>> runner.run(test)
1812 Traceback (most recent call last):
1813 ...
Guido van Rossum6a2a2a02006-08-26 20:37:44 +00001814 doctest.UnexpectedException: <DocTest foo from foo.py:0 (2 examples)>
Tim Petersd1b78272004-08-07 06:03:09 +00001815
Tim Peters19397e52004-08-06 22:02:59 +00001816 >>> del test.globs['__builtins__']
1817 >>> test.globs
1818 {'x': 2}
1819
1820 But the globals are cleared if there is no error:
1821
Edward Lopera1ef6112004-08-09 16:14:41 +00001822 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00001823 ... >>> x = 2
1824 ... ''', {}, 'foo', 'foo.py', 0)
1825
1826 >>> runner.run(test)
Christian Heimes25bb7832008-01-11 16:17:00 +00001827 TestResults(failed=0, attempted=1)
Tim Peters19397e52004-08-06 22:02:59 +00001828
1829 >>> test.globs
1830 {}
1831
1832 """
1833
1834 def run(self, test, compileflags=None, out=None, clear_globs=True):
1835 r = DocTestRunner.run(self, test, compileflags, out, False)
1836 if clear_globs:
1837 test.globs.clear()
1838 return r
1839
1840 def report_unexpected_exception(self, out, test, example, exc_info):
1841 raise UnexpectedException(test, example, exc_info)
1842
1843 def report_failure(self, out, test, example, got):
1844 raise DocTestFailure(test, example, got)
1845
Tim Peters8485b562004-08-04 18:46:34 +00001846######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00001847## 6. Test Functions
Tim Peters8485b562004-08-04 18:46:34 +00001848######################################################################
1849# These should be backwards compatible.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001850
Tim Peters82076ef2004-09-13 00:52:51 +00001851# For backward compatibility, a global instance of a DocTestRunner
1852# class, updated by testmod.
1853master = None
1854
Thomas Wouters73e5a5b2006-06-08 15:35:45 +00001855def testmod(m=None, name=None, globs=None, verbose=None,
Tim Peters19397e52004-08-06 22:02:59 +00001856 report=True, optionflags=0, extraglobs=None,
Tim Peters958cc892004-09-13 14:53:28 +00001857 raise_on_error=False, exclude_empty=False):
Thomas Wouters73e5a5b2006-06-08 15:35:45 +00001858 """m=None, name=None, globs=None, verbose=None, report=True,
1859 optionflags=0, extraglobs=None, raise_on_error=False,
Tim Peters958cc892004-09-13 14:53:28 +00001860 exclude_empty=False
Tim Peters8a7d2d52001-01-16 07:10:57 +00001861
Martin v. Löwis4581cfa2002-11-22 08:23:09 +00001862 Test examples in docstrings in functions and classes reachable
1863 from module m (or the current module if m is not supplied), starting
Thomas Wouters73e5a5b2006-06-08 15:35:45 +00001864 with m.__doc__.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001865
1866 Also test examples reachable from dict m.__test__ if it exists and is
Tim Petersc2388a22004-08-10 01:41:28 +00001867 not None. m.__test__ maps names to functions, classes and strings;
Tim Peters8a7d2d52001-01-16 07:10:57 +00001868 function and class docstrings are tested even if the name is private;
1869 strings are tested directly, as if they were docstrings.
1870
1871 Return (#failures, #tests).
1872
Alexander Belopolsky977a6842010-08-16 20:17:07 +00001873 See help(doctest) for an overview.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001874
1875 Optional keyword arg "name" gives the name of the module; by default
1876 use m.__name__.
1877
1878 Optional keyword arg "globs" gives a dict to be used as the globals
1879 when executing examples; by default, use m.__dict__. A copy of this
1880 dict is actually used for each docstring, so that each docstring's
1881 examples start with a clean slate.
1882
Tim Peters8485b562004-08-04 18:46:34 +00001883 Optional keyword arg "extraglobs" gives a dictionary that should be
1884 merged into the globals that are used to execute examples. By
1885 default, no extra globals are used. This is new in 2.4.
1886
Tim Peters8a7d2d52001-01-16 07:10:57 +00001887 Optional keyword arg "verbose" prints lots of stuff if true, prints
1888 only failures if false; by default, it's true iff "-v" is in sys.argv.
1889
Tim Peters8a7d2d52001-01-16 07:10:57 +00001890 Optional keyword arg "report" prints a summary at the end when true,
1891 else prints nothing at the end. In verbose mode, the summary is
1892 detailed, else very brief (in fact, empty if all tests passed).
1893
Tim Peters6ebe61f2003-06-27 20:48:05 +00001894 Optional keyword arg "optionflags" or's together module constants,
Tim Petersf82a9de2004-08-22 20:51:53 +00001895 and defaults to 0. This is new in 2.3. Possible values (see the
1896 docs for details):
Tim Peters6ebe61f2003-06-27 20:48:05 +00001897
1898 DONT_ACCEPT_TRUE_FOR_1
Tim Peters8485b562004-08-04 18:46:34 +00001899 DONT_ACCEPT_BLANKLINE
Tim Peters8485b562004-08-04 18:46:34 +00001900 NORMALIZE_WHITESPACE
Tim Peters8485b562004-08-04 18:46:34 +00001901 ELLIPSIS
Thomas Wouters477c8d52006-05-27 19:21:47 +00001902 SKIP
Edward Loper052d0cd2004-09-19 17:19:33 +00001903 IGNORE_EXCEPTION_DETAIL
Edward Loper71f55af2004-08-26 01:41:51 +00001904 REPORT_UDIFF
1905 REPORT_CDIFF
1906 REPORT_NDIFF
Edward Lopera89f88d2004-08-26 02:45:51 +00001907 REPORT_ONLY_FIRST_FAILURE
Tim Peters19397e52004-08-06 22:02:59 +00001908
1909 Optional keyword arg "raise_on_error" raises an exception on the
1910 first unexpected exception or failure. This allows failures to be
1911 post-mortem debugged.
1912
Tim Peters8a7d2d52001-01-16 07:10:57 +00001913 Advanced tomfoolery: testmod runs methods of a local instance of
1914 class doctest.Tester, then merges the results into (or creates)
1915 global Tester instance doctest.master. Methods of doctest.master
1916 can be called directly too, if you want to do something unusual.
1917 Passing report=0 to testmod is especially useful then, to delay
1918 displaying a summary. Invoke doctest.master.summarize(verbose)
1919 when you're done fiddling.
1920 """
Tim Peters82076ef2004-09-13 00:52:51 +00001921 global master
1922
Tim Peters8485b562004-08-04 18:46:34 +00001923 # If no module was given, then use __main__.
Martin v. Löwis4581cfa2002-11-22 08:23:09 +00001924 if m is None:
Martin v. Löwis4581cfa2002-11-22 08:23:09 +00001925 # DWA - m will still be None if this wasn't invoked from the command
1926 # line, in which case the following TypeError is about as good an error
1927 # as we should expect
1928 m = sys.modules.get('__main__')
1929
Tim Peters8485b562004-08-04 18:46:34 +00001930 # Check that we were actually given a module.
1931 if not inspect.ismodule(m):
Walter Dörwald70a6b492004-02-12 17:35:32 +00001932 raise TypeError("testmod: module required; %r" % (m,))
Tim Peters8485b562004-08-04 18:46:34 +00001933
1934 # If no name was given, then use the module's name.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001935 if name is None:
1936 name = m.__name__
Tim Peters8485b562004-08-04 18:46:34 +00001937
1938 # Find, parse, and run all tests in the given module.
Thomas Wouters73e5a5b2006-06-08 15:35:45 +00001939 finder = DocTestFinder(exclude_empty=exclude_empty)
Tim Peters19397e52004-08-06 22:02:59 +00001940
1941 if raise_on_error:
1942 runner = DebugRunner(verbose=verbose, optionflags=optionflags)
1943 else:
1944 runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1945
Tim Peters8485b562004-08-04 18:46:34 +00001946 for test in finder.find(m, name, globs=globs, extraglobs=extraglobs):
1947 runner.run(test)
1948
Tim Peters8a7d2d52001-01-16 07:10:57 +00001949 if report:
Tim Peters8485b562004-08-04 18:46:34 +00001950 runner.summarize()
Tim Peters8a7d2d52001-01-16 07:10:57 +00001951
Tim Peters82076ef2004-09-13 00:52:51 +00001952 if master is None:
1953 master = runner
1954 else:
1955 master.merge(runner)
1956
Christian Heimes25bb7832008-01-11 16:17:00 +00001957 return TestResults(runner.failures, runner.tries)
Tim Petersdb3756d2003-06-29 05:30:48 +00001958
Edward Loper052d0cd2004-09-19 17:19:33 +00001959def testfile(filename, module_relative=True, name=None, package=None,
1960 globs=None, verbose=None, report=True, optionflags=0,
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00001961 extraglobs=None, raise_on_error=False, parser=DocTestParser(),
1962 encoding=None):
Edward Loper052d0cd2004-09-19 17:19:33 +00001963 """
1964 Test examples in the given file. Return (#failures, #tests).
1965
1966 Optional keyword arg "module_relative" specifies how filenames
1967 should be interpreted:
1968
1969 - If "module_relative" is True (the default), then "filename"
1970 specifies a module-relative path. By default, this path is
1971 relative to the calling module's directory; but if the
1972 "package" argument is specified, then it is relative to that
1973 package. To ensure os-independence, "filename" should use
1974 "/" characters to separate path segments, and should not
1975 be an absolute path (i.e., it may not begin with "/").
1976
1977 - If "module_relative" is False, then "filename" specifies an
1978 os-specific path. The path may be absolute or relative (to
1979 the current working directory).
1980
Edward Lopera2fc7ec2004-09-21 03:24:24 +00001981 Optional keyword arg "name" gives the name of the test; by default
1982 use the file's basename.
Edward Loper052d0cd2004-09-19 17:19:33 +00001983
1984 Optional keyword argument "package" is a Python package or the
1985 name of a Python package whose directory should be used as the
1986 base directory for a module relative filename. If no package is
1987 specified, then the calling module's directory is used as the base
1988 directory for module relative filenames. It is an error to
1989 specify "package" if "module_relative" is False.
1990
1991 Optional keyword arg "globs" gives a dict to be used as the globals
1992 when executing examples; by default, use {}. A copy of this dict
1993 is actually used for each docstring, so that each docstring's
1994 examples start with a clean slate.
1995
1996 Optional keyword arg "extraglobs" gives a dictionary that should be
1997 merged into the globals that are used to execute examples. By
1998 default, no extra globals are used.
1999
2000 Optional keyword arg "verbose" prints lots of stuff if true, prints
2001 only failures if false; by default, it's true iff "-v" is in sys.argv.
2002
2003 Optional keyword arg "report" prints a summary at the end when true,
2004 else prints nothing at the end. In verbose mode, the summary is
2005 detailed, else very brief (in fact, empty if all tests passed).
2006
2007 Optional keyword arg "optionflags" or's together module constants,
2008 and defaults to 0. Possible values (see the docs for details):
2009
2010 DONT_ACCEPT_TRUE_FOR_1
2011 DONT_ACCEPT_BLANKLINE
2012 NORMALIZE_WHITESPACE
2013 ELLIPSIS
Thomas Wouters477c8d52006-05-27 19:21:47 +00002014 SKIP
Edward Loper052d0cd2004-09-19 17:19:33 +00002015 IGNORE_EXCEPTION_DETAIL
2016 REPORT_UDIFF
2017 REPORT_CDIFF
2018 REPORT_NDIFF
2019 REPORT_ONLY_FIRST_FAILURE
2020
2021 Optional keyword arg "raise_on_error" raises an exception on the
2022 first unexpected exception or failure. This allows failures to be
2023 post-mortem debugged.
2024
Edward Loper498a1862004-09-27 03:42:58 +00002025 Optional keyword arg "parser" specifies a DocTestParser (or
2026 subclass) that should be used to extract tests from the files.
2027
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00002028 Optional keyword arg "encoding" specifies an encoding that should
2029 be used to convert the file to unicode.
2030
Edward Loper052d0cd2004-09-19 17:19:33 +00002031 Advanced tomfoolery: testmod runs methods of a local instance of
2032 class doctest.Tester, then merges the results into (or creates)
2033 global Tester instance doctest.master. Methods of doctest.master
2034 can be called directly too, if you want to do something unusual.
2035 Passing report=0 to testmod is especially useful then, to delay
2036 displaying a summary. Invoke doctest.master.summarize(verbose)
2037 when you're done fiddling.
2038 """
2039 global master
2040
2041 if package and not module_relative:
2042 raise ValueError("Package may only be specified for module-"
2043 "relative paths.")
Tim Petersbab3e992004-09-20 19:52:34 +00002044
Edward Loper052d0cd2004-09-19 17:19:33 +00002045 # Relativize the path
Guido van Rossum1b81e7b2007-08-29 03:53:53 +00002046 text, filename = _load_testfile(filename, package, module_relative,
2047 encoding or "utf-8")
Edward Loper052d0cd2004-09-19 17:19:33 +00002048
2049 # If no name was given, then use the file's name.
2050 if name is None:
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002051 name = os.path.basename(filename)
Edward Loper052d0cd2004-09-19 17:19:33 +00002052
2053 # Assemble the globals.
2054 if globs is None:
2055 globs = {}
2056 else:
2057 globs = globs.copy()
2058 if extraglobs is not None:
2059 globs.update(extraglobs)
Raymond Hettinger0f055172009-01-27 10:06:09 +00002060 if '__name__' not in globs:
2061 globs['__name__'] = '__main__'
Edward Loper052d0cd2004-09-19 17:19:33 +00002062
2063 if raise_on_error:
2064 runner = DebugRunner(verbose=verbose, optionflags=optionflags)
2065 else:
2066 runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
2067
2068 # Read the file, convert it to a test, and run it.
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00002069 test = parser.get_doctest(text, globs, name, filename, 0)
Edward Loper052d0cd2004-09-19 17:19:33 +00002070 runner.run(test)
2071
2072 if report:
2073 runner.summarize()
2074
2075 if master is None:
2076 master = runner
2077 else:
2078 master.merge(runner)
2079
Christian Heimes25bb7832008-01-11 16:17:00 +00002080 return TestResults(runner.failures, runner.tries)
Edward Loper052d0cd2004-09-19 17:19:33 +00002081
Tim Peters8485b562004-08-04 18:46:34 +00002082def run_docstring_examples(f, globs, verbose=False, name="NoName",
2083 compileflags=None, optionflags=0):
2084 """
2085 Test examples in the given object's docstring (`f`), using `globs`
2086 as globals. Optional argument `name` is used in failure messages.
2087 If the optional argument `verbose` is true, then generate output
2088 even if there are no failures.
Tim Petersdb3756d2003-06-29 05:30:48 +00002089
Tim Peters8485b562004-08-04 18:46:34 +00002090 `compileflags` gives the set of flags that should be used by the
2091 Python compiler when running the examples. If not specified, then
2092 it will default to the set of future-import flags that apply to
2093 `globs`.
Tim Petersdb3756d2003-06-29 05:30:48 +00002094
Tim Peters8485b562004-08-04 18:46:34 +00002095 Optional keyword arg `optionflags` specifies options for the
2096 testing and output. See the documentation for `testmod` for more
2097 information.
2098 """
2099 # Find, parse, and run all tests in the given module.
2100 finder = DocTestFinder(verbose=verbose, recurse=False)
2101 runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
2102 for test in finder.find(f, name, globs=globs):
2103 runner.run(test, compileflags=compileflags)
Tim Petersdb3756d2003-06-29 05:30:48 +00002104
Tim Peters8485b562004-08-04 18:46:34 +00002105######################################################################
Georg Brandl31835852008-05-12 17:38:56 +00002106## 7. Unittest Support
Tim Peters8485b562004-08-04 18:46:34 +00002107######################################################################
Tim Petersdb3756d2003-06-29 05:30:48 +00002108
Jim Fultonf54bad42004-08-28 14:57:56 +00002109_unittest_reportflags = 0
Tim Peters38330fe2004-08-30 16:19:24 +00002110
Jim Fultonf54bad42004-08-28 14:57:56 +00002111def set_unittest_reportflags(flags):
Tim Peters38330fe2004-08-30 16:19:24 +00002112 """Sets the unittest option flags.
Jim Fultonf54bad42004-08-28 14:57:56 +00002113
2114 The old flag is returned so that a runner could restore the old
2115 value if it wished to:
2116
Tim Petersb7e99b62005-03-28 23:50:54 +00002117 >>> import doctest
2118 >>> old = doctest._unittest_reportflags
2119 >>> doctest.set_unittest_reportflags(REPORT_NDIFF |
Jim Fultonf54bad42004-08-28 14:57:56 +00002120 ... REPORT_ONLY_FIRST_FAILURE) == old
2121 True
2122
Jim Fultonf54bad42004-08-28 14:57:56 +00002123 >>> doctest._unittest_reportflags == (REPORT_NDIFF |
2124 ... REPORT_ONLY_FIRST_FAILURE)
2125 True
Tim Petersdf7a2082004-08-29 00:38:17 +00002126
Jim Fultonf54bad42004-08-28 14:57:56 +00002127 Only reporting flags can be set:
2128
Tim Petersb7e99b62005-03-28 23:50:54 +00002129 >>> doctest.set_unittest_reportflags(ELLIPSIS)
Jim Fultonf54bad42004-08-28 14:57:56 +00002130 Traceback (most recent call last):
2131 ...
Tim Peters38330fe2004-08-30 16:19:24 +00002132 ValueError: ('Only reporting flags allowed', 8)
Jim Fultonf54bad42004-08-28 14:57:56 +00002133
Tim Petersb7e99b62005-03-28 23:50:54 +00002134 >>> doctest.set_unittest_reportflags(old) == (REPORT_NDIFF |
Jim Fultonf54bad42004-08-28 14:57:56 +00002135 ... REPORT_ONLY_FIRST_FAILURE)
2136 True
Jim Fultonf54bad42004-08-28 14:57:56 +00002137 """
Jim Fultonf54bad42004-08-28 14:57:56 +00002138 global _unittest_reportflags
Tim Peters38330fe2004-08-30 16:19:24 +00002139
2140 if (flags & REPORTING_FLAGS) != flags:
2141 raise ValueError("Only reporting flags allowed", flags)
Jim Fultonf54bad42004-08-28 14:57:56 +00002142 old = _unittest_reportflags
2143 _unittest_reportflags = flags
2144 return old
Tim Petersdf7a2082004-08-29 00:38:17 +00002145
Jim Fultonf54bad42004-08-28 14:57:56 +00002146
Tim Peters19397e52004-08-06 22:02:59 +00002147class DocTestCase(unittest.TestCase):
Tim Petersdb3756d2003-06-29 05:30:48 +00002148
Edward Loper34fcb142004-08-09 02:45:41 +00002149 def __init__(self, test, optionflags=0, setUp=None, tearDown=None,
2150 checker=None):
Jim Fulton07a349c2004-08-22 14:10:00 +00002151
Jim Fultona643b652004-07-14 19:06:50 +00002152 unittest.TestCase.__init__(self)
Tim Peters19397e52004-08-06 22:02:59 +00002153 self._dt_optionflags = optionflags
Edward Loper34fcb142004-08-09 02:45:41 +00002154 self._dt_checker = checker
Tim Peters19397e52004-08-06 22:02:59 +00002155 self._dt_test = test
2156 self._dt_setUp = setUp
2157 self._dt_tearDown = tearDown
Tim Petersdb3756d2003-06-29 05:30:48 +00002158
Jim Fultona643b652004-07-14 19:06:50 +00002159 def setUp(self):
Jim Fultonf54bad42004-08-28 14:57:56 +00002160 test = self._dt_test
Tim Petersdf7a2082004-08-29 00:38:17 +00002161
Tim Peters19397e52004-08-06 22:02:59 +00002162 if self._dt_setUp is not None:
Jim Fultonf54bad42004-08-28 14:57:56 +00002163 self._dt_setUp(test)
Jim Fultona643b652004-07-14 19:06:50 +00002164
2165 def tearDown(self):
Jim Fultonf54bad42004-08-28 14:57:56 +00002166 test = self._dt_test
2167
Tim Peters19397e52004-08-06 22:02:59 +00002168 if self._dt_tearDown is not None:
Jim Fultonf54bad42004-08-28 14:57:56 +00002169 self._dt_tearDown(test)
2170
2171 test.globs.clear()
Jim Fultona643b652004-07-14 19:06:50 +00002172
2173 def runTest(self):
Tim Peters19397e52004-08-06 22:02:59 +00002174 test = self._dt_test
Jim Fultona643b652004-07-14 19:06:50 +00002175 old = sys.stdout
2176 new = StringIO()
Jim Fultonf54bad42004-08-28 14:57:56 +00002177 optionflags = self._dt_optionflags
Tim Petersdf7a2082004-08-29 00:38:17 +00002178
Tim Peters38330fe2004-08-30 16:19:24 +00002179 if not (optionflags & REPORTING_FLAGS):
Jim Fultonf54bad42004-08-28 14:57:56 +00002180 # The option flags don't include any reporting flags,
2181 # so add the default reporting flags
2182 optionflags |= _unittest_reportflags
Tim Petersdf7a2082004-08-29 00:38:17 +00002183
Jim Fultonf54bad42004-08-28 14:57:56 +00002184 runner = DocTestRunner(optionflags=optionflags,
Edward Loper34fcb142004-08-09 02:45:41 +00002185 checker=self._dt_checker, verbose=False)
Tim Peters19397e52004-08-06 22:02:59 +00002186
Jim Fultona643b652004-07-14 19:06:50 +00002187 try:
Tim Peters19397e52004-08-06 22:02:59 +00002188 runner.DIVIDER = "-"*70
Jim Fultonf54bad42004-08-28 14:57:56 +00002189 failures, tries = runner.run(
2190 test, out=new.write, clear_globs=False)
Jim Fultona643b652004-07-14 19:06:50 +00002191 finally:
2192 sys.stdout = old
2193
2194 if failures:
Tim Peters19397e52004-08-06 22:02:59 +00002195 raise self.failureException(self.format_failure(new.getvalue()))
Tim Peters8485b562004-08-04 18:46:34 +00002196
Tim Peters19397e52004-08-06 22:02:59 +00002197 def format_failure(self, err):
2198 test = self._dt_test
2199 if test.lineno is None:
2200 lineno = 'unknown line number'
2201 else:
Jim Fulton07a349c2004-08-22 14:10:00 +00002202 lineno = '%s' % test.lineno
Tim Peters19397e52004-08-06 22:02:59 +00002203 lname = '.'.join(test.name.split('.')[-1:])
2204 return ('Failed doctest test for %s\n'
2205 ' File "%s", line %s, in %s\n\n%s'
2206 % (test.name, test.filename, lineno, lname, err)
2207 )
2208
2209 def debug(self):
2210 r"""Run the test case without results and without catching exceptions
2211
2212 The unit test framework includes a debug method on test cases
2213 and test suites to support post-mortem debugging. The test code
2214 is run in such a way that errors are not caught. This way a
2215 caller can catch the errors and initiate post-mortem debugging.
2216
2217 The DocTestCase provides a debug method that raises
Ezio Melotti13925002011-03-16 11:05:33 +02002218 UnexpectedException errors if there is an unexpected
Tim Peters19397e52004-08-06 22:02:59 +00002219 exception:
2220
Edward Lopera1ef6112004-08-09 16:14:41 +00002221 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
Tim Peters19397e52004-08-06 22:02:59 +00002222 ... {}, 'foo', 'foo.py', 0)
2223 >>> case = DocTestCase(test)
2224 >>> try:
2225 ... case.debug()
Guido van Rossumb940e112007-01-10 16:19:56 +00002226 ... except UnexpectedException as f:
2227 ... failure = f
Tim Peters19397e52004-08-06 22:02:59 +00002228
2229 The UnexpectedException contains the test, the example, and
2230 the original exception:
2231
2232 >>> failure.test is test
2233 True
2234
2235 >>> failure.example.want
2236 '42\n'
2237
2238 >>> exc_info = failure.exc_info
Collin Winter828f04a2007-08-31 00:04:24 +00002239 >>> raise exc_info[1] # Already has the traceback
Tim Peters19397e52004-08-06 22:02:59 +00002240 Traceback (most recent call last):
2241 ...
2242 KeyError
2243
2244 If the output doesn't match, then a DocTestFailure is raised:
2245
Edward Lopera1ef6112004-08-09 16:14:41 +00002246 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00002247 ... >>> x = 1
2248 ... >>> x
2249 ... 2
2250 ... ''', {}, 'foo', 'foo.py', 0)
2251 >>> case = DocTestCase(test)
2252
2253 >>> try:
2254 ... case.debug()
Guido van Rossumb940e112007-01-10 16:19:56 +00002255 ... except DocTestFailure as f:
2256 ... failure = f
Tim Peters19397e52004-08-06 22:02:59 +00002257
2258 DocTestFailure objects provide access to the test:
2259
2260 >>> failure.test is test
2261 True
2262
2263 As well as to the example:
2264
2265 >>> failure.example.want
2266 '2\n'
2267
2268 and the actual output:
2269
2270 >>> failure.got
2271 '1\n'
2272
2273 """
2274
Jim Fultonf54bad42004-08-28 14:57:56 +00002275 self.setUp()
Edward Loper34fcb142004-08-09 02:45:41 +00002276 runner = DebugRunner(optionflags=self._dt_optionflags,
2277 checker=self._dt_checker, verbose=False)
Alexandre Vassalottieca20b62008-05-16 02:54:33 +00002278 runner.run(self._dt_test, clear_globs=False)
Jim Fultonf54bad42004-08-28 14:57:56 +00002279 self.tearDown()
Jim Fultona643b652004-07-14 19:06:50 +00002280
2281 def id(self):
Tim Peters19397e52004-08-06 22:02:59 +00002282 return self._dt_test.name
Jim Fultona643b652004-07-14 19:06:50 +00002283
Antoine Pitrou2bc801c2011-12-18 19:27:45 +01002284 def __eq__(self, other):
2285 if type(self) is not type(other):
2286 return NotImplemented
2287
2288 return self._dt_test == other._dt_test and \
2289 self._dt_optionflags == other._dt_optionflags and \
2290 self._dt_setUp == other._dt_setUp and \
2291 self._dt_tearDown == other._dt_tearDown and \
2292 self._dt_checker == other._dt_checker
2293
2294 def __ne__(self, other):
2295 return not self == other
2296
Antoine Pitrou165b1282011-12-18 20:20:17 +01002297 def __hash__(self):
2298 return hash((self._dt_optionflags, self._dt_setUp, self._dt_tearDown,
2299 self._dt_checker))
2300
Jim Fultona643b652004-07-14 19:06:50 +00002301 def __repr__(self):
Tim Peters19397e52004-08-06 22:02:59 +00002302 name = self._dt_test.name.split('.')
Jim Fultona643b652004-07-14 19:06:50 +00002303 return "%s (%s)" % (name[-1], '.'.join(name[:-1]))
2304
2305 __str__ = __repr__
2306
2307 def shortDescription(self):
Tim Peters19397e52004-08-06 22:02:59 +00002308 return "Doctest: " + self._dt_test.name
Jim Fultona643b652004-07-14 19:06:50 +00002309
R. David Murray378c0cf2010-02-24 01:46:21 +00002310class SkipDocTestCase(DocTestCase):
R David Murraye1121532012-03-21 14:53:42 -04002311 def __init__(self, module):
2312 self.module = module
R. David Murray378c0cf2010-02-24 01:46:21 +00002313 DocTestCase.__init__(self, None)
2314
2315 def setUp(self):
2316 self.skipTest("DocTestSuite will not work with -O2 and above")
2317
2318 def test_skip(self):
2319 pass
2320
2321 def shortDescription(self):
R David Murraye1121532012-03-21 14:53:42 -04002322 return "Skipping tests from %s" % self.module.__name__
2323
2324 __str__ = shortDescription
2325
R. David Murray378c0cf2010-02-24 01:46:21 +00002326
Andrew Svetlov7c1017b2013-08-29 01:24:39 +03002327class _DocTestSuite(unittest.TestSuite):
2328
2329 def _removeTestAtIndex(self, index):
2330 pass
2331
2332
Jim Fultonf54bad42004-08-28 14:57:56 +00002333def DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None,
2334 **options):
Tim Peters8485b562004-08-04 18:46:34 +00002335 """
Tim Peters75dc5e12004-08-22 17:50:45 +00002336 Convert doctest tests for a module to a unittest test suite.
Jim Fultona643b652004-07-14 19:06:50 +00002337
Tim Peters19397e52004-08-06 22:02:59 +00002338 This converts each documentation string in a module that
2339 contains doctest tests to a unittest test case. If any of the
2340 tests in a doc string fail, then the test case fails. An exception
2341 is raised showing the name of the file containing the test and a
Jim Fultona643b652004-07-14 19:06:50 +00002342 (sometimes approximate) line number.
2343
Tim Peters19397e52004-08-06 22:02:59 +00002344 The `module` argument provides the module to be tested. The argument
Jim Fultona643b652004-07-14 19:06:50 +00002345 can be either a module or a module name.
2346
2347 If no argument is given, the calling module is used.
Jim Fultonf54bad42004-08-28 14:57:56 +00002348
2349 A number of options may be provided as keyword arguments:
2350
Jim Fultonf54bad42004-08-28 14:57:56 +00002351 setUp
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002352 A set-up function. This is called before running the
Jim Fultonf54bad42004-08-28 14:57:56 +00002353 tests in each file. The setUp function will be passed a DocTest
2354 object. The setUp function can access the test globals as the
2355 globs attribute of the test passed.
2356
2357 tearDown
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002358 A tear-down function. This is called after running the
Jim Fultonf54bad42004-08-28 14:57:56 +00002359 tests in each file. The tearDown function will be passed a DocTest
2360 object. The tearDown function can access the test globals as the
2361 globs attribute of the test passed.
2362
2363 globs
2364 A dictionary containing initial global variables for the tests.
2365
2366 optionflags
2367 A set of doctest option flags expressed as an integer.
Jim Fultona643b652004-07-14 19:06:50 +00002368 """
Jim Fultona643b652004-07-14 19:06:50 +00002369
Tim Peters8485b562004-08-04 18:46:34 +00002370 if test_finder is None:
2371 test_finder = DocTestFinder()
Tim Peters8485b562004-08-04 18:46:34 +00002372
Tim Peters19397e52004-08-06 22:02:59 +00002373 module = _normalize_module(module)
2374 tests = test_finder.find(module, globs=globs, extraglobs=extraglobs)
R. David Murray378c0cf2010-02-24 01:46:21 +00002375
2376 if not tests and sys.flags.optimize >=2:
2377 # Skip doctests when running with -O2
Andrew Svetlov7c1017b2013-08-29 01:24:39 +03002378 suite = _DocTestSuite()
R David Murraye1121532012-03-21 14:53:42 -04002379 suite.addTest(SkipDocTestCase(module))
R. David Murray378c0cf2010-02-24 01:46:21 +00002380 return suite
Tim Petersdb3756d2003-06-29 05:30:48 +00002381
2382 tests.sort()
Andrew Svetlov7c1017b2013-08-29 01:24:39 +03002383 suite = _DocTestSuite()
R. David Murray378c0cf2010-02-24 01:46:21 +00002384
Tim Peters8485b562004-08-04 18:46:34 +00002385 for test in tests:
Tim Peters19397e52004-08-06 22:02:59 +00002386 if len(test.examples) == 0:
2387 continue
Tim Peters8485b562004-08-04 18:46:34 +00002388 if not test.filename:
Tim Petersdb3756d2003-06-29 05:30:48 +00002389 filename = module.__file__
Jim Fulton07a349c2004-08-22 14:10:00 +00002390 if filename[-4:] in (".pyc", ".pyo"):
Tim Petersdb3756d2003-06-29 05:30:48 +00002391 filename = filename[:-1]
Tim Peters8485b562004-08-04 18:46:34 +00002392 test.filename = filename
Jim Fultonf54bad42004-08-28 14:57:56 +00002393 suite.addTest(DocTestCase(test, **options))
Tim Peters19397e52004-08-06 22:02:59 +00002394
2395 return suite
2396
2397class DocFileCase(DocTestCase):
2398
2399 def id(self):
2400 return '_'.join(self._dt_test.name.split('.'))
2401
2402 def __repr__(self):
2403 return self._dt_test.filename
2404 __str__ = __repr__
2405
2406 def format_failure(self, err):
2407 return ('Failed doctest test for %s\n File "%s", line 0\n\n%s'
2408 % (self._dt_test.name, self._dt_test.filename, err)
2409 )
2410
Edward Loper052d0cd2004-09-19 17:19:33 +00002411def DocFileTest(path, module_relative=True, package=None,
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00002412 globs=None, parser=DocTestParser(),
2413 encoding=None, **options):
Tim Peters19397e52004-08-06 22:02:59 +00002414 if globs is None:
2415 globs = {}
Fred Drake7c404a42004-12-21 23:46:34 +00002416 else:
2417 globs = globs.copy()
Tim Peters19397e52004-08-06 22:02:59 +00002418
Edward Loper052d0cd2004-09-19 17:19:33 +00002419 if package and not module_relative:
2420 raise ValueError("Package may only be specified for module-"
2421 "relative paths.")
Tim Petersbab3e992004-09-20 19:52:34 +00002422
Edward Loper052d0cd2004-09-19 17:19:33 +00002423 # Relativize the path.
Guido van Rossum1b81e7b2007-08-29 03:53:53 +00002424 doc, path = _load_testfile(path, package, module_relative,
2425 encoding or "utf-8")
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00002426
Fred Drake7c404a42004-12-21 23:46:34 +00002427 if "__file__" not in globs:
2428 globs["__file__"] = path
Tim Peters19397e52004-08-06 22:02:59 +00002429
Edward Loper052d0cd2004-09-19 17:19:33 +00002430 # Find the file and read it.
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002431 name = os.path.basename(path)
Edward Loper052d0cd2004-09-19 17:19:33 +00002432
2433 # Convert it to a test, and wrap it in a DocFileCase.
Edward Loper498a1862004-09-27 03:42:58 +00002434 test = parser.get_doctest(doc, globs, name, path, 0)
Jim Fultonf54bad42004-08-28 14:57:56 +00002435 return DocFileCase(test, **options)
Tim Peters19397e52004-08-06 22:02:59 +00002436
2437def DocFileSuite(*paths, **kw):
Edward Loper052d0cd2004-09-19 17:19:33 +00002438 """A unittest suite for one or more doctest files.
Tim Petersbab3e992004-09-20 19:52:34 +00002439
Edward Loper052d0cd2004-09-19 17:19:33 +00002440 The path to each doctest file is given as a string; the
2441 interpretation of that string depends on the keyword argument
2442 "module_relative".
Tim Peters19397e52004-08-06 22:02:59 +00002443
2444 A number of options may be provided as keyword arguments:
2445
Edward Loper052d0cd2004-09-19 17:19:33 +00002446 module_relative
2447 If "module_relative" is True, then the given file paths are
2448 interpreted as os-independent module-relative paths. By
2449 default, these paths are relative to the calling module's
2450 directory; but if the "package" argument is specified, then
2451 they are relative to that package. To ensure os-independence,
2452 "filename" should use "/" characters to separate path
2453 segments, and may not be an absolute path (i.e., it may not
2454 begin with "/").
Tim Petersbab3e992004-09-20 19:52:34 +00002455
Edward Loper052d0cd2004-09-19 17:19:33 +00002456 If "module_relative" is False, then the given file paths are
2457 interpreted as os-specific paths. These paths may be absolute
2458 or relative (to the current working directory).
2459
Tim Peters19397e52004-08-06 22:02:59 +00002460 package
Edward Loper052d0cd2004-09-19 17:19:33 +00002461 A Python package or the name of a Python package whose directory
2462 should be used as the base directory for module relative paths.
2463 If "package" is not specified, then the calling module's
2464 directory is used as the base directory for module relative
2465 filenames. It is an error to specify "package" if
2466 "module_relative" is False.
Tim Peters19397e52004-08-06 22:02:59 +00002467
2468 setUp
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002469 A set-up function. This is called before running the
Jim Fultonf54bad42004-08-28 14:57:56 +00002470 tests in each file. The setUp function will be passed a DocTest
2471 object. The setUp function can access the test globals as the
2472 globs attribute of the test passed.
Tim Peters19397e52004-08-06 22:02:59 +00002473
2474 tearDown
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002475 A tear-down function. This is called after running the
Jim Fultonf54bad42004-08-28 14:57:56 +00002476 tests in each file. The tearDown function will be passed a DocTest
2477 object. The tearDown function can access the test globals as the
2478 globs attribute of the test passed.
Tim Peters19397e52004-08-06 22:02:59 +00002479
2480 globs
2481 A dictionary containing initial global variables for the tests.
Jim Fultonf54bad42004-08-28 14:57:56 +00002482
2483 optionflags
Edward Loper498a1862004-09-27 03:42:58 +00002484 A set of doctest option flags expressed as an integer.
2485
2486 parser
2487 A DocTestParser (or subclass) that should be used to extract
2488 tests from the files.
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00002489
2490 encoding
2491 An encoding that will be used to convert the files to unicode.
Tim Peters19397e52004-08-06 22:02:59 +00002492 """
Andrew Svetlov7c1017b2013-08-29 01:24:39 +03002493 suite = _DocTestSuite()
Tim Peters19397e52004-08-06 22:02:59 +00002494
2495 # We do this here so that _normalize_module is called at the right
2496 # level. If it were called in DocFileTest, then this function
2497 # would be the caller and we might guess the package incorrectly.
Edward Loper052d0cd2004-09-19 17:19:33 +00002498 if kw.get('module_relative', True):
2499 kw['package'] = _normalize_module(kw.get('package'))
Tim Peters19397e52004-08-06 22:02:59 +00002500
2501 for path in paths:
2502 suite.addTest(DocFileTest(path, **kw))
Jim Fultona643b652004-07-14 19:06:50 +00002503
Tim Petersdb3756d2003-06-29 05:30:48 +00002504 return suite
2505
Tim Peters8485b562004-08-04 18:46:34 +00002506######################################################################
Georg Brandl31835852008-05-12 17:38:56 +00002507## 8. Debugging Support
Tim Peters8485b562004-08-04 18:46:34 +00002508######################################################################
Jim Fultona643b652004-07-14 19:06:50 +00002509
Tim Peters19397e52004-08-06 22:02:59 +00002510def script_from_examples(s):
2511 r"""Extract script from text with examples.
2512
2513 Converts text with examples to a Python script. Example input is
2514 converted to regular code. Example output and all other words
2515 are converted to comments:
2516
2517 >>> text = '''
2518 ... Here are examples of simple math.
2519 ...
2520 ... Python has super accurate integer addition
2521 ...
2522 ... >>> 2 + 2
2523 ... 5
2524 ...
2525 ... And very friendly error messages:
2526 ...
2527 ... >>> 1/0
2528 ... To Infinity
2529 ... And
2530 ... Beyond
2531 ...
2532 ... You can use logic if you want:
2533 ...
2534 ... >>> if 0:
2535 ... ... blah
2536 ... ... blah
2537 ... ...
2538 ...
2539 ... Ho hum
2540 ... '''
2541
Guido van Rossum7131f842007-02-09 20:13:25 +00002542 >>> print(script_from_examples(text))
Edward Lopera5db6002004-08-12 02:41:30 +00002543 # Here are examples of simple math.
Tim Peters19397e52004-08-06 22:02:59 +00002544 #
Edward Lopera5db6002004-08-12 02:41:30 +00002545 # Python has super accurate integer addition
Tim Peters19397e52004-08-06 22:02:59 +00002546 #
2547 2 + 2
2548 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +00002549 ## 5
Tim Peters19397e52004-08-06 22:02:59 +00002550 #
Edward Lopera5db6002004-08-12 02:41:30 +00002551 # And very friendly error messages:
Tim Peters19397e52004-08-06 22:02:59 +00002552 #
2553 1/0
2554 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +00002555 ## To Infinity
2556 ## And
2557 ## Beyond
Tim Peters19397e52004-08-06 22:02:59 +00002558 #
Edward Lopera5db6002004-08-12 02:41:30 +00002559 # You can use logic if you want:
Tim Peters19397e52004-08-06 22:02:59 +00002560 #
2561 if 0:
2562 blah
2563 blah
Tim Peters19397e52004-08-06 22:02:59 +00002564 #
Edward Lopera5db6002004-08-12 02:41:30 +00002565 # Ho hum
Georg Brandlecf93c72005-06-26 23:09:51 +00002566 <BLANKLINE>
Tim Peters19397e52004-08-06 22:02:59 +00002567 """
Edward Loper00f8da72004-08-26 18:05:07 +00002568 output = []
2569 for piece in DocTestParser().parse(s):
2570 if isinstance(piece, Example):
2571 # Add the example's source code (strip trailing NL)
2572 output.append(piece.source[:-1])
2573 # Add the expected output:
2574 want = piece.want
2575 if want:
2576 output.append('# Expected:')
2577 output += ['## '+l for l in want.split('\n')[:-1]]
2578 else:
2579 # Add non-example text.
2580 output += [_comment_line(l)
2581 for l in piece.split('\n')[:-1]]
Tim Peters19397e52004-08-06 22:02:59 +00002582
Edward Loper00f8da72004-08-26 18:05:07 +00002583 # Trim junk on both ends.
2584 while output and output[-1] == '#':
2585 output.pop()
2586 while output and output[0] == '#':
2587 output.pop(0)
2588 # Combine the output, and return it.
Georg Brandl1f149642005-06-26 22:22:31 +00002589 # Add a courtesy newline to prevent exec from choking (see bug #1172785)
2590 return '\n'.join(output) + '\n'
Tim Petersdb3756d2003-06-29 05:30:48 +00002591
2592def testsource(module, name):
Tim Peters19397e52004-08-06 22:02:59 +00002593 """Extract the test sources from a doctest docstring as a script.
Tim Petersdb3756d2003-06-29 05:30:48 +00002594
2595 Provide the module (or dotted name of the module) containing the
Jim Fultona643b652004-07-14 19:06:50 +00002596 test to be debugged and the name (within the module) of the object
2597 with the doc string with tests to be debugged.
Tim Petersdb3756d2003-06-29 05:30:48 +00002598 """
Tim Peters8485b562004-08-04 18:46:34 +00002599 module = _normalize_module(module)
2600 tests = DocTestFinder().find(module)
2601 test = [t for t in tests if t.name == name]
Tim Petersdb3756d2003-06-29 05:30:48 +00002602 if not test:
2603 raise ValueError(name, "not found in tests")
2604 test = test[0]
Tim Peters19397e52004-08-06 22:02:59 +00002605 testsrc = script_from_examples(test.docstring)
Jim Fultona643b652004-07-14 19:06:50 +00002606 return testsrc
Tim Petersdb3756d2003-06-29 05:30:48 +00002607
Jim Fultona643b652004-07-14 19:06:50 +00002608def debug_src(src, pm=False, globs=None):
Tim Peters19397e52004-08-06 22:02:59 +00002609 """Debug a single doctest docstring, in argument `src`'"""
2610 testsrc = script_from_examples(src)
Tim Peters8485b562004-08-04 18:46:34 +00002611 debug_script(testsrc, pm, globs)
Tim Petersdb3756d2003-06-29 05:30:48 +00002612
Jim Fultona643b652004-07-14 19:06:50 +00002613def debug_script(src, pm=False, globs=None):
Tim Peters19397e52004-08-06 22:02:59 +00002614 "Debug a test script. `src` is the script, as a string."
Tim Petersdb3756d2003-06-29 05:30:48 +00002615 import pdb
Tim Petersdb3756d2003-06-29 05:30:48 +00002616
Victor Stinner12b8d142011-06-30 17:35:55 +02002617 if globs:
2618 globs = globs.copy()
2619 else:
2620 globs = {}
Tim Peters8485b562004-08-04 18:46:34 +00002621
Victor Stinner12b8d142011-06-30 17:35:55 +02002622 if pm:
2623 try:
2624 exec(src, globs, globs)
2625 except:
2626 print(sys.exc_info()[1])
2627 p = pdb.Pdb(nosigint=True)
2628 p.reset()
2629 p.interaction(None, sys.exc_info()[2])
2630 else:
2631 pdb.Pdb(nosigint=True).run("exec(%r)" % src, globs, globs)
Tim Petersdb3756d2003-06-29 05:30:48 +00002632
Jim Fultona643b652004-07-14 19:06:50 +00002633def debug(module, name, pm=False):
Tim Peters19397e52004-08-06 22:02:59 +00002634 """Debug a single doctest docstring.
Jim Fultona643b652004-07-14 19:06:50 +00002635
2636 Provide the module (or dotted name of the module) containing the
2637 test to be debugged and the name (within the module) of the object
Tim Peters19397e52004-08-06 22:02:59 +00002638 with the docstring with tests to be debugged.
Jim Fultona643b652004-07-14 19:06:50 +00002639 """
Tim Peters8485b562004-08-04 18:46:34 +00002640 module = _normalize_module(module)
Jim Fultona643b652004-07-14 19:06:50 +00002641 testsrc = testsource(module, name)
2642 debug_script(testsrc, pm, module.__dict__)
2643
Tim Peters8485b562004-08-04 18:46:34 +00002644######################################################################
Georg Brandl31835852008-05-12 17:38:56 +00002645## 9. Example Usage
Tim Peters8485b562004-08-04 18:46:34 +00002646######################################################################
Tim Peters8a7d2d52001-01-16 07:10:57 +00002647class _TestClass:
2648 """
2649 A pointless class, for sanity-checking of docstring testing.
2650
2651 Methods:
2652 square()
2653 get()
2654
2655 >>> _TestClass(13).get() + _TestClass(-12).get()
2656 1
2657 >>> hex(_TestClass(13).square().get())
2658 '0xa9'
2659 """
2660
2661 def __init__(self, val):
2662 """val -> _TestClass object with associated value val.
2663
2664 >>> t = _TestClass(123)
Guido van Rossum7131f842007-02-09 20:13:25 +00002665 >>> print(t.get())
Tim Peters8a7d2d52001-01-16 07:10:57 +00002666 123
2667 """
2668
2669 self.val = val
2670
2671 def square(self):
2672 """square() -> square TestClass's associated value
2673
2674 >>> _TestClass(13).square().get()
2675 169
2676 """
2677
2678 self.val = self.val ** 2
2679 return self
2680
2681 def get(self):
2682 """get() -> return TestClass's associated value.
2683
2684 >>> x = _TestClass(-42)
Guido van Rossum7131f842007-02-09 20:13:25 +00002685 >>> print(x.get())
Tim Peters8a7d2d52001-01-16 07:10:57 +00002686 -42
2687 """
2688
2689 return self.val
2690
2691__test__ = {"_TestClass": _TestClass,
2692 "string": r"""
2693 Example of a string object, searched as-is.
2694 >>> x = 1; y = 2
2695 >>> x + y, x * y
2696 (3, 2)
Tim Peters6ebe61f2003-06-27 20:48:05 +00002697 """,
Tim Peters3fa8c202004-08-23 21:43:39 +00002698
Tim Peters6ebe61f2003-06-27 20:48:05 +00002699 "bool-int equivalence": r"""
2700 In 2.2, boolean expressions displayed
2701 0 or 1. By default, we still accept
2702 them. This can be disabled by passing
2703 DONT_ACCEPT_TRUE_FOR_1 to the new
2704 optionflags argument.
2705 >>> 4 == 4
2706 1
2707 >>> 4 == 4
2708 True
2709 >>> 4 > 4
2710 0
2711 >>> 4 > 4
2712 False
2713 """,
Tim Peters3fa8c202004-08-23 21:43:39 +00002714
Tim Peters8485b562004-08-04 18:46:34 +00002715 "blank lines": r"""
Tim Peters3fa8c202004-08-23 21:43:39 +00002716 Blank lines can be marked with <BLANKLINE>:
Guido van Rossum7131f842007-02-09 20:13:25 +00002717 >>> print('foo\n\nbar\n')
Tim Peters3fa8c202004-08-23 21:43:39 +00002718 foo
2719 <BLANKLINE>
2720 bar
2721 <BLANKLINE>
Tim Peters8485b562004-08-04 18:46:34 +00002722 """,
Tim Peters3fa8c202004-08-23 21:43:39 +00002723
2724 "ellipsis": r"""
2725 If the ellipsis flag is used, then '...' can be used to
2726 elide substrings in the desired output:
Guido van Rossum805365e2007-05-07 22:24:25 +00002727 >>> print(list(range(1000))) #doctest: +ELLIPSIS
Tim Peters3fa8c202004-08-23 21:43:39 +00002728 [0, 1, 2, ..., 999]
2729 """,
2730
2731 "whitespace normalization": r"""
2732 If the whitespace normalization flag is used, then
2733 differences in whitespace are ignored.
Guido van Rossum805365e2007-05-07 22:24:25 +00002734 >>> print(list(range(30))) #doctest: +NORMALIZE_WHITESPACE
Tim Peters3fa8c202004-08-23 21:43:39 +00002735 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
2736 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,
2737 27, 28, 29]
2738 """,
2739 }
Tim Peters8485b562004-08-04 18:46:34 +00002740
R. David Murray445448c2009-12-20 17:28:31 +00002741
Tim Peters8a7d2d52001-01-16 07:10:57 +00002742def _test():
R David Murray5707d502013-06-23 14:24:13 -04002743 parser = argparse.ArgumentParser(description="doctest runner")
2744 parser.add_argument('-v', '--verbose', action='store_true', default=False,
2745 help='print very verbose output for all tests')
2746 parser.add_argument('-o', '--option', action='append',
2747 choices=OPTIONFLAGS_BY_NAME.keys(), default=[],
2748 help=('specify a doctest option flag to apply'
2749 ' to the test run; may be specified more'
2750 ' than once to apply multiple options'))
2751 parser.add_argument('-f', '--fail-fast', action='store_true',
2752 help=('stop running tests after first failure (this'
2753 ' is a shorthand for -o FAIL_FAST, and is'
2754 ' in addition to any other -o options)'))
2755 parser.add_argument('file', nargs='+',
2756 help='file containing the tests to run')
2757 args = parser.parse_args()
2758 testfiles = args.file
2759 # Verbose used to be handled by the "inspect argv" magic in DocTestRunner,
2760 # but since we are using argparse we are passing it manually now.
2761 verbose = args.verbose
2762 options = 0
2763 for option in args.option:
2764 options |= OPTIONFLAGS_BY_NAME[option]
2765 if args.fail_fast:
2766 options |= FAIL_FAST
R. David Murray445448c2009-12-20 17:28:31 +00002767 for filename in testfiles:
2768 if filename.endswith(".py"):
2769 # It is a module -- insert its dir into sys.path and try to
2770 # import it. If it is part of a package, that possibly
2771 # won't work because of package imports.
2772 dirname, filename = os.path.split(filename)
2773 sys.path.insert(0, dirname)
2774 m = __import__(filename[:-3])
2775 del sys.path[0]
R David Murray5707d502013-06-23 14:24:13 -04002776 failures, _ = testmod(m, verbose=verbose, optionflags=options)
R. David Murray445448c2009-12-20 17:28:31 +00002777 else:
R David Murray5707d502013-06-23 14:24:13 -04002778 failures, _ = testfile(filename, module_relative=False,
2779 verbose=verbose, optionflags=options)
R. David Murray445448c2009-12-20 17:28:31 +00002780 if failures:
2781 return 1
Christian Heimes895627f2007-12-08 17:28:33 +00002782 return 0
Tim Peters8a7d2d52001-01-16 07:10:57 +00002783
R. David Murray445448c2009-12-20 17:28:31 +00002784
Tim Peters8a7d2d52001-01-16 07:10:57 +00002785if __name__ == "__main__":
Christian Heimes895627f2007-12-08 17:28:33 +00002786 sys.exit(_test())