blob: 22052ec030bf489d200ba1aeae9006df852eaa9b [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',
Edward Loperb7503ff2004-08-19 19:19:03 +000065 # 1. Utility Functions
Edward Loperb7503ff2004-08-19 19:19:03 +000066 # 2. Example & DocTest
Tim Peters8485b562004-08-04 18:46:34 +000067 'Example',
68 'DocTest',
Edward Loperb7503ff2004-08-19 19:19:03 +000069 # 3. Doctest Parser
70 'DocTestParser',
71 # 4. Doctest Finder
Tim Peters8485b562004-08-04 18:46:34 +000072 'DocTestFinder',
Edward Loperb7503ff2004-08-19 19:19:03 +000073 # 5. Doctest Runner
Tim Peters8485b562004-08-04 18:46:34 +000074 'DocTestRunner',
Edward Loperb7503ff2004-08-19 19:19:03 +000075 'OutputChecker',
76 'DocTestFailure',
77 'UnexpectedException',
78 'DebugRunner',
79 # 6. Test Functions
Tim Peters4fd9e2f2001-08-18 00:05:50 +000080 'testmod',
Edward Loper052d0cd2004-09-19 17:19:33 +000081 'testfile',
Tim Peters4fd9e2f2001-08-18 00:05:50 +000082 'run_docstring_examples',
Georg Brandlcc80bfe2008-05-12 18:06:23 +000083 # 7. Unittest Support
Tim Petersdb3756d2003-06-29 05:30:48 +000084 'DocTestSuite',
Edward Loperb7503ff2004-08-19 19:19:03 +000085 'DocFileSuite',
Tim Peters9d02a7c2004-09-26 01:50:24 +000086 'set_unittest_reportflags',
Georg Brandlcc80bfe2008-05-12 18:06:23 +000087 # 8. Debugging Support
Edward Loperb7503ff2004-08-19 19:19:03 +000088 'script_from_examples',
Tim Petersdb3756d2003-06-29 05:30:48 +000089 'testsource',
Edward Loperb7503ff2004-08-19 19:19:03 +000090 'debug_src',
Tim Petersdb3756d2003-06-29 05:30:48 +000091 'debug',
Tim Peters4fd9e2f2001-08-18 00:05:50 +000092]
Tim Peters8a7d2d52001-01-16 07:10:57 +000093
Tim Peters4fd9e2f2001-08-18 00:05:50 +000094import __future__
Tim Peters8a7d2d52001-01-16 07:10:57 +000095
Thomas Wouters0e3f5912006-08-11 14:57:12 +000096import sys, traceback, inspect, linecache, os, re
Jim Fulton356fd192004-08-09 11:34:47 +000097import unittest, difflib, pdb, tempfile
Tim Petersf727c6c2004-08-08 01:48:59 +000098import warnings
Guido van Rossum34d19282007-08-09 01:03:29 +000099from io import StringIO
Christian Heimes25bb7832008-01-11 16:17:00 +0000100from collections import namedtuple
101
102TestResults = namedtuple('TestResults', 'failed attempted')
Tim Peters7402f792001-10-02 03:53:41 +0000103
Tim Peters19397e52004-08-06 22:02:59 +0000104# There are 4 basic classes:
105# - Example: a <source, want> pair, plus an intra-docstring line number.
106# - DocTest: a collection of examples, parsed from a docstring, plus
107# info about where the docstring came from (name, filename, lineno).
108# - DocTestFinder: extracts DocTests from a given object's docstring and
109# its contained objects' docstrings.
110# - DocTestRunner: runs DocTest cases, and accumulates statistics.
111#
112# So the basic picture is:
113#
114# list of:
115# +------+ +---------+ +-------+
116# |object| --DocTestFinder-> | DocTest | --DocTestRunner-> |results|
117# +------+ +---------+ +-------+
118# | Example |
119# | ... |
120# | Example |
121# +---------+
122
Edward Loperac20f572004-08-12 02:02:24 +0000123# Option constants.
Tim Peters38330fe2004-08-30 16:19:24 +0000124
Edward Loperac20f572004-08-12 02:02:24 +0000125OPTIONFLAGS_BY_NAME = {}
126def register_optionflag(name):
Thomas Wouters477c8d52006-05-27 19:21:47 +0000127 # Create a new flag unless `name` is already known.
128 return OPTIONFLAGS_BY_NAME.setdefault(name, 1 << len(OPTIONFLAGS_BY_NAME))
Edward Loperac20f572004-08-12 02:02:24 +0000129
130DONT_ACCEPT_TRUE_FOR_1 = register_optionflag('DONT_ACCEPT_TRUE_FOR_1')
131DONT_ACCEPT_BLANKLINE = register_optionflag('DONT_ACCEPT_BLANKLINE')
132NORMALIZE_WHITESPACE = register_optionflag('NORMALIZE_WHITESPACE')
133ELLIPSIS = register_optionflag('ELLIPSIS')
Thomas Wouters477c8d52006-05-27 19:21:47 +0000134SKIP = register_optionflag('SKIP')
Tim Peters1fbf9c52004-09-04 17:21:02 +0000135IGNORE_EXCEPTION_DETAIL = register_optionflag('IGNORE_EXCEPTION_DETAIL')
Tim Peters38330fe2004-08-30 16:19:24 +0000136
137COMPARISON_FLAGS = (DONT_ACCEPT_TRUE_FOR_1 |
138 DONT_ACCEPT_BLANKLINE |
139 NORMALIZE_WHITESPACE |
Tim Peters1fbf9c52004-09-04 17:21:02 +0000140 ELLIPSIS |
Thomas Wouters477c8d52006-05-27 19:21:47 +0000141 SKIP |
Edward Loper7d88a582004-09-28 05:50:57 +0000142 IGNORE_EXCEPTION_DETAIL)
Tim Peters38330fe2004-08-30 16:19:24 +0000143
Edward Loper71f55af2004-08-26 01:41:51 +0000144REPORT_UDIFF = register_optionflag('REPORT_UDIFF')
145REPORT_CDIFF = register_optionflag('REPORT_CDIFF')
146REPORT_NDIFF = register_optionflag('REPORT_NDIFF')
Edward Lopera89f88d2004-08-26 02:45:51 +0000147REPORT_ONLY_FIRST_FAILURE = register_optionflag('REPORT_ONLY_FIRST_FAILURE')
Edward Loperac20f572004-08-12 02:02:24 +0000148
Tim Peters38330fe2004-08-30 16:19:24 +0000149REPORTING_FLAGS = (REPORT_UDIFF |
150 REPORT_CDIFF |
151 REPORT_NDIFF |
152 REPORT_ONLY_FIRST_FAILURE)
153
Edward Loperac20f572004-08-12 02:02:24 +0000154# Special string markers for use in `want` strings:
155BLANKLINE_MARKER = '<BLANKLINE>'
156ELLIPSIS_MARKER = '...'
157
Tim Peters8485b562004-08-04 18:46:34 +0000158######################################################################
159## Table of Contents
160######################################################################
Edward Loper7c748462004-08-09 02:06:06 +0000161# 1. Utility Functions
162# 2. Example & DocTest -- store test cases
163# 3. DocTest Parser -- extracts examples from strings
164# 4. DocTest Finder -- extracts test cases from objects
165# 5. DocTest Runner -- runs test cases
166# 6. Test Functions -- convenient wrappers for testing
Georg Brandl31835852008-05-12 17:38:56 +0000167# 7. Unittest Support
168# 8. Debugging Support
169# 9. Example Usage
Tim Peters8a7d2d52001-01-16 07:10:57 +0000170
Tim Peters8485b562004-08-04 18:46:34 +0000171######################################################################
172## 1. Utility Functions
173######################################################################
Tim Peters8a7d2d52001-01-16 07:10:57 +0000174
Tim Peters8485b562004-08-04 18:46:34 +0000175def _extract_future_flags(globs):
176 """
177 Return the compiler-flags associated with the future features that
178 have been imported into the given namespace (globs).
179 """
180 flags = 0
181 for fname in __future__.all_feature_names:
182 feature = globs.get(fname, None)
183 if feature is getattr(__future__, fname):
184 flags |= feature.compiler_flag
185 return flags
Tim Peters7402f792001-10-02 03:53:41 +0000186
Tim Peters8485b562004-08-04 18:46:34 +0000187def _normalize_module(module, depth=2):
188 """
189 Return the module specified by `module`. In particular:
190 - If `module` is a module, then return module.
191 - If `module` is a string, then import and return the
192 module with that name.
193 - If `module` is None, then return the calling module.
194 The calling module is assumed to be the module of
195 the stack frame at the given depth in the call stack.
196 """
197 if inspect.ismodule(module):
198 return module
Walter Dörwaldaa97f042007-05-03 21:05:51 +0000199 elif isinstance(module, str):
Tim Peters8485b562004-08-04 18:46:34 +0000200 return __import__(module, globals(), locals(), ["*"])
201 elif module is None:
202 return sys.modules[sys._getframe(depth).f_globals['__name__']]
203 else:
204 raise TypeError("Expected a module, string, or None")
Tim Peters7402f792001-10-02 03:53:41 +0000205
Guido van Rossum1b81e7b2007-08-29 03:53:53 +0000206def _load_testfile(filename, package, module_relative, encoding):
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000207 if module_relative:
208 package = _normalize_module(package, 3)
209 filename = _module_relative_path(package, filename)
210 if hasattr(package, '__loader__'):
211 if hasattr(package.__loader__, 'get_data'):
Guido van Rossumcd4d4522007-11-22 00:30:02 +0000212 file_contents = package.__loader__.get_data(filename)
213 file_contents = file_contents.decode(encoding)
214 # get_data() opens files as 'rb', so one must do the equivalent
215 # conversion as universal newlines would do.
216 return file_contents.replace(os.linesep, '\n'), filename
Guido van Rossum1b81e7b2007-08-29 03:53:53 +0000217 return open(filename, encoding=encoding).read(), filename
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000218
Edward Loperaacf0832004-08-26 01:19:50 +0000219def _indent(s, indent=4):
Tim Peters8485b562004-08-04 18:46:34 +0000220 """
Edward Loperaacf0832004-08-26 01:19:50 +0000221 Add the given number of space characters to the beginning every
222 non-blank line in `s`, and return the result.
Tim Peters8485b562004-08-04 18:46:34 +0000223 """
Edward Loperaacf0832004-08-26 01:19:50 +0000224 # This regexp matches the start of non-blank lines:
225 return re.sub('(?m)^(?!$)', indent*' ', s)
Tim Peters8a7d2d52001-01-16 07:10:57 +0000226
Edward Loper8e4a34b2004-08-12 02:34:27 +0000227def _exception_traceback(exc_info):
228 """
229 Return a string containing a traceback message for the given
230 exc_info tuple (as returned by sys.exc_info()).
231 """
232 # Get a traceback message.
233 excout = StringIO()
234 exc_type, exc_val, exc_tb = exc_info
235 traceback.print_exception(exc_type, exc_val, exc_tb, file=excout)
236 return excout.getvalue()
237
Tim Peters8485b562004-08-04 18:46:34 +0000238# Override some StringIO methods.
239class _SpoofOut(StringIO):
240 def getvalue(self):
241 result = StringIO.getvalue(self)
242 # If anything at all was written, make sure there's a trailing
243 # newline. There's no way for the expected output to indicate
244 # that a trailing newline is missing.
245 if result and not result.endswith("\n"):
246 result += "\n"
Tim Peters8485b562004-08-04 18:46:34 +0000247 return result
Tim Peters8a7d2d52001-01-16 07:10:57 +0000248
Guido van Rossum79139b22007-02-09 23:20:19 +0000249 def truncate(self, size=None):
Tim Peters8485b562004-08-04 18:46:34 +0000250 StringIO.truncate(self, size)
Tim Peters8a7d2d52001-01-16 07:10:57 +0000251
Tim Peters26b3ebb2004-08-19 08:10:08 +0000252# Worst-case linear-time ellipsis matching.
Tim Petersb0a04e12004-08-20 02:08:04 +0000253def _ellipsis_match(want, got):
Tim Petersdc5de3b2004-08-19 14:06:20 +0000254 """
255 Essentially the only subtle case:
Tim Petersb0a04e12004-08-20 02:08:04 +0000256 >>> _ellipsis_match('aa...aa', 'aaa')
Tim Petersdc5de3b2004-08-19 14:06:20 +0000257 False
258 """
Tim Peters26b3ebb2004-08-19 08:10:08 +0000259 if ELLIPSIS_MARKER not in want:
260 return want == got
Tim Petersdc5de3b2004-08-19 14:06:20 +0000261
Tim Peters26b3ebb2004-08-19 08:10:08 +0000262 # Find "the real" strings.
263 ws = want.split(ELLIPSIS_MARKER)
264 assert len(ws) >= 2
Tim Peters26b3ebb2004-08-19 08:10:08 +0000265
Tim Petersdc5de3b2004-08-19 14:06:20 +0000266 # Deal with exact matches possibly needed at one or both ends.
267 startpos, endpos = 0, len(got)
268 w = ws[0]
269 if w: # starts with exact match
270 if got.startswith(w):
271 startpos = len(w)
272 del ws[0]
273 else:
274 return False
275 w = ws[-1]
276 if w: # ends with exact match
277 if got.endswith(w):
278 endpos -= len(w)
279 del ws[-1]
280 else:
281 return False
282
283 if startpos > endpos:
284 # Exact end matches required more characters than we have, as in
Tim Petersb0a04e12004-08-20 02:08:04 +0000285 # _ellipsis_match('aa...aa', 'aaa')
Tim Petersdc5de3b2004-08-19 14:06:20 +0000286 return False
287
288 # For the rest, we only need to find the leftmost non-overlapping
289 # match for each piece. If there's no overall match that way alone,
290 # there's no overall match period.
Tim Peters26b3ebb2004-08-19 08:10:08 +0000291 for w in ws:
292 # w may be '' at times, if there are consecutive ellipses, or
293 # due to an ellipsis at the start or end of `want`. That's OK.
Tim Petersdc5de3b2004-08-19 14:06:20 +0000294 # Search for an empty string succeeds, and doesn't change startpos.
295 startpos = got.find(w, startpos, endpos)
296 if startpos < 0:
Tim Peters26b3ebb2004-08-19 08:10:08 +0000297 return False
Tim Petersdc5de3b2004-08-19 14:06:20 +0000298 startpos += len(w)
Tim Peters26b3ebb2004-08-19 08:10:08 +0000299
Tim Petersdc5de3b2004-08-19 14:06:20 +0000300 return True
Tim Peters26b3ebb2004-08-19 08:10:08 +0000301
Edward Loper00f8da72004-08-26 18:05:07 +0000302def _comment_line(line):
303 "Return a commented form of the given line"
304 line = line.rstrip()
305 if line:
306 return '# '+line
307 else:
308 return '#'
309
Edward Loper2de91ba2004-08-27 02:07:46 +0000310class _OutputRedirectingPdb(pdb.Pdb):
311 """
312 A specialized version of the python debugger that redirects stdout
313 to a given stream when interacting with the user. Stdout is *not*
314 redirected when traced code is executed.
315 """
316 def __init__(self, out):
317 self.__out = out
Guido van Rossum0d3fb8a2007-11-26 23:23:18 +0000318 self.__debugger_used = False
Thomas Wouters477c8d52006-05-27 19:21:47 +0000319 pdb.Pdb.__init__(self, stdout=out)
Edward Loper2de91ba2004-08-27 02:07:46 +0000320
Guido van Rossum0d3fb8a2007-11-26 23:23:18 +0000321 def set_trace(self, frame=None):
322 self.__debugger_used = True
323 if frame is None:
324 frame = sys._getframe().f_back
325 pdb.Pdb.set_trace(self, frame)
326
327 def set_continue(self):
328 # Calling set_continue unconditionally would break unit test
329 # coverage reporting, as Bdb.set_continue calls sys.settrace(None).
330 if self.__debugger_used:
331 pdb.Pdb.set_continue(self)
332
Edward Loper2de91ba2004-08-27 02:07:46 +0000333 def trace_dispatch(self, *args):
334 # Redirect stdout to the given stream.
335 save_stdout = sys.stdout
336 sys.stdout = self.__out
337 # Call Pdb's trace dispatch method.
Tim Petersd7bbbbc2004-11-08 22:30:28 +0000338 try:
339 return pdb.Pdb.trace_dispatch(self, *args)
340 finally:
Tim Petersd7bbbbc2004-11-08 22:30:28 +0000341 sys.stdout = save_stdout
Edward Loper2de91ba2004-08-27 02:07:46 +0000342
Edward Lopera2fc7ec2004-09-21 03:24:24 +0000343# [XX] Normalize with respect to os.path.pardir?
Edward Loper052d0cd2004-09-19 17:19:33 +0000344def _module_relative_path(module, path):
345 if not inspect.ismodule(module):
Collin Winterce36ad82007-08-30 01:19:48 +0000346 raise TypeError('Expected a module: %r' % module)
Edward Loper052d0cd2004-09-19 17:19:33 +0000347 if path.startswith('/'):
Collin Winterce36ad82007-08-30 01:19:48 +0000348 raise ValueError('Module-relative files may not have absolute paths')
Edward Loper052d0cd2004-09-19 17:19:33 +0000349
350 # Find the base directory for the path.
351 if hasattr(module, '__file__'):
352 # A normal module/package
353 basedir = os.path.split(module.__file__)[0]
354 elif module.__name__ == '__main__':
355 # An interactive session.
356 if len(sys.argv)>0 and sys.argv[0] != '':
357 basedir = os.path.split(sys.argv[0])[0]
358 else:
359 basedir = os.curdir
360 else:
361 # A module w/o __file__ (this includes builtins)
362 raise ValueError("Can't resolve paths relative to the module " +
363 module + " (it has no __file__)")
364
365 # Combine the base directory and the path.
366 return os.path.join(basedir, *(path.split('/')))
367
Tim Peters8485b562004-08-04 18:46:34 +0000368######################################################################
369## 2. Example & DocTest
370######################################################################
371## - An "example" is a <source, want> pair, where "source" is a
372## fragment of source code, and "want" is the expected output for
373## "source." The Example class also includes information about
374## where the example was extracted from.
375##
Edward Lopera1ef6112004-08-09 16:14:41 +0000376## - A "doctest" is a collection of examples, typically extracted from
377## a string (such as an object's docstring). The DocTest class also
378## includes information about where the string was extracted from.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000379
Tim Peters8485b562004-08-04 18:46:34 +0000380class Example:
381 """
382 A single doctest example, consisting of source code and expected
Edward Lopera1ef6112004-08-09 16:14:41 +0000383 output. `Example` defines the following attributes:
Tim Peters8a7d2d52001-01-16 07:10:57 +0000384
Edward Loper74bca7a2004-08-12 02:27:44 +0000385 - source: A single Python statement, always ending with a newline.
Tim Petersbb431472004-08-09 03:51:46 +0000386 The constructor adds a newline if needed.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000387
Edward Loper74bca7a2004-08-12 02:27:44 +0000388 - want: The expected output from running the source code (either
Tim Petersbb431472004-08-09 03:51:46 +0000389 from stdout, or a traceback in case of exception). `want` ends
390 with a newline unless it's empty, in which case it's an empty
391 string. The constructor adds a newline if needed.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000392
Edward Lopera6b68322004-08-26 00:05:43 +0000393 - exc_msg: The exception message generated by the example, if
394 the example is expected to generate an exception; or `None` if
395 it is not expected to generate an exception. This exception
396 message is compared against the return value of
397 `traceback.format_exception_only()`. `exc_msg` ends with a
398 newline unless it's `None`. The constructor adds a newline
399 if needed.
400
Edward Loper74bca7a2004-08-12 02:27:44 +0000401 - lineno: The line number within the DocTest string containing
Tim Peters8485b562004-08-04 18:46:34 +0000402 this Example where the Example begins. This line number is
403 zero-based, with respect to the beginning of the DocTest.
Edward Loper74bca7a2004-08-12 02:27:44 +0000404
405 - indent: The example's indentation in the DocTest string.
406 I.e., the number of space characters that preceed the
407 example's first prompt.
408
409 - options: A dictionary mapping from option flags to True or
410 False, which is used to override default options for this
411 example. Any option flags not contained in this dictionary
412 are left at their default value (as specified by the
413 DocTestRunner's optionflags). By default, no options are set.
Tim Peters8485b562004-08-04 18:46:34 +0000414 """
Edward Lopera6b68322004-08-26 00:05:43 +0000415 def __init__(self, source, want, exc_msg=None, lineno=0, indent=0,
416 options=None):
Tim Petersbb431472004-08-09 03:51:46 +0000417 # Normalize inputs.
418 if not source.endswith('\n'):
419 source += '\n'
420 if want and not want.endswith('\n'):
421 want += '\n'
Edward Lopera6b68322004-08-26 00:05:43 +0000422 if exc_msg is not None and not exc_msg.endswith('\n'):
423 exc_msg += '\n'
Tim Peters8485b562004-08-04 18:46:34 +0000424 # Store properties.
425 self.source = source
426 self.want = want
427 self.lineno = lineno
Edward Loper74bca7a2004-08-12 02:27:44 +0000428 self.indent = indent
429 if options is None: options = {}
430 self.options = options
Edward Lopera6b68322004-08-26 00:05:43 +0000431 self.exc_msg = exc_msg
Tim Peters8a7d2d52001-01-16 07:10:57 +0000432
Tim Peters8485b562004-08-04 18:46:34 +0000433class DocTest:
434 """
435 A collection of doctest examples that should be run in a single
Edward Lopera1ef6112004-08-09 16:14:41 +0000436 namespace. Each `DocTest` defines the following attributes:
Tim Peters8a7d2d52001-01-16 07:10:57 +0000437
Tim Peters8485b562004-08-04 18:46:34 +0000438 - examples: the list of examples.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000439
Tim Peters8485b562004-08-04 18:46:34 +0000440 - globs: The namespace (aka globals) that the examples should
441 be run in.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000442
Tim Peters8485b562004-08-04 18:46:34 +0000443 - name: A name identifying the DocTest (typically, the name of
444 the object whose docstring this DocTest was extracted from).
Tim Peters8a7d2d52001-01-16 07:10:57 +0000445
Tim Peters8485b562004-08-04 18:46:34 +0000446 - filename: The name of the file that this DocTest was extracted
Edward Lopera1ef6112004-08-09 16:14:41 +0000447 from, or `None` if the filename is unknown.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000448
Tim Peters8485b562004-08-04 18:46:34 +0000449 - lineno: The line number within filename where this DocTest
Edward Lopera1ef6112004-08-09 16:14:41 +0000450 begins, or `None` if the line number is unavailable. This
451 line number is zero-based, with respect to the beginning of
452 the file.
453
454 - docstring: The string that the examples were extracted from,
455 or `None` if the string is unavailable.
Tim Peters8485b562004-08-04 18:46:34 +0000456 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000457 def __init__(self, examples, globs, name, filename, lineno, docstring):
Tim Peters8485b562004-08-04 18:46:34 +0000458 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000459 Create a new DocTest containing the given examples. The
460 DocTest's globals are initialized with a copy of `globs`.
Tim Peters8485b562004-08-04 18:46:34 +0000461 """
Guido van Rossum3172c5d2007-10-16 18:12:55 +0000462 assert not isinstance(examples, str), \
Edward Lopera1ef6112004-08-09 16:14:41 +0000463 "DocTest no longer accepts str; use DocTestParser instead"
464 self.examples = examples
465 self.docstring = docstring
Tim Peters8485b562004-08-04 18:46:34 +0000466 self.globs = globs.copy()
Tim Peters8485b562004-08-04 18:46:34 +0000467 self.name = name
468 self.filename = filename
469 self.lineno = lineno
Tim Peters8485b562004-08-04 18:46:34 +0000470
471 def __repr__(self):
472 if len(self.examples) == 0:
473 examples = 'no examples'
474 elif len(self.examples) == 1:
475 examples = '1 example'
476 else:
477 examples = '%d examples' % len(self.examples)
478 return ('<DocTest %s from %s:%s (%s)>' %
479 (self.name, self.filename, self.lineno, examples))
480
481
482 # This lets us sort tests by name:
Guido van Rossum47b9ff62006-08-24 00:41:19 +0000483 def __lt__(self, other):
Tim Peters8485b562004-08-04 18:46:34 +0000484 if not isinstance(other, DocTest):
Guido van Rossum47b9ff62006-08-24 00:41:19 +0000485 return NotImplemented
486 return ((self.name, self.filename, self.lineno, id(self))
487 <
488 (other.name, other.filename, other.lineno, id(other)))
Tim Peters8485b562004-08-04 18:46:34 +0000489
490######################################################################
Edward Loperb7503ff2004-08-19 19:19:03 +0000491## 3. DocTestParser
Edward Loper7c748462004-08-09 02:06:06 +0000492######################################################################
493
Edward Lopera1ef6112004-08-09 16:14:41 +0000494class DocTestParser:
Edward Loper7c748462004-08-09 02:06:06 +0000495 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000496 A class used to parse strings containing doctest examples.
Edward Loper7c748462004-08-09 02:06:06 +0000497 """
Edward Loper8e4a34b2004-08-12 02:34:27 +0000498 # This regular expression is used to find doctest examples in a
499 # string. It defines three groups: `source` is the source code
500 # (including leading indentation and prompts); `indent` is the
501 # indentation of the first (PS1) line of the source code; and
502 # `want` is the expected output (including leading indentation).
Edward Loper7c748462004-08-09 02:06:06 +0000503 _EXAMPLE_RE = re.compile(r'''
Tim Petersd40a92b2004-08-09 03:28:45 +0000504 # Source consists of a PS1 line followed by zero or more PS2 lines.
505 (?P<source>
506 (?:^(?P<indent> [ ]*) >>> .*) # PS1 line
507 (?:\n [ ]* \.\.\. .*)*) # PS2 lines
508 \n?
509 # Want consists of any non-blank lines that do not start with PS1.
510 (?P<want> (?:(?![ ]*$) # Not a blank line
511 (?![ ]*>>>) # Not a line starting with PS1
512 .*$\n? # But any other line
513 )*)
514 ''', re.MULTILINE | re.VERBOSE)
Edward Loper8e4a34b2004-08-12 02:34:27 +0000515
Edward Lopera6b68322004-08-26 00:05:43 +0000516 # A regular expression for handling `want` strings that contain
517 # expected exceptions. It divides `want` into three pieces:
518 # - the traceback header line (`hdr`)
519 # - the traceback stack (`stack`)
520 # - the exception message (`msg`), as generated by
521 # traceback.format_exception_only()
522 # `msg` may have multiple lines. We assume/require that the
523 # exception message is the first non-indented line starting with a word
524 # character following the traceback header line.
525 _EXCEPTION_RE = re.compile(r"""
526 # Grab the traceback header. Different versions of Python have
527 # said different things on the first traceback line.
528 ^(?P<hdr> Traceback\ \(
529 (?: most\ recent\ call\ last
530 | innermost\ last
531 ) \) :
532 )
533 \s* $ # toss trailing whitespace on the header.
534 (?P<stack> .*?) # don't blink: absorb stuff until...
535 ^ (?P<msg> \w+ .*) # a line *starts* with alphanum.
536 """, re.VERBOSE | re.MULTILINE | re.DOTALL)
537
Tim Peters7ea48dd2004-08-13 01:52:59 +0000538 # A callable returning a true value iff its argument is a blank line
539 # or contains a single comment.
Edward Loper8e4a34b2004-08-12 02:34:27 +0000540 _IS_BLANK_OR_COMMENT = re.compile(r'^[ ]*(#.*)?$').match
Edward Loper7c748462004-08-09 02:06:06 +0000541
Edward Loper00f8da72004-08-26 18:05:07 +0000542 def parse(self, string, name='<string>'):
543 """
544 Divide the given string into examples and intervening text,
545 and return them as a list of alternating Examples and strings.
546 Line numbers for the Examples are 0-based. The optional
547 argument `name` is a name identifying this string, and is only
548 used for error messages.
549 """
550 string = string.expandtabs()
551 # If all lines begin with the same indentation, then strip it.
552 min_indent = self._min_indent(string)
553 if min_indent > 0:
554 string = '\n'.join([l[min_indent:] for l in string.split('\n')])
555
556 output = []
557 charno, lineno = 0, 0
558 # Find all doctest examples in the string:
Edward Loper2de91ba2004-08-27 02:07:46 +0000559 for m in self._EXAMPLE_RE.finditer(string):
Edward Loper00f8da72004-08-26 18:05:07 +0000560 # Add the pre-example text to `output`.
561 output.append(string[charno:m.start()])
562 # Update lineno (lines before this example)
563 lineno += string.count('\n', charno, m.start())
564 # Extract info from the regexp match.
565 (source, options, want, exc_msg) = \
566 self._parse_example(m, name, lineno)
567 # Create an Example, and add it to the list.
568 if not self._IS_BLANK_OR_COMMENT(source):
569 output.append( Example(source, want, exc_msg,
570 lineno=lineno,
571 indent=min_indent+len(m.group('indent')),
572 options=options) )
573 # Update lineno (lines inside this example)
574 lineno += string.count('\n', m.start(), m.end())
575 # Update charno.
576 charno = m.end()
577 # Add any remaining post-example text to `output`.
578 output.append(string[charno:])
579 return output
580
Edward Lopera1ef6112004-08-09 16:14:41 +0000581 def get_doctest(self, string, globs, name, filename, lineno):
Edward Loper7c748462004-08-09 02:06:06 +0000582 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000583 Extract all doctest examples from the given string, and
584 collect them into a `DocTest` object.
585
586 `globs`, `name`, `filename`, and `lineno` are attributes for
587 the new `DocTest` object. See the documentation for `DocTest`
588 for more information.
589 """
590 return DocTest(self.get_examples(string, name), globs,
591 name, filename, lineno, string)
592
593 def get_examples(self, string, name='<string>'):
594 """
595 Extract all doctest examples from the given string, and return
596 them as a list of `Example` objects. Line numbers are
597 0-based, because it's most common in doctests that nothing
598 interesting appears on the same line as opening triple-quote,
599 and so the first interesting line is called \"line 1\" then.
600
601 The optional argument `name` is a name identifying this
602 string, and is only used for error messages.
Edward Loper7c748462004-08-09 02:06:06 +0000603 """
Edward Loper00f8da72004-08-26 18:05:07 +0000604 return [x for x in self.parse(string, name)
605 if isinstance(x, Example)]
Edward Loper7c748462004-08-09 02:06:06 +0000606
Edward Loper74bca7a2004-08-12 02:27:44 +0000607 def _parse_example(self, m, name, lineno):
608 """
609 Given a regular expression match from `_EXAMPLE_RE` (`m`),
610 return a pair `(source, want)`, where `source` is the matched
611 example's source code (with prompts and indentation stripped);
612 and `want` is the example's expected output (with indentation
613 stripped).
614
615 `name` is the string's name, and `lineno` is the line number
616 where the example starts; both are used for error messages.
617 """
Edward Loper7c748462004-08-09 02:06:06 +0000618 # Get the example's indentation level.
619 indent = len(m.group('indent'))
620
621 # Divide source into lines; check that they're properly
622 # indented; and then strip their indentation & prompts.
623 source_lines = m.group('source').split('\n')
Edward Lopera1ef6112004-08-09 16:14:41 +0000624 self._check_prompt_blank(source_lines, indent, name, lineno)
Tim Petersc5049152004-08-22 17:34:58 +0000625 self._check_prefix(source_lines[1:], ' '*indent + '.', name, lineno)
Edward Loper7c748462004-08-09 02:06:06 +0000626 source = '\n'.join([sl[indent+4:] for sl in source_lines])
Edward Loper7c748462004-08-09 02:06:06 +0000627
Tim Petersc5049152004-08-22 17:34:58 +0000628 # Divide want into lines; check that it's properly indented; and
629 # then strip the indentation. Spaces before the last newline should
630 # be preserved, so plain rstrip() isn't good enough.
Jim Fulton07a349c2004-08-22 14:10:00 +0000631 want = m.group('want')
Jim Fulton07a349c2004-08-22 14:10:00 +0000632 want_lines = want.split('\n')
Tim Petersc5049152004-08-22 17:34:58 +0000633 if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]):
634 del want_lines[-1] # forget final newline & spaces after it
Edward Lopera1ef6112004-08-09 16:14:41 +0000635 self._check_prefix(want_lines, ' '*indent, name,
Tim Petersc5049152004-08-22 17:34:58 +0000636 lineno + len(source_lines))
Edward Loper7c748462004-08-09 02:06:06 +0000637 want = '\n'.join([wl[indent:] for wl in want_lines])
Edward Loper7c748462004-08-09 02:06:06 +0000638
Edward Lopera6b68322004-08-26 00:05:43 +0000639 # If `want` contains a traceback message, then extract it.
640 m = self._EXCEPTION_RE.match(want)
641 if m:
642 exc_msg = m.group('msg')
643 else:
644 exc_msg = None
645
Edward Loper00f8da72004-08-26 18:05:07 +0000646 # Extract options from the source.
647 options = self._find_options(source, name, lineno)
648
649 return source, options, want, exc_msg
Edward Loper7c748462004-08-09 02:06:06 +0000650
Edward Loper74bca7a2004-08-12 02:27:44 +0000651 # This regular expression looks for option directives in the
652 # source code of an example. Option directives are comments
653 # starting with "doctest:". Warning: this may give false
654 # positives for string-literals that contain the string
655 # "#doctest:". Eliminating these false positives would require
656 # actually parsing the string; but we limit them by ignoring any
657 # line containing "#doctest:" that is *followed* by a quote mark.
658 _OPTION_DIRECTIVE_RE = re.compile(r'#\s*doctest:\s*([^\n\'"]*)$',
659 re.MULTILINE)
660
661 def _find_options(self, source, name, lineno):
662 """
663 Return a dictionary containing option overrides extracted from
664 option directives in the given source string.
665
666 `name` is the string's name, and `lineno` is the line number
667 where the example starts; both are used for error messages.
668 """
669 options = {}
670 # (note: with the current regexp, this will match at most once:)
671 for m in self._OPTION_DIRECTIVE_RE.finditer(source):
672 option_strings = m.group(1).replace(',', ' ').split()
673 for option in option_strings:
674 if (option[0] not in '+-' or
675 option[1:] not in OPTIONFLAGS_BY_NAME):
676 raise ValueError('line %r of the doctest for %s '
677 'has an invalid option: %r' %
678 (lineno+1, name, option))
679 flag = OPTIONFLAGS_BY_NAME[option[1:]]
680 options[flag] = (option[0] == '+')
681 if options and self._IS_BLANK_OR_COMMENT(source):
682 raise ValueError('line %r of the doctest for %s has an option '
683 'directive on a line with no example: %r' %
684 (lineno, name, source))
685 return options
686
Edward Lopera5db6002004-08-12 02:41:30 +0000687 # This regular expression finds the indentation of every non-blank
688 # line in a string.
Edward Loper00f8da72004-08-26 18:05:07 +0000689 _INDENT_RE = re.compile('^([ ]*)(?=\S)', re.MULTILINE)
Edward Lopera5db6002004-08-12 02:41:30 +0000690
691 def _min_indent(self, s):
692 "Return the minimum indentation of any non-blank line in `s`"
Edward Loper00f8da72004-08-26 18:05:07 +0000693 indents = [len(indent) for indent in self._INDENT_RE.findall(s)]
694 if len(indents) > 0:
695 return min(indents)
Tim Petersdd0e4752004-08-09 03:31:56 +0000696 else:
Edward Loper00f8da72004-08-26 18:05:07 +0000697 return 0
Edward Loper7c748462004-08-09 02:06:06 +0000698
Edward Lopera1ef6112004-08-09 16:14:41 +0000699 def _check_prompt_blank(self, lines, indent, name, lineno):
Edward Loper74bca7a2004-08-12 02:27:44 +0000700 """
701 Given the lines of a source string (including prompts and
702 leading indentation), check to make sure that every prompt is
703 followed by a space character. If any line is not followed by
704 a space character, then raise ValueError.
705 """
Edward Loper7c748462004-08-09 02:06:06 +0000706 for i, line in enumerate(lines):
707 if len(line) >= indent+4 and line[indent+3] != ' ':
708 raise ValueError('line %r of the docstring for %s '
709 'lacks blank after %s: %r' %
Edward Lopera1ef6112004-08-09 16:14:41 +0000710 (lineno+i+1, name,
Edward Loper7c748462004-08-09 02:06:06 +0000711 line[indent:indent+3], line))
712
Edward Lopera1ef6112004-08-09 16:14:41 +0000713 def _check_prefix(self, lines, prefix, name, lineno):
Edward Loper74bca7a2004-08-12 02:27:44 +0000714 """
715 Check that every line in the given list starts with the given
716 prefix; if any line does not, then raise a ValueError.
717 """
Edward Loper7c748462004-08-09 02:06:06 +0000718 for i, line in enumerate(lines):
719 if line and not line.startswith(prefix):
720 raise ValueError('line %r of the docstring for %s has '
721 'inconsistent leading whitespace: %r' %
Edward Lopera1ef6112004-08-09 16:14:41 +0000722 (lineno+i+1, name, line))
Edward Loper7c748462004-08-09 02:06:06 +0000723
724
725######################################################################
726## 4. DocTest Finder
Tim Peters8485b562004-08-04 18:46:34 +0000727######################################################################
728
729class DocTestFinder:
730 """
731 A class used to extract the DocTests that are relevant to a given
732 object, from its docstring and the docstrings of its contained
733 objects. Doctests can currently be extracted from the following
734 object types: modules, functions, classes, methods, staticmethods,
735 classmethods, and properties.
Tim Peters8485b562004-08-04 18:46:34 +0000736 """
737
Edward Lopera1ef6112004-08-09 16:14:41 +0000738 def __init__(self, verbose=False, parser=DocTestParser(),
Thomas Wouters73e5a5b2006-06-08 15:35:45 +0000739 recurse=True, exclude_empty=True):
Tim Peters8485b562004-08-04 18:46:34 +0000740 """
741 Create a new doctest finder.
742
Edward Lopera1ef6112004-08-09 16:14:41 +0000743 The optional argument `parser` specifies a class or
Tim Peters19397e52004-08-06 22:02:59 +0000744 function that should be used to create new DocTest objects (or
Tim Peters161c9632004-08-08 03:38:33 +0000745 objects that implement the same interface as DocTest). The
Tim Peters19397e52004-08-06 22:02:59 +0000746 signature for this factory function should match the signature
747 of the DocTest constructor.
748
Tim Peters8485b562004-08-04 18:46:34 +0000749 If the optional argument `recurse` is false, then `find` will
750 only examine the given object, and not any contained objects.
Edward Loper32ddbf72004-09-13 05:47:24 +0000751
Tim Peters958cc892004-09-13 14:53:28 +0000752 If the optional argument `exclude_empty` is false, then `find`
753 will include tests for objects with empty docstrings.
Tim Peters8485b562004-08-04 18:46:34 +0000754 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000755 self._parser = parser
Tim Peters8485b562004-08-04 18:46:34 +0000756 self._verbose = verbose
Tim Peters8485b562004-08-04 18:46:34 +0000757 self._recurse = recurse
Edward Loper32ddbf72004-09-13 05:47:24 +0000758 self._exclude_empty = exclude_empty
Tim Peters8485b562004-08-04 18:46:34 +0000759
Thomas Wouters73e5a5b2006-06-08 15:35:45 +0000760 def find(self, obj, name=None, module=None, globs=None, extraglobs=None):
Tim Peters8485b562004-08-04 18:46:34 +0000761 """
762 Return a list of the DocTests that are defined by the given
763 object's docstring, or by any of its contained objects'
764 docstrings.
765
766 The optional parameter `module` is the module that contains
Tim Petersf3f57472004-08-08 06:11:48 +0000767 the given object. If the module is not specified or is None, then
768 the test finder will attempt to automatically determine the
Tim Peters8485b562004-08-04 18:46:34 +0000769 correct module. The object's module is used:
770
771 - As a default namespace, if `globs` is not specified.
772 - To prevent the DocTestFinder from extracting DocTests
Tim Petersf3f57472004-08-08 06:11:48 +0000773 from objects that are imported from other modules.
Tim Peters8485b562004-08-04 18:46:34 +0000774 - To find the name of the file containing the object.
775 - To help find the line number of the object within its
776 file.
777
Tim Petersf3f57472004-08-08 06:11:48 +0000778 Contained objects whose module does not match `module` are ignored.
779
780 If `module` is False, no attempt to find the module will be made.
781 This is obscure, of use mostly in tests: if `module` is False, or
782 is None but cannot be found automatically, then all objects are
783 considered to belong to the (non-existent) module, so all contained
784 objects will (recursively) be searched for doctests.
785
Tim Peters8485b562004-08-04 18:46:34 +0000786 The globals for each DocTest is formed by combining `globs`
787 and `extraglobs` (bindings in `extraglobs` override bindings
788 in `globs`). A new copy of the globals dictionary is created
789 for each DocTest. If `globs` is not specified, then it
790 defaults to the module's `__dict__`, if specified, or {}
791 otherwise. If `extraglobs` is not specified, then it defaults
792 to {}.
793
Tim Peters8485b562004-08-04 18:46:34 +0000794 """
795 # If name was not specified, then extract it from the object.
796 if name is None:
797 name = getattr(obj, '__name__', None)
798 if name is None:
799 raise ValueError("DocTestFinder.find: name must be given "
800 "when obj.__name__ doesn't exist: %r" %
801 (type(obj),))
802
803 # Find the module that contains the given object (if obj is
804 # a module, then module=obj.). Note: this may fail, in which
805 # case module will be None.
Tim Petersf3f57472004-08-08 06:11:48 +0000806 if module is False:
807 module = None
808 elif module is None:
Tim Peters8485b562004-08-04 18:46:34 +0000809 module = inspect.getmodule(obj)
810
811 # Read the module's source code. This is used by
812 # DocTestFinder._find_lineno to find the line number for a
813 # given object's docstring.
814 try:
815 file = inspect.getsourcefile(obj) or inspect.getfile(obj)
816 source_lines = linecache.getlines(file)
817 if not source_lines:
818 source_lines = None
819 except TypeError:
820 source_lines = None
821
822 # Initialize globals, and merge in extraglobs.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000823 if globs is None:
Tim Peters8485b562004-08-04 18:46:34 +0000824 if module is None:
825 globs = {}
826 else:
827 globs = module.__dict__.copy()
828 else:
829 globs = globs.copy()
830 if extraglobs is not None:
831 globs.update(extraglobs)
Tim Peters8a7d2d52001-01-16 07:10:57 +0000832
Tim Peters8485b562004-08-04 18:46:34 +0000833 # Recursively expore `obj`, extracting DocTests.
834 tests = []
Tim Petersf3f57472004-08-08 06:11:48 +0000835 self._find(tests, obj, name, module, source_lines, globs, {})
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000836 # Sort the tests by alpha order of names, for consistency in
837 # verbose-mode output. This was a feature of doctest in Pythons
838 # <= 2.3 that got lost by accident in 2.4. It was repaired in
839 # 2.4.4 and 2.5.
840 tests.sort()
Tim Peters8485b562004-08-04 18:46:34 +0000841 return tests
842
Tim Peters8485b562004-08-04 18:46:34 +0000843 def _from_module(self, module, object):
844 """
845 Return true if the given object is defined in the given
846 module.
847 """
848 if module is None:
849 return True
Benjamin Peterson6cadba72008-11-19 22:38:29 +0000850 elif inspect.getmodule(object) is not None:
851 return module is inspect.getmodule(object)
Tim Peters8485b562004-08-04 18:46:34 +0000852 elif inspect.isfunction(object):
Neal Norwitz221085d2007-02-25 20:55:47 +0000853 return module.__dict__ is object.__globals__
Tim Peters8485b562004-08-04 18:46:34 +0000854 elif inspect.isclass(object):
855 return module.__name__ == object.__module__
Tim Peters8485b562004-08-04 18:46:34 +0000856 elif hasattr(object, '__module__'):
857 return module.__name__ == object.__module__
858 elif isinstance(object, property):
859 return True # [XX] no way not be sure.
860 else:
861 raise ValueError("object must be a class or function")
862
Tim Petersf3f57472004-08-08 06:11:48 +0000863 def _find(self, tests, obj, name, module, source_lines, globs, seen):
Tim Peters8485b562004-08-04 18:46:34 +0000864 """
865 Find tests for the given object and any contained objects, and
866 add them to `tests`.
867 """
868 if self._verbose:
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000869 print('Finding tests in %s' % name)
Tim Peters8485b562004-08-04 18:46:34 +0000870
871 # If we've already processed this object, then ignore it.
872 if id(obj) in seen:
873 return
874 seen[id(obj)] = 1
875
876 # Find a test for this object, and add it to the list of tests.
877 test = self._get_test(obj, name, module, globs, source_lines)
878 if test is not None:
879 tests.append(test)
880
881 # Look for tests in a module's contained objects.
882 if inspect.ismodule(obj) and self._recurse:
883 for valname, val in obj.__dict__.items():
Tim Peters8485b562004-08-04 18:46:34 +0000884 valname = '%s.%s' % (name, valname)
885 # Recurse to functions & classes.
886 if ((inspect.isfunction(val) or inspect.isclass(val)) and
Tim Petersf3f57472004-08-08 06:11:48 +0000887 self._from_module(module, val)):
Tim Peters8485b562004-08-04 18:46:34 +0000888 self._find(tests, val, valname, module, source_lines,
Tim Petersf3f57472004-08-08 06:11:48 +0000889 globs, seen)
Tim Peters8485b562004-08-04 18:46:34 +0000890
891 # Look for tests in a module's __test__ dictionary.
892 if inspect.ismodule(obj) and self._recurse:
893 for valname, val in getattr(obj, '__test__', {}).items():
Guido van Rossum3172c5d2007-10-16 18:12:55 +0000894 if not isinstance(valname, str):
Tim Peters8485b562004-08-04 18:46:34 +0000895 raise ValueError("DocTestFinder.find: __test__ keys "
896 "must be strings: %r" %
897 (type(valname),))
898 if not (inspect.isfunction(val) or inspect.isclass(val) or
899 inspect.ismethod(val) or inspect.ismodule(val) or
Guido van Rossum3172c5d2007-10-16 18:12:55 +0000900 isinstance(val, str)):
Tim Peters8485b562004-08-04 18:46:34 +0000901 raise ValueError("DocTestFinder.find: __test__ values "
902 "must be strings, functions, methods, "
903 "classes, or modules: %r" %
904 (type(val),))
Tim Petersc5684782004-09-13 01:07:12 +0000905 valname = '%s.__test__.%s' % (name, valname)
Tim Peters8485b562004-08-04 18:46:34 +0000906 self._find(tests, val, valname, module, source_lines,
Tim Petersf3f57472004-08-08 06:11:48 +0000907 globs, seen)
Tim Peters8485b562004-08-04 18:46:34 +0000908
909 # Look for tests in a class's contained objects.
910 if inspect.isclass(obj) and self._recurse:
911 for valname, val in obj.__dict__.items():
Tim Peters8485b562004-08-04 18:46:34 +0000912 # Special handling for staticmethod/classmethod.
913 if isinstance(val, staticmethod):
914 val = getattr(obj, valname)
915 if isinstance(val, classmethod):
Christian Heimesff737952007-11-27 10:40:20 +0000916 val = getattr(obj, valname).__func__
Tim Peters8485b562004-08-04 18:46:34 +0000917
918 # Recurse to methods, properties, and nested classes.
919 if ((inspect.isfunction(val) or inspect.isclass(val) or
Tim Petersf3f57472004-08-08 06:11:48 +0000920 isinstance(val, property)) and
921 self._from_module(module, val)):
Tim Peters8485b562004-08-04 18:46:34 +0000922 valname = '%s.%s' % (name, valname)
923 self._find(tests, val, valname, module, source_lines,
Tim Petersf3f57472004-08-08 06:11:48 +0000924 globs, seen)
Tim Peters8485b562004-08-04 18:46:34 +0000925
926 def _get_test(self, obj, name, module, globs, source_lines):
927 """
928 Return a DocTest for the given object, if it defines a docstring;
929 otherwise, return None.
930 """
931 # Extract the object's docstring. If it doesn't have one,
932 # then return None (no test for this object).
Guido van Rossum3172c5d2007-10-16 18:12:55 +0000933 if isinstance(obj, str):
Tim Peters8485b562004-08-04 18:46:34 +0000934 docstring = obj
935 else:
936 try:
937 if obj.__doc__ is None:
Edward Loper32ddbf72004-09-13 05:47:24 +0000938 docstring = ''
939 else:
Jim Fulton7d428782004-10-13 14:15:32 +0000940 docstring = obj.__doc__
Guido van Rossum3172c5d2007-10-16 18:12:55 +0000941 if not isinstance(docstring, str):
Jim Fulton7d428782004-10-13 14:15:32 +0000942 docstring = str(docstring)
Tim Peters8485b562004-08-04 18:46:34 +0000943 except (TypeError, AttributeError):
Edward Loper32ddbf72004-09-13 05:47:24 +0000944 docstring = ''
Tim Peters8485b562004-08-04 18:46:34 +0000945
946 # Find the docstring's location in the file.
947 lineno = self._find_lineno(obj, source_lines)
948
Edward Loper32ddbf72004-09-13 05:47:24 +0000949 # Don't bother if the docstring is empty.
950 if self._exclude_empty and not docstring:
951 return None
952
Tim Peters8485b562004-08-04 18:46:34 +0000953 # Return a DocTest for this object.
954 if module is None:
955 filename = None
956 else:
957 filename = getattr(module, '__file__', module.__name__)
Jim Fulton07a349c2004-08-22 14:10:00 +0000958 if filename[-4:] in (".pyc", ".pyo"):
959 filename = filename[:-1]
Edward Lopera1ef6112004-08-09 16:14:41 +0000960 return self._parser.get_doctest(docstring, globs, name,
961 filename, lineno)
Tim Peters8485b562004-08-04 18:46:34 +0000962
963 def _find_lineno(self, obj, source_lines):
964 """
965 Return a line number of the given object's docstring. Note:
966 this method assumes that the object has a docstring.
967 """
968 lineno = None
969
970 # Find the line number for modules.
971 if inspect.ismodule(obj):
972 lineno = 0
973
974 # Find the line number for classes.
975 # Note: this could be fooled if a class is defined multiple
976 # times in a single file.
977 if inspect.isclass(obj):
978 if source_lines is None:
979 return None
980 pat = re.compile(r'^\s*class\s*%s\b' %
981 getattr(obj, '__name__', '-'))
982 for i, line in enumerate(source_lines):
983 if pat.match(line):
984 lineno = i
985 break
986
987 # Find the line number for functions & methods.
Christian Heimesff737952007-11-27 10:40:20 +0000988 if inspect.ismethod(obj): obj = obj.__func__
Neal Norwitz221085d2007-02-25 20:55:47 +0000989 if inspect.isfunction(obj): obj = obj.__code__
Tim Peters8485b562004-08-04 18:46:34 +0000990 if inspect.istraceback(obj): obj = obj.tb_frame
991 if inspect.isframe(obj): obj = obj.f_code
992 if inspect.iscode(obj):
993 lineno = getattr(obj, 'co_firstlineno', None)-1
994
995 # Find the line number where the docstring starts. Assume
996 # that it's the first line that begins with a quote mark.
997 # Note: this could be fooled by a multiline function
998 # signature, where a continuation line begins with a quote
999 # mark.
1000 if lineno is not None:
1001 if source_lines is None:
1002 return lineno+1
1003 pat = re.compile('(^|.*:)\s*\w*("|\')')
1004 for lineno in range(lineno, len(source_lines)):
1005 if pat.match(source_lines[lineno]):
1006 return lineno
1007
1008 # We couldn't find the line number.
1009 return None
1010
1011######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00001012## 5. DocTest Runner
Tim Peters8485b562004-08-04 18:46:34 +00001013######################################################################
1014
Tim Peters8485b562004-08-04 18:46:34 +00001015class DocTestRunner:
1016 """
1017 A class used to run DocTest test cases, and accumulate statistics.
1018 The `run` method is used to process a single DocTest case. It
1019 returns a tuple `(f, t)`, where `t` is the number of test cases
1020 tried, and `f` is the number of test cases that failed.
1021
1022 >>> tests = DocTestFinder().find(_TestClass)
1023 >>> runner = DocTestRunner(verbose=False)
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00001024 >>> tests.sort(key = lambda test: test.name)
Tim Peters8485b562004-08-04 18:46:34 +00001025 >>> for test in tests:
Guido van Rossum7131f842007-02-09 20:13:25 +00001026 ... print(test.name, '->', runner.run(test))
Christian Heimes25bb7832008-01-11 16:17:00 +00001027 _TestClass -> TestResults(failed=0, attempted=2)
1028 _TestClass.__init__ -> TestResults(failed=0, attempted=2)
1029 _TestClass.get -> TestResults(failed=0, attempted=2)
1030 _TestClass.square -> TestResults(failed=0, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +00001031
1032 The `summarize` method prints a summary of all the test cases that
1033 have been run by the runner, and returns an aggregated `(f, t)`
1034 tuple:
1035
1036 >>> runner.summarize(verbose=1)
1037 4 items passed all tests:
1038 2 tests in _TestClass
1039 2 tests in _TestClass.__init__
1040 2 tests in _TestClass.get
1041 1 tests in _TestClass.square
1042 7 tests in 4 items.
1043 7 passed and 0 failed.
1044 Test passed.
Christian Heimes25bb7832008-01-11 16:17:00 +00001045 TestResults(failed=0, attempted=7)
Tim Peters8485b562004-08-04 18:46:34 +00001046
1047 The aggregated number of tried examples and failed examples is
1048 also available via the `tries` and `failures` attributes:
1049
1050 >>> runner.tries
1051 7
1052 >>> runner.failures
1053 0
1054
1055 The comparison between expected outputs and actual outputs is done
Edward Loper34fcb142004-08-09 02:45:41 +00001056 by an `OutputChecker`. This comparison may be customized with a
1057 number of option flags; see the documentation for `testmod` for
1058 more information. If the option flags are insufficient, then the
1059 comparison may also be customized by passing a subclass of
1060 `OutputChecker` to the constructor.
Tim Peters8485b562004-08-04 18:46:34 +00001061
1062 The test runner's display output can be controlled in two ways.
1063 First, an output function (`out) can be passed to
1064 `TestRunner.run`; this function will be called with strings that
1065 should be displayed. It defaults to `sys.stdout.write`. If
1066 capturing the output is not sufficient, then the display output
1067 can be also customized by subclassing DocTestRunner, and
1068 overriding the methods `report_start`, `report_success`,
1069 `report_unexpected_exception`, and `report_failure`.
1070 """
1071 # This divider string is used to separate failure messages, and to
1072 # separate sections of the summary.
1073 DIVIDER = "*" * 70
1074
Edward Loper34fcb142004-08-09 02:45:41 +00001075 def __init__(self, checker=None, verbose=None, optionflags=0):
Tim Peters8485b562004-08-04 18:46:34 +00001076 """
1077 Create a new test runner.
1078
Edward Loper34fcb142004-08-09 02:45:41 +00001079 Optional keyword arg `checker` is the `OutputChecker` that
1080 should be used to compare the expected outputs and actual
1081 outputs of doctest examples.
1082
Tim Peters8485b562004-08-04 18:46:34 +00001083 Optional keyword arg 'verbose' prints lots of stuff if true,
1084 only failures if false; by default, it's true iff '-v' is in
1085 sys.argv.
1086
1087 Optional argument `optionflags` can be used to control how the
1088 test runner compares expected output to actual output, and how
1089 it displays failures. See the documentation for `testmod` for
1090 more information.
1091 """
Edward Loper34fcb142004-08-09 02:45:41 +00001092 self._checker = checker or OutputChecker()
Tim Peters8a7d2d52001-01-16 07:10:57 +00001093 if verbose is None:
Tim Peters8485b562004-08-04 18:46:34 +00001094 verbose = '-v' in sys.argv
1095 self._verbose = verbose
Tim Peters6ebe61f2003-06-27 20:48:05 +00001096 self.optionflags = optionflags
Jim Fulton07a349c2004-08-22 14:10:00 +00001097 self.original_optionflags = optionflags
Tim Peters6ebe61f2003-06-27 20:48:05 +00001098
Tim Peters8485b562004-08-04 18:46:34 +00001099 # Keep track of the examples we've run.
1100 self.tries = 0
1101 self.failures = 0
1102 self._name2ft = {}
Tim Peters8a7d2d52001-01-16 07:10:57 +00001103
Tim Peters8485b562004-08-04 18:46:34 +00001104 # Create a fake output target for capturing doctest output.
1105 self._fakeout = _SpoofOut()
Tim Peters4fd9e2f2001-08-18 00:05:50 +00001106
Tim Peters8485b562004-08-04 18:46:34 +00001107 #/////////////////////////////////////////////////////////////////
Tim Peters8485b562004-08-04 18:46:34 +00001108 # Reporting methods
1109 #/////////////////////////////////////////////////////////////////
Tim Peters17111f32001-10-03 04:08:26 +00001110
Tim Peters8485b562004-08-04 18:46:34 +00001111 def report_start(self, out, test, example):
Tim Peters8a7d2d52001-01-16 07:10:57 +00001112 """
Tim Peters8485b562004-08-04 18:46:34 +00001113 Report that the test runner is about to process the given
1114 example. (Only displays a message if verbose=True)
1115 """
1116 if self._verbose:
Edward Loperaacf0832004-08-26 01:19:50 +00001117 if example.want:
1118 out('Trying:\n' + _indent(example.source) +
1119 'Expecting:\n' + _indent(example.want))
1120 else:
1121 out('Trying:\n' + _indent(example.source) +
1122 'Expecting nothing\n')
Tim Peters8a7d2d52001-01-16 07:10:57 +00001123
Tim Peters8485b562004-08-04 18:46:34 +00001124 def report_success(self, out, test, example, got):
1125 """
1126 Report that the given example ran successfully. (Only
1127 displays a message if verbose=True)
1128 """
1129 if self._verbose:
1130 out("ok\n")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001131
Tim Peters8485b562004-08-04 18:46:34 +00001132 def report_failure(self, out, test, example, got):
1133 """
1134 Report that the given example failed.
1135 """
Edward Loper8e4a34b2004-08-12 02:34:27 +00001136 out(self._failure_header(test, example) +
Edward Loperca9111e2004-08-26 03:00:24 +00001137 self._checker.output_difference(example, got, self.optionflags))
Tim Peters7402f792001-10-02 03:53:41 +00001138
Tim Peters8485b562004-08-04 18:46:34 +00001139 def report_unexpected_exception(self, out, test, example, exc_info):
1140 """
1141 Report that the given example raised an unexpected exception.
1142 """
Edward Loper8e4a34b2004-08-12 02:34:27 +00001143 out(self._failure_header(test, example) +
Edward Loperaacf0832004-08-26 01:19:50 +00001144 'Exception raised:\n' + _indent(_exception_traceback(exc_info)))
Tim Peters7402f792001-10-02 03:53:41 +00001145
Edward Loper8e4a34b2004-08-12 02:34:27 +00001146 def _failure_header(self, test, example):
Jim Fulton07a349c2004-08-22 14:10:00 +00001147 out = [self.DIVIDER]
1148 if test.filename:
1149 if test.lineno is not None and example.lineno is not None:
1150 lineno = test.lineno + example.lineno + 1
1151 else:
1152 lineno = '?'
1153 out.append('File "%s", line %s, in %s' %
1154 (test.filename, lineno, test.name))
Tim Peters8485b562004-08-04 18:46:34 +00001155 else:
Jim Fulton07a349c2004-08-22 14:10:00 +00001156 out.append('Line %s, in %s' % (example.lineno+1, test.name))
1157 out.append('Failed example:')
1158 source = example.source
Edward Loperaacf0832004-08-26 01:19:50 +00001159 out.append(_indent(source))
1160 return '\n'.join(out)
Tim Peters7402f792001-10-02 03:53:41 +00001161
Tim Peters8485b562004-08-04 18:46:34 +00001162 #/////////////////////////////////////////////////////////////////
1163 # DocTest Running
1164 #/////////////////////////////////////////////////////////////////
Tim Peters7402f792001-10-02 03:53:41 +00001165
Tim Peters8485b562004-08-04 18:46:34 +00001166 def __run(self, test, compileflags, out):
Tim Peters8a7d2d52001-01-16 07:10:57 +00001167 """
Tim Peters8485b562004-08-04 18:46:34 +00001168 Run the examples in `test`. Write the outcome of each example
1169 with one of the `DocTestRunner.report_*` methods, using the
1170 writer function `out`. `compileflags` is the set of compiler
1171 flags that should be used to execute examples. Return a tuple
1172 `(f, t)`, where `t` is the number of examples tried, and `f`
1173 is the number of examples that failed. The examples are run
1174 in the namespace `test.globs`.
1175 """
1176 # Keep track of the number of failures and tries.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001177 failures = tries = 0
Tim Peters8485b562004-08-04 18:46:34 +00001178
1179 # Save the option flags (since option directives can be used
1180 # to modify them).
1181 original_optionflags = self.optionflags
1182
Tim Peters1fbf9c52004-09-04 17:21:02 +00001183 SUCCESS, FAILURE, BOOM = range(3) # `outcome` state
1184
1185 check = self._checker.check_output
1186
Tim Peters8485b562004-08-04 18:46:34 +00001187 # Process each example.
Edward Loper2de91ba2004-08-27 02:07:46 +00001188 for examplenum, example in enumerate(test.examples):
1189
Edward Lopera89f88d2004-08-26 02:45:51 +00001190 # If REPORT_ONLY_FIRST_FAILURE is set, then supress
1191 # reporting after the first failure.
1192 quiet = (self.optionflags & REPORT_ONLY_FIRST_FAILURE and
1193 failures > 0)
1194
Edward Loper74bca7a2004-08-12 02:27:44 +00001195 # Merge in the example's options.
1196 self.optionflags = original_optionflags
1197 if example.options:
1198 for (optionflag, val) in example.options.items():
1199 if val:
1200 self.optionflags |= optionflag
1201 else:
1202 self.optionflags &= ~optionflag
Tim Peters8485b562004-08-04 18:46:34 +00001203
Thomas Wouters477c8d52006-05-27 19:21:47 +00001204 # If 'SKIP' is set, then skip this example.
1205 if self.optionflags & SKIP:
1206 continue
1207
Tim Peters8485b562004-08-04 18:46:34 +00001208 # Record that we started this example.
1209 tries += 1
Edward Lopera89f88d2004-08-26 02:45:51 +00001210 if not quiet:
1211 self.report_start(out, test, example)
Tim Peters8485b562004-08-04 18:46:34 +00001212
Edward Loper2de91ba2004-08-27 02:07:46 +00001213 # Use a special filename for compile(), so we can retrieve
1214 # the source code during interactive debugging (see
1215 # __patched_linecache_getlines).
1216 filename = '<doctest %s[%d]>' % (test.name, examplenum)
1217
Tim Peters8485b562004-08-04 18:46:34 +00001218 # Run the example in the given context (globs), and record
1219 # any exception that gets raised. (But don't intercept
1220 # keyboard interrupts.)
1221 try:
Tim Peters208ca702004-08-09 04:12:36 +00001222 # Don't blink! This is where the user's code gets run.
Georg Brandl7cae87c2006-09-06 06:51:57 +00001223 exec(compile(example.source, filename, "single",
1224 compileflags, 1), test.globs)
Edward Loper2de91ba2004-08-27 02:07:46 +00001225 self.debugger.set_continue() # ==== Example Finished ====
Tim Peters8485b562004-08-04 18:46:34 +00001226 exception = None
1227 except KeyboardInterrupt:
1228 raise
1229 except:
1230 exception = sys.exc_info()
Edward Loper2de91ba2004-08-27 02:07:46 +00001231 self.debugger.set_continue() # ==== Example Finished ====
Tim Peters8485b562004-08-04 18:46:34 +00001232
Tim Peters208ca702004-08-09 04:12:36 +00001233 got = self._fakeout.getvalue() # the actual output
Tim Peters8485b562004-08-04 18:46:34 +00001234 self._fakeout.truncate(0)
Tim Peters1fbf9c52004-09-04 17:21:02 +00001235 outcome = FAILURE # guilty until proved innocent or insane
Tim Peters8485b562004-08-04 18:46:34 +00001236
1237 # If the example executed without raising any exceptions,
Tim Peters1fbf9c52004-09-04 17:21:02 +00001238 # verify its output.
Tim Peters8485b562004-08-04 18:46:34 +00001239 if exception is None:
Tim Peters1fbf9c52004-09-04 17:21:02 +00001240 if check(example.want, got, self.optionflags):
1241 outcome = SUCCESS
Tim Peters8485b562004-08-04 18:46:34 +00001242
Tim Peters1fbf9c52004-09-04 17:21:02 +00001243 # The example raised an exception: check if it was expected.
Tim Peters8485b562004-08-04 18:46:34 +00001244 else:
Benjamin Petersoneec3d712008-06-11 15:59:43 +00001245 exc_msg = traceback.format_exception_only(*exception[:2])[-1]
Tim Peters1fbf9c52004-09-04 17:21:02 +00001246 if not quiet:
Benjamin Petersoneec3d712008-06-11 15:59:43 +00001247 got += _exception_traceback(exception)
Tim Peters8485b562004-08-04 18:46:34 +00001248
Tim Peters1fbf9c52004-09-04 17:21:02 +00001249 # If `example.exc_msg` is None, then we weren't expecting
1250 # an exception.
Edward Lopera6b68322004-08-26 00:05:43 +00001251 if example.exc_msg is None:
Tim Peters1fbf9c52004-09-04 17:21:02 +00001252 outcome = BOOM
1253
1254 # We expected an exception: see whether it matches.
1255 elif check(example.exc_msg, exc_msg, self.optionflags):
1256 outcome = SUCCESS
1257
1258 # Another chance if they didn't care about the detail.
1259 elif self.optionflags & IGNORE_EXCEPTION_DETAIL:
1260 m1 = re.match(r'[^:]*:', example.exc_msg)
1261 m2 = re.match(r'[^:]*:', exc_msg)
1262 if m1 and m2 and check(m1.group(0), m2.group(0),
1263 self.optionflags):
1264 outcome = SUCCESS
1265
1266 # Report the outcome.
1267 if outcome is SUCCESS:
1268 if not quiet:
1269 self.report_success(out, test, example, got)
1270 elif outcome is FAILURE:
1271 if not quiet:
1272 self.report_failure(out, test, example, got)
1273 failures += 1
1274 elif outcome is BOOM:
1275 if not quiet:
1276 self.report_unexpected_exception(out, test, example,
Benjamin Petersoneec3d712008-06-11 15:59:43 +00001277 exception)
Tim Peters1fbf9c52004-09-04 17:21:02 +00001278 failures += 1
1279 else:
1280 assert False, ("unknown outcome", outcome)
Tim Peters8485b562004-08-04 18:46:34 +00001281
1282 # Restore the option flags (in case they were modified)
1283 self.optionflags = original_optionflags
1284
1285 # Record and return the number of failures and tries.
1286 self.__record_outcome(test, failures, tries)
Christian Heimes25bb7832008-01-11 16:17:00 +00001287 return TestResults(failures, tries)
Tim Peters8a7d2d52001-01-16 07:10:57 +00001288
Tim Peters8485b562004-08-04 18:46:34 +00001289 def __record_outcome(self, test, f, t):
1290 """
1291 Record the fact that the given DocTest (`test`) generated `f`
1292 failures out of `t` tried examples.
1293 """
1294 f2, t2 = self._name2ft.get(test.name, (0,0))
1295 self._name2ft[test.name] = (f+f2, t+t2)
1296 self.failures += f
1297 self.tries += t
1298
Edward Loper2de91ba2004-08-27 02:07:46 +00001299 __LINECACHE_FILENAME_RE = re.compile(r'<doctest '
1300 r'(?P<name>[\w\.]+)'
1301 r'\[(?P<examplenum>\d+)\]>$')
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00001302 def __patched_linecache_getlines(self, filename, module_globals=None):
Edward Loper2de91ba2004-08-27 02:07:46 +00001303 m = self.__LINECACHE_FILENAME_RE.match(filename)
1304 if m and m.group('name') == self.test.name:
1305 example = self.test.examples[int(m.group('examplenum'))]
1306 return example.source.splitlines(True)
1307 else:
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00001308 return self.save_linecache_getlines(filename, module_globals)
Edward Loper2de91ba2004-08-27 02:07:46 +00001309
Tim Peters8485b562004-08-04 18:46:34 +00001310 def run(self, test, compileflags=None, out=None, clear_globs=True):
1311 """
1312 Run the examples in `test`, and display the results using the
1313 writer function `out`.
1314
1315 The examples are run in the namespace `test.globs`. If
1316 `clear_globs` is true (the default), then this namespace will
1317 be cleared after the test runs, to help with garbage
1318 collection. If you would like to examine the namespace after
1319 the test completes, then use `clear_globs=False`.
1320
1321 `compileflags` gives the set of flags that should be used by
1322 the Python compiler when running the examples. If not
1323 specified, then it will default to the set of future-import
1324 flags that apply to `globs`.
1325
1326 The output of each example is checked using
1327 `DocTestRunner.check_output`, and the results are formatted by
1328 the `DocTestRunner.report_*` methods.
1329 """
Edward Loper2de91ba2004-08-27 02:07:46 +00001330 self.test = test
1331
Tim Peters8485b562004-08-04 18:46:34 +00001332 if compileflags is None:
1333 compileflags = _extract_future_flags(test.globs)
Jim Fulton356fd192004-08-09 11:34:47 +00001334
Tim Peters6c542b72004-08-09 16:43:36 +00001335 save_stdout = sys.stdout
Tim Peters8485b562004-08-04 18:46:34 +00001336 if out is None:
Tim Peters6c542b72004-08-09 16:43:36 +00001337 out = save_stdout.write
1338 sys.stdout = self._fakeout
Tim Peters8485b562004-08-04 18:46:34 +00001339
Edward Loper2de91ba2004-08-27 02:07:46 +00001340 # Patch pdb.set_trace to restore sys.stdout during interactive
1341 # debugging (so it's not still redirected to self._fakeout).
1342 # Note that the interactive output will go to *our*
1343 # save_stdout, even if that's not the real sys.stdout; this
1344 # allows us to write test cases for the set_trace behavior.
Tim Peters6c542b72004-08-09 16:43:36 +00001345 save_set_trace = pdb.set_trace
Edward Loper2de91ba2004-08-27 02:07:46 +00001346 self.debugger = _OutputRedirectingPdb(save_stdout)
1347 self.debugger.reset()
1348 pdb.set_trace = self.debugger.set_trace
1349
1350 # Patch linecache.getlines, so we can see the example's source
1351 # when we're inside the debugger.
1352 self.save_linecache_getlines = linecache.getlines
1353 linecache.getlines = self.__patched_linecache_getlines
1354
Tim Peters8485b562004-08-04 18:46:34 +00001355 try:
Tim Peters8485b562004-08-04 18:46:34 +00001356 return self.__run(test, compileflags, out)
1357 finally:
Tim Peters6c542b72004-08-09 16:43:36 +00001358 sys.stdout = save_stdout
1359 pdb.set_trace = save_set_trace
Edward Loper2de91ba2004-08-27 02:07:46 +00001360 linecache.getlines = self.save_linecache_getlines
Tim Peters8485b562004-08-04 18:46:34 +00001361 if clear_globs:
1362 test.globs.clear()
Benjamin Petersonfbf66bd2008-07-29 15:55:50 +00001363 import builtins
1364 builtins._ = None
Tim Peters8485b562004-08-04 18:46:34 +00001365
1366 #/////////////////////////////////////////////////////////////////
1367 # Summarization
1368 #/////////////////////////////////////////////////////////////////
Tim Peters8a7d2d52001-01-16 07:10:57 +00001369 def summarize(self, verbose=None):
1370 """
Tim Peters8485b562004-08-04 18:46:34 +00001371 Print a summary of all the test cases that have been run by
1372 this DocTestRunner, and return a tuple `(f, t)`, where `f` is
1373 the total number of failed examples, and `t` is the total
1374 number of tried examples.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001375
Tim Peters8485b562004-08-04 18:46:34 +00001376 The optional `verbose` argument controls how detailed the
1377 summary is. If the verbosity is not specified, then the
1378 DocTestRunner's verbosity is used.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001379 """
Tim Peters8a7d2d52001-01-16 07:10:57 +00001380 if verbose is None:
Tim Peters8485b562004-08-04 18:46:34 +00001381 verbose = self._verbose
Tim Peters8a7d2d52001-01-16 07:10:57 +00001382 notests = []
1383 passed = []
1384 failed = []
1385 totalt = totalf = 0
Tim Peters8485b562004-08-04 18:46:34 +00001386 for x in self._name2ft.items():
Tim Peters8a7d2d52001-01-16 07:10:57 +00001387 name, (f, t) = x
1388 assert f <= t
Tim Peters8485b562004-08-04 18:46:34 +00001389 totalt += t
1390 totalf += f
Tim Peters8a7d2d52001-01-16 07:10:57 +00001391 if t == 0:
1392 notests.append(name)
1393 elif f == 0:
1394 passed.append( (name, t) )
1395 else:
1396 failed.append(x)
1397 if verbose:
1398 if notests:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001399 print(len(notests), "items had no tests:")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001400 notests.sort()
1401 for thing in notests:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001402 print(" ", thing)
Tim Peters8a7d2d52001-01-16 07:10:57 +00001403 if passed:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001404 print(len(passed), "items passed all tests:")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001405 passed.sort()
1406 for thing, count in passed:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001407 print(" %3d tests in %s" % (count, thing))
Tim Peters8a7d2d52001-01-16 07:10:57 +00001408 if failed:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001409 print(self.DIVIDER)
1410 print(len(failed), "items had failures:")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001411 failed.sort()
1412 for thing, (f, t) in failed:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001413 print(" %3d of %3d in %s" % (f, t, thing))
Tim Peters8a7d2d52001-01-16 07:10:57 +00001414 if verbose:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001415 print(totalt, "tests in", len(self._name2ft), "items.")
1416 print(totalt - totalf, "passed and", totalf, "failed.")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001417 if totalf:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001418 print("***Test Failed***", totalf, "failures.")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001419 elif verbose:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001420 print("Test passed.")
Christian Heimes25bb7832008-01-11 16:17:00 +00001421 return TestResults(totalf, totalt)
Tim Peters8a7d2d52001-01-16 07:10:57 +00001422
Tim Peters82076ef2004-09-13 00:52:51 +00001423 #/////////////////////////////////////////////////////////////////
1424 # Backward compatibility cruft to maintain doctest.master.
1425 #/////////////////////////////////////////////////////////////////
1426 def merge(self, other):
1427 d = self._name2ft
1428 for name, (f, t) in other._name2ft.items():
1429 if name in d:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001430 print("*** DocTestRunner.merge: '" + name + "' in both" \
1431 " testers; summing outcomes.")
Tim Peters82076ef2004-09-13 00:52:51 +00001432 f2, t2 = d[name]
1433 f = f + f2
1434 t = t + t2
1435 d[name] = f, t
1436
Edward Loper34fcb142004-08-09 02:45:41 +00001437class OutputChecker:
1438 """
1439 A class used to check the whether the actual output from a doctest
1440 example matches the expected output. `OutputChecker` defines two
1441 methods: `check_output`, which compares a given pair of outputs,
1442 and returns true if they match; and `output_difference`, which
1443 returns a string describing the differences between two outputs.
1444 """
Georg Brandl559e5d72008-06-11 18:37:52 +00001445 def _toAscii(self, s):
1446 """
1447 Convert string to hex-escaped ASCII string.
1448 """
1449 return str(s.encode('ASCII', 'backslashreplace'), "ASCII")
1450
Edward Loper34fcb142004-08-09 02:45:41 +00001451 def check_output(self, want, got, optionflags):
1452 """
Edward Loper74bca7a2004-08-12 02:27:44 +00001453 Return True iff the actual output from an example (`got`)
1454 matches the expected output (`want`). These strings are
1455 always considered to match if they are identical; but
1456 depending on what option flags the test runner is using,
1457 several non-exact match types are also possible. See the
1458 documentation for `TestRunner` for more information about
1459 option flags.
Edward Loper34fcb142004-08-09 02:45:41 +00001460 """
Georg Brandl559e5d72008-06-11 18:37:52 +00001461
1462 # If `want` contains hex-escaped character such as "\u1234",
1463 # then `want` is a string of six characters(e.g. [\,u,1,2,3,4]).
1464 # On the other hand, `got` could be an another sequence of
1465 # characters such as [\u1234], so `want` and `got` should
1466 # be folded to hex-escaped ASCII string to compare.
1467 got = self._toAscii(got)
1468 want = self._toAscii(want)
1469
Edward Loper34fcb142004-08-09 02:45:41 +00001470 # Handle the common case first, for efficiency:
1471 # if they're string-identical, always return true.
1472 if got == want:
1473 return True
1474
1475 # The values True and False replaced 1 and 0 as the return
1476 # value for boolean comparisons in Python 2.3.
1477 if not (optionflags & DONT_ACCEPT_TRUE_FOR_1):
1478 if (got,want) == ("True\n", "1\n"):
1479 return True
1480 if (got,want) == ("False\n", "0\n"):
1481 return True
1482
1483 # <BLANKLINE> can be used as a special sequence to signify a
1484 # blank line, unless the DONT_ACCEPT_BLANKLINE flag is used.
1485 if not (optionflags & DONT_ACCEPT_BLANKLINE):
1486 # Replace <BLANKLINE> in want with a blank line.
1487 want = re.sub('(?m)^%s\s*?$' % re.escape(BLANKLINE_MARKER),
1488 '', want)
1489 # If a line in got contains only spaces, then remove the
1490 # spaces.
1491 got = re.sub('(?m)^\s*?$', '', got)
1492 if got == want:
1493 return True
1494
1495 # This flag causes doctest to ignore any differences in the
1496 # contents of whitespace strings. Note that this can be used
Tim Peters3fa8c202004-08-23 21:43:39 +00001497 # in conjunction with the ELLIPSIS flag.
Tim Peters1cf3aa62004-08-19 06:49:33 +00001498 if optionflags & NORMALIZE_WHITESPACE:
Edward Loper34fcb142004-08-09 02:45:41 +00001499 got = ' '.join(got.split())
1500 want = ' '.join(want.split())
1501 if got == want:
1502 return True
1503
1504 # The ELLIPSIS flag says to let the sequence "..." in `want`
Tim Peters26b3ebb2004-08-19 08:10:08 +00001505 # match any substring in `got`.
Tim Peters1cf3aa62004-08-19 06:49:33 +00001506 if optionflags & ELLIPSIS:
Tim Petersb0a04e12004-08-20 02:08:04 +00001507 if _ellipsis_match(want, got):
Edward Loper34fcb142004-08-09 02:45:41 +00001508 return True
1509
1510 # We didn't find any match; return false.
1511 return False
1512
Tim Petersc6cbab02004-08-22 19:43:28 +00001513 # Should we do a fancy diff?
1514 def _do_a_fancy_diff(self, want, got, optionflags):
1515 # Not unless they asked for a fancy diff.
Edward Loper71f55af2004-08-26 01:41:51 +00001516 if not optionflags & (REPORT_UDIFF |
1517 REPORT_CDIFF |
1518 REPORT_NDIFF):
Tim Petersc6cbab02004-08-22 19:43:28 +00001519 return False
Tim Peters5b799c12004-08-26 05:21:59 +00001520
Tim Petersc6cbab02004-08-22 19:43:28 +00001521 # If expected output uses ellipsis, a meaningful fancy diff is
Tim Peters5b799c12004-08-26 05:21:59 +00001522 # too hard ... or maybe not. In two real-life failures Tim saw,
1523 # a diff was a major help anyway, so this is commented out.
1524 # [todo] _ellipsis_match() knows which pieces do and don't match,
1525 # and could be the basis for a kick-ass diff in this case.
1526 ##if optionflags & ELLIPSIS and ELLIPSIS_MARKER in want:
1527 ## return False
1528
Tim Petersc6cbab02004-08-22 19:43:28 +00001529 # ndiff does intraline difference marking, so can be useful even
Tim Peters5b799c12004-08-26 05:21:59 +00001530 # for 1-line differences.
Edward Loper71f55af2004-08-26 01:41:51 +00001531 if optionflags & REPORT_NDIFF:
Tim Petersc6cbab02004-08-22 19:43:28 +00001532 return True
Tim Peters5b799c12004-08-26 05:21:59 +00001533
Tim Petersc6cbab02004-08-22 19:43:28 +00001534 # The other diff types need at least a few lines to be helpful.
1535 return want.count('\n') > 2 and got.count('\n') > 2
1536
Edward Loperca9111e2004-08-26 03:00:24 +00001537 def output_difference(self, example, got, optionflags):
Edward Loper34fcb142004-08-09 02:45:41 +00001538 """
1539 Return a string describing the differences between the
Edward Loperca9111e2004-08-26 03:00:24 +00001540 expected output for a given example (`example`) and the actual
1541 output (`got`). `optionflags` is the set of option flags used
1542 to compare `want` and `got`.
Edward Loper34fcb142004-08-09 02:45:41 +00001543 """
Edward Loperca9111e2004-08-26 03:00:24 +00001544 want = example.want
Edward Loper68ba9a62004-08-12 02:43:49 +00001545 # If <BLANKLINE>s are being used, then replace blank lines
1546 # with <BLANKLINE> in the actual output string.
Edward Loper34fcb142004-08-09 02:45:41 +00001547 if not (optionflags & DONT_ACCEPT_BLANKLINE):
Edward Loper68ba9a62004-08-12 02:43:49 +00001548 got = re.sub('(?m)^[ ]*(?=\n)', BLANKLINE_MARKER, got)
Edward Loper34fcb142004-08-09 02:45:41 +00001549
Tim Peters5b799c12004-08-26 05:21:59 +00001550 # Check if we should use diff.
Tim Petersc6cbab02004-08-22 19:43:28 +00001551 if self._do_a_fancy_diff(want, got, optionflags):
Edward Loper34fcb142004-08-09 02:45:41 +00001552 # Split want & got into lines.
Tim Peterse7edcb82004-08-26 05:44:27 +00001553 want_lines = want.splitlines(True) # True == keep line ends
1554 got_lines = got.splitlines(True)
Edward Loper34fcb142004-08-09 02:45:41 +00001555 # Use difflib to find their differences.
Edward Loper71f55af2004-08-26 01:41:51 +00001556 if optionflags & REPORT_UDIFF:
Edward Loper56629292004-08-26 01:31:56 +00001557 diff = difflib.unified_diff(want_lines, got_lines, n=2)
1558 diff = list(diff)[2:] # strip the diff header
1559 kind = 'unified diff with -expected +actual'
Edward Loper71f55af2004-08-26 01:41:51 +00001560 elif optionflags & REPORT_CDIFF:
Edward Loper56629292004-08-26 01:31:56 +00001561 diff = difflib.context_diff(want_lines, got_lines, n=2)
1562 diff = list(diff)[2:] # strip the diff header
1563 kind = 'context diff with expected followed by actual'
Edward Loper71f55af2004-08-26 01:41:51 +00001564 elif optionflags & REPORT_NDIFF:
Tim Petersc6cbab02004-08-22 19:43:28 +00001565 engine = difflib.Differ(charjunk=difflib.IS_CHARACTER_JUNK)
1566 diff = list(engine.compare(want_lines, got_lines))
1567 kind = 'ndiff with -expected +actual'
Edward Loper34fcb142004-08-09 02:45:41 +00001568 else:
1569 assert 0, 'Bad diff option'
1570 # Remove trailing whitespace on diff output.
1571 diff = [line.rstrip() + '\n' for line in diff]
Edward Loperaacf0832004-08-26 01:19:50 +00001572 return 'Differences (%s):\n' % kind + _indent(''.join(diff))
Edward Loper34fcb142004-08-09 02:45:41 +00001573
1574 # If we're not using diff, then simply list the expected
1575 # output followed by the actual output.
Edward Loperaacf0832004-08-26 01:19:50 +00001576 if want and got:
1577 return 'Expected:\n%sGot:\n%s' % (_indent(want), _indent(got))
1578 elif want:
1579 return 'Expected:\n%sGot nothing\n' % _indent(want)
1580 elif got:
1581 return 'Expected nothing\nGot:\n%s' % _indent(got)
1582 else:
1583 return 'Expected nothing\nGot nothing\n'
Edward Loper34fcb142004-08-09 02:45:41 +00001584
Tim Peters19397e52004-08-06 22:02:59 +00001585class DocTestFailure(Exception):
1586 """A DocTest example has failed in debugging mode.
1587
1588 The exception instance has variables:
1589
1590 - test: the DocTest object being run
1591
Neal Norwitzc082cb72006-08-29 05:40:08 +00001592 - example: the Example object that failed
Tim Peters19397e52004-08-06 22:02:59 +00001593
1594 - got: the actual output
1595 """
1596 def __init__(self, test, example, got):
1597 self.test = test
1598 self.example = example
1599 self.got = got
1600
1601 def __str__(self):
1602 return str(self.test)
1603
1604class UnexpectedException(Exception):
1605 """A DocTest example has encountered an unexpected exception
1606
1607 The exception instance has variables:
1608
1609 - test: the DocTest object being run
1610
Guido van Rossum6a2a2a02006-08-26 20:37:44 +00001611 - example: the Example object that failed
Tim Peters19397e52004-08-06 22:02:59 +00001612
1613 - exc_info: the exception info
1614 """
1615 def __init__(self, test, example, exc_info):
1616 self.test = test
1617 self.example = example
1618 self.exc_info = exc_info
1619
1620 def __str__(self):
1621 return str(self.test)
Tim Petersd1b78272004-08-07 06:03:09 +00001622
Tim Peters19397e52004-08-06 22:02:59 +00001623class DebugRunner(DocTestRunner):
1624 r"""Run doc tests but raise an exception as soon as there is a failure.
1625
1626 If an unexpected exception occurs, an UnexpectedException is raised.
1627 It contains the test, the example, and the original exception:
1628
1629 >>> runner = DebugRunner(verbose=False)
Edward Lopera1ef6112004-08-09 16:14:41 +00001630 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
1631 ... {}, 'foo', 'foo.py', 0)
Tim Peters19397e52004-08-06 22:02:59 +00001632 >>> try:
1633 ... runner.run(test)
Guido van Rossumb940e112007-01-10 16:19:56 +00001634 ... except UnexpectedException as f:
1635 ... failure = f
Tim Peters19397e52004-08-06 22:02:59 +00001636
1637 >>> failure.test is test
1638 True
1639
1640 >>> failure.example.want
1641 '42\n'
1642
1643 >>> exc_info = failure.exc_info
Collin Winter828f04a2007-08-31 00:04:24 +00001644 >>> raise exc_info[1] # Already has the traceback
Tim Peters19397e52004-08-06 22:02:59 +00001645 Traceback (most recent call last):
1646 ...
1647 KeyError
1648
1649 We wrap the original exception to give the calling application
1650 access to the test and example information.
1651
1652 If the output doesn't match, then a DocTestFailure is raised:
1653
Edward Lopera1ef6112004-08-09 16:14:41 +00001654 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00001655 ... >>> x = 1
1656 ... >>> x
1657 ... 2
1658 ... ''', {}, 'foo', 'foo.py', 0)
1659
1660 >>> try:
1661 ... runner.run(test)
Guido van Rossumb940e112007-01-10 16:19:56 +00001662 ... except DocTestFailure as f:
1663 ... failure = f
Tim Peters19397e52004-08-06 22:02:59 +00001664
1665 DocTestFailure objects provide access to the test:
1666
1667 >>> failure.test is test
1668 True
1669
1670 As well as to the example:
1671
1672 >>> failure.example.want
1673 '2\n'
1674
1675 and the actual output:
1676
1677 >>> failure.got
1678 '1\n'
1679
1680 If a failure or error occurs, the globals are left intact:
1681
1682 >>> del test.globs['__builtins__']
1683 >>> test.globs
1684 {'x': 1}
1685
Edward Lopera1ef6112004-08-09 16:14:41 +00001686 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00001687 ... >>> x = 2
1688 ... >>> raise KeyError
1689 ... ''', {}, 'foo', 'foo.py', 0)
1690
1691 >>> runner.run(test)
1692 Traceback (most recent call last):
1693 ...
Guido van Rossum6a2a2a02006-08-26 20:37:44 +00001694 doctest.UnexpectedException: <DocTest foo from foo.py:0 (2 examples)>
Tim Petersd1b78272004-08-07 06:03:09 +00001695
Tim Peters19397e52004-08-06 22:02:59 +00001696 >>> del test.globs['__builtins__']
1697 >>> test.globs
1698 {'x': 2}
1699
1700 But the globals are cleared if there is no error:
1701
Edward Lopera1ef6112004-08-09 16:14:41 +00001702 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00001703 ... >>> x = 2
1704 ... ''', {}, 'foo', 'foo.py', 0)
1705
1706 >>> runner.run(test)
Christian Heimes25bb7832008-01-11 16:17:00 +00001707 TestResults(failed=0, attempted=1)
Tim Peters19397e52004-08-06 22:02:59 +00001708
1709 >>> test.globs
1710 {}
1711
1712 """
1713
1714 def run(self, test, compileflags=None, out=None, clear_globs=True):
1715 r = DocTestRunner.run(self, test, compileflags, out, False)
1716 if clear_globs:
1717 test.globs.clear()
1718 return r
1719
1720 def report_unexpected_exception(self, out, test, example, exc_info):
1721 raise UnexpectedException(test, example, exc_info)
1722
1723 def report_failure(self, out, test, example, got):
1724 raise DocTestFailure(test, example, got)
1725
Tim Peters8485b562004-08-04 18:46:34 +00001726######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00001727## 6. Test Functions
Tim Peters8485b562004-08-04 18:46:34 +00001728######################################################################
1729# These should be backwards compatible.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001730
Tim Peters82076ef2004-09-13 00:52:51 +00001731# For backward compatibility, a global instance of a DocTestRunner
1732# class, updated by testmod.
1733master = None
1734
Thomas Wouters73e5a5b2006-06-08 15:35:45 +00001735def testmod(m=None, name=None, globs=None, verbose=None,
Tim Peters19397e52004-08-06 22:02:59 +00001736 report=True, optionflags=0, extraglobs=None,
Tim Peters958cc892004-09-13 14:53:28 +00001737 raise_on_error=False, exclude_empty=False):
Thomas Wouters73e5a5b2006-06-08 15:35:45 +00001738 """m=None, name=None, globs=None, verbose=None, report=True,
1739 optionflags=0, extraglobs=None, raise_on_error=False,
Tim Peters958cc892004-09-13 14:53:28 +00001740 exclude_empty=False
Tim Peters8a7d2d52001-01-16 07:10:57 +00001741
Martin v. Löwis4581cfa2002-11-22 08:23:09 +00001742 Test examples in docstrings in functions and classes reachable
1743 from module m (or the current module if m is not supplied), starting
Thomas Wouters73e5a5b2006-06-08 15:35:45 +00001744 with m.__doc__.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001745
1746 Also test examples reachable from dict m.__test__ if it exists and is
Tim Petersc2388a22004-08-10 01:41:28 +00001747 not None. m.__test__ maps names to functions, classes and strings;
Tim Peters8a7d2d52001-01-16 07:10:57 +00001748 function and class docstrings are tested even if the name is private;
1749 strings are tested directly, as if they were docstrings.
1750
1751 Return (#failures, #tests).
1752
1753 See doctest.__doc__ for an overview.
1754
1755 Optional keyword arg "name" gives the name of the module; by default
1756 use m.__name__.
1757
1758 Optional keyword arg "globs" gives a dict to be used as the globals
1759 when executing examples; by default, use m.__dict__. A copy of this
1760 dict is actually used for each docstring, so that each docstring's
1761 examples start with a clean slate.
1762
Tim Peters8485b562004-08-04 18:46:34 +00001763 Optional keyword arg "extraglobs" gives a dictionary that should be
1764 merged into the globals that are used to execute examples. By
1765 default, no extra globals are used. This is new in 2.4.
1766
Tim Peters8a7d2d52001-01-16 07:10:57 +00001767 Optional keyword arg "verbose" prints lots of stuff if true, prints
1768 only failures if false; by default, it's true iff "-v" is in sys.argv.
1769
Tim Peters8a7d2d52001-01-16 07:10:57 +00001770 Optional keyword arg "report" prints a summary at the end when true,
1771 else prints nothing at the end. In verbose mode, the summary is
1772 detailed, else very brief (in fact, empty if all tests passed).
1773
Tim Peters6ebe61f2003-06-27 20:48:05 +00001774 Optional keyword arg "optionflags" or's together module constants,
Tim Petersf82a9de2004-08-22 20:51:53 +00001775 and defaults to 0. This is new in 2.3. Possible values (see the
1776 docs for details):
Tim Peters6ebe61f2003-06-27 20:48:05 +00001777
1778 DONT_ACCEPT_TRUE_FOR_1
Tim Peters8485b562004-08-04 18:46:34 +00001779 DONT_ACCEPT_BLANKLINE
Tim Peters8485b562004-08-04 18:46:34 +00001780 NORMALIZE_WHITESPACE
Tim Peters8485b562004-08-04 18:46:34 +00001781 ELLIPSIS
Thomas Wouters477c8d52006-05-27 19:21:47 +00001782 SKIP
Edward Loper052d0cd2004-09-19 17:19:33 +00001783 IGNORE_EXCEPTION_DETAIL
Edward Loper71f55af2004-08-26 01:41:51 +00001784 REPORT_UDIFF
1785 REPORT_CDIFF
1786 REPORT_NDIFF
Edward Lopera89f88d2004-08-26 02:45:51 +00001787 REPORT_ONLY_FIRST_FAILURE
Tim Peters19397e52004-08-06 22:02:59 +00001788
1789 Optional keyword arg "raise_on_error" raises an exception on the
1790 first unexpected exception or failure. This allows failures to be
1791 post-mortem debugged.
1792
Tim Peters8a7d2d52001-01-16 07:10:57 +00001793 Advanced tomfoolery: testmod runs methods of a local instance of
1794 class doctest.Tester, then merges the results into (or creates)
1795 global Tester instance doctest.master. Methods of doctest.master
1796 can be called directly too, if you want to do something unusual.
1797 Passing report=0 to testmod is especially useful then, to delay
1798 displaying a summary. Invoke doctest.master.summarize(verbose)
1799 when you're done fiddling.
1800 """
Tim Peters82076ef2004-09-13 00:52:51 +00001801 global master
1802
Tim Peters8485b562004-08-04 18:46:34 +00001803 # If no module was given, then use __main__.
Martin v. Löwis4581cfa2002-11-22 08:23:09 +00001804 if m is None:
Martin v. Löwis4581cfa2002-11-22 08:23:09 +00001805 # DWA - m will still be None if this wasn't invoked from the command
1806 # line, in which case the following TypeError is about as good an error
1807 # as we should expect
1808 m = sys.modules.get('__main__')
1809
Tim Peters8485b562004-08-04 18:46:34 +00001810 # Check that we were actually given a module.
1811 if not inspect.ismodule(m):
Walter Dörwald70a6b492004-02-12 17:35:32 +00001812 raise TypeError("testmod: module required; %r" % (m,))
Tim Peters8485b562004-08-04 18:46:34 +00001813
1814 # If no name was given, then use the module's name.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001815 if name is None:
1816 name = m.__name__
Tim Peters8485b562004-08-04 18:46:34 +00001817
1818 # Find, parse, and run all tests in the given module.
Thomas Wouters73e5a5b2006-06-08 15:35:45 +00001819 finder = DocTestFinder(exclude_empty=exclude_empty)
Tim Peters19397e52004-08-06 22:02:59 +00001820
1821 if raise_on_error:
1822 runner = DebugRunner(verbose=verbose, optionflags=optionflags)
1823 else:
1824 runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1825
Tim Peters8485b562004-08-04 18:46:34 +00001826 for test in finder.find(m, name, globs=globs, extraglobs=extraglobs):
1827 runner.run(test)
1828
Tim Peters8a7d2d52001-01-16 07:10:57 +00001829 if report:
Tim Peters8485b562004-08-04 18:46:34 +00001830 runner.summarize()
Tim Peters8a7d2d52001-01-16 07:10:57 +00001831
Tim Peters82076ef2004-09-13 00:52:51 +00001832 if master is None:
1833 master = runner
1834 else:
1835 master.merge(runner)
1836
Christian Heimes25bb7832008-01-11 16:17:00 +00001837 return TestResults(runner.failures, runner.tries)
Tim Petersdb3756d2003-06-29 05:30:48 +00001838
Edward Loper052d0cd2004-09-19 17:19:33 +00001839def testfile(filename, module_relative=True, name=None, package=None,
1840 globs=None, verbose=None, report=True, optionflags=0,
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00001841 extraglobs=None, raise_on_error=False, parser=DocTestParser(),
1842 encoding=None):
Edward Loper052d0cd2004-09-19 17:19:33 +00001843 """
1844 Test examples in the given file. Return (#failures, #tests).
1845
1846 Optional keyword arg "module_relative" specifies how filenames
1847 should be interpreted:
1848
1849 - If "module_relative" is True (the default), then "filename"
1850 specifies a module-relative path. By default, this path is
1851 relative to the calling module's directory; but if the
1852 "package" argument is specified, then it is relative to that
1853 package. To ensure os-independence, "filename" should use
1854 "/" characters to separate path segments, and should not
1855 be an absolute path (i.e., it may not begin with "/").
1856
1857 - If "module_relative" is False, then "filename" specifies an
1858 os-specific path. The path may be absolute or relative (to
1859 the current working directory).
1860
Edward Lopera2fc7ec2004-09-21 03:24:24 +00001861 Optional keyword arg "name" gives the name of the test; by default
1862 use the file's basename.
Edward Loper052d0cd2004-09-19 17:19:33 +00001863
1864 Optional keyword argument "package" is a Python package or the
1865 name of a Python package whose directory should be used as the
1866 base directory for a module relative filename. If no package is
1867 specified, then the calling module's directory is used as the base
1868 directory for module relative filenames. It is an error to
1869 specify "package" if "module_relative" is False.
1870
1871 Optional keyword arg "globs" gives a dict to be used as the globals
1872 when executing examples; by default, use {}. A copy of this dict
1873 is actually used for each docstring, so that each docstring's
1874 examples start with a clean slate.
1875
1876 Optional keyword arg "extraglobs" gives a dictionary that should be
1877 merged into the globals that are used to execute examples. By
1878 default, no extra globals are used.
1879
1880 Optional keyword arg "verbose" prints lots of stuff if true, prints
1881 only failures if false; by default, it's true iff "-v" is in sys.argv.
1882
1883 Optional keyword arg "report" prints a summary at the end when true,
1884 else prints nothing at the end. In verbose mode, the summary is
1885 detailed, else very brief (in fact, empty if all tests passed).
1886
1887 Optional keyword arg "optionflags" or's together module constants,
1888 and defaults to 0. Possible values (see the docs for details):
1889
1890 DONT_ACCEPT_TRUE_FOR_1
1891 DONT_ACCEPT_BLANKLINE
1892 NORMALIZE_WHITESPACE
1893 ELLIPSIS
Thomas Wouters477c8d52006-05-27 19:21:47 +00001894 SKIP
Edward Loper052d0cd2004-09-19 17:19:33 +00001895 IGNORE_EXCEPTION_DETAIL
1896 REPORT_UDIFF
1897 REPORT_CDIFF
1898 REPORT_NDIFF
1899 REPORT_ONLY_FIRST_FAILURE
1900
1901 Optional keyword arg "raise_on_error" raises an exception on the
1902 first unexpected exception or failure. This allows failures to be
1903 post-mortem debugged.
1904
Edward Loper498a1862004-09-27 03:42:58 +00001905 Optional keyword arg "parser" specifies a DocTestParser (or
1906 subclass) that should be used to extract tests from the files.
1907
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00001908 Optional keyword arg "encoding" specifies an encoding that should
1909 be used to convert the file to unicode.
1910
Edward Loper052d0cd2004-09-19 17:19:33 +00001911 Advanced tomfoolery: testmod runs methods of a local instance of
1912 class doctest.Tester, then merges the results into (or creates)
1913 global Tester instance doctest.master. Methods of doctest.master
1914 can be called directly too, if you want to do something unusual.
1915 Passing report=0 to testmod is especially useful then, to delay
1916 displaying a summary. Invoke doctest.master.summarize(verbose)
1917 when you're done fiddling.
1918 """
1919 global master
1920
1921 if package and not module_relative:
1922 raise ValueError("Package may only be specified for module-"
1923 "relative paths.")
Tim Petersbab3e992004-09-20 19:52:34 +00001924
Edward Loper052d0cd2004-09-19 17:19:33 +00001925 # Relativize the path
Guido van Rossum1b81e7b2007-08-29 03:53:53 +00001926 text, filename = _load_testfile(filename, package, module_relative,
1927 encoding or "utf-8")
Edward Loper052d0cd2004-09-19 17:19:33 +00001928
1929 # If no name was given, then use the file's name.
1930 if name is None:
Edward Lopera2fc7ec2004-09-21 03:24:24 +00001931 name = os.path.basename(filename)
Edward Loper052d0cd2004-09-19 17:19:33 +00001932
1933 # Assemble the globals.
1934 if globs is None:
1935 globs = {}
1936 else:
1937 globs = globs.copy()
1938 if extraglobs is not None:
1939 globs.update(extraglobs)
1940
1941 if raise_on_error:
1942 runner = DebugRunner(verbose=verbose, optionflags=optionflags)
1943 else:
1944 runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1945
1946 # Read the file, convert it to a test, and run it.
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00001947 test = parser.get_doctest(text, globs, name, filename, 0)
Edward Loper052d0cd2004-09-19 17:19:33 +00001948 runner.run(test)
1949
1950 if report:
1951 runner.summarize()
1952
1953 if master is None:
1954 master = runner
1955 else:
1956 master.merge(runner)
1957
Christian Heimes25bb7832008-01-11 16:17:00 +00001958 return TestResults(runner.failures, runner.tries)
Edward Loper052d0cd2004-09-19 17:19:33 +00001959
Tim Peters8485b562004-08-04 18:46:34 +00001960def run_docstring_examples(f, globs, verbose=False, name="NoName",
1961 compileflags=None, optionflags=0):
1962 """
1963 Test examples in the given object's docstring (`f`), using `globs`
1964 as globals. Optional argument `name` is used in failure messages.
1965 If the optional argument `verbose` is true, then generate output
1966 even if there are no failures.
Tim Petersdb3756d2003-06-29 05:30:48 +00001967
Tim Peters8485b562004-08-04 18:46:34 +00001968 `compileflags` gives the set of flags that should be used by the
1969 Python compiler when running the examples. If not specified, then
1970 it will default to the set of future-import flags that apply to
1971 `globs`.
Tim Petersdb3756d2003-06-29 05:30:48 +00001972
Tim Peters8485b562004-08-04 18:46:34 +00001973 Optional keyword arg `optionflags` specifies options for the
1974 testing and output. See the documentation for `testmod` for more
1975 information.
1976 """
1977 # Find, parse, and run all tests in the given module.
1978 finder = DocTestFinder(verbose=verbose, recurse=False)
1979 runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1980 for test in finder.find(f, name, globs=globs):
1981 runner.run(test, compileflags=compileflags)
Tim Petersdb3756d2003-06-29 05:30:48 +00001982
Tim Peters8485b562004-08-04 18:46:34 +00001983######################################################################
Georg Brandl31835852008-05-12 17:38:56 +00001984## 7. Unittest Support
Tim Peters8485b562004-08-04 18:46:34 +00001985######################################################################
Tim Petersdb3756d2003-06-29 05:30:48 +00001986
Jim Fultonf54bad42004-08-28 14:57:56 +00001987_unittest_reportflags = 0
Tim Peters38330fe2004-08-30 16:19:24 +00001988
Jim Fultonf54bad42004-08-28 14:57:56 +00001989def set_unittest_reportflags(flags):
Tim Peters38330fe2004-08-30 16:19:24 +00001990 """Sets the unittest option flags.
Jim Fultonf54bad42004-08-28 14:57:56 +00001991
1992 The old flag is returned so that a runner could restore the old
1993 value if it wished to:
1994
Tim Petersb7e99b62005-03-28 23:50:54 +00001995 >>> import doctest
1996 >>> old = doctest._unittest_reportflags
1997 >>> doctest.set_unittest_reportflags(REPORT_NDIFF |
Jim Fultonf54bad42004-08-28 14:57:56 +00001998 ... REPORT_ONLY_FIRST_FAILURE) == old
1999 True
2000
Jim Fultonf54bad42004-08-28 14:57:56 +00002001 >>> doctest._unittest_reportflags == (REPORT_NDIFF |
2002 ... REPORT_ONLY_FIRST_FAILURE)
2003 True
Tim Petersdf7a2082004-08-29 00:38:17 +00002004
Jim Fultonf54bad42004-08-28 14:57:56 +00002005 Only reporting flags can be set:
2006
Tim Petersb7e99b62005-03-28 23:50:54 +00002007 >>> doctest.set_unittest_reportflags(ELLIPSIS)
Jim Fultonf54bad42004-08-28 14:57:56 +00002008 Traceback (most recent call last):
2009 ...
Tim Peters38330fe2004-08-30 16:19:24 +00002010 ValueError: ('Only reporting flags allowed', 8)
Jim Fultonf54bad42004-08-28 14:57:56 +00002011
Tim Petersb7e99b62005-03-28 23:50:54 +00002012 >>> doctest.set_unittest_reportflags(old) == (REPORT_NDIFF |
Jim Fultonf54bad42004-08-28 14:57:56 +00002013 ... REPORT_ONLY_FIRST_FAILURE)
2014 True
Jim Fultonf54bad42004-08-28 14:57:56 +00002015 """
Jim Fultonf54bad42004-08-28 14:57:56 +00002016 global _unittest_reportflags
Tim Peters38330fe2004-08-30 16:19:24 +00002017
2018 if (flags & REPORTING_FLAGS) != flags:
2019 raise ValueError("Only reporting flags allowed", flags)
Jim Fultonf54bad42004-08-28 14:57:56 +00002020 old = _unittest_reportflags
2021 _unittest_reportflags = flags
2022 return old
Tim Petersdf7a2082004-08-29 00:38:17 +00002023
Jim Fultonf54bad42004-08-28 14:57:56 +00002024
Tim Peters19397e52004-08-06 22:02:59 +00002025class DocTestCase(unittest.TestCase):
Tim Petersdb3756d2003-06-29 05:30:48 +00002026
Edward Loper34fcb142004-08-09 02:45:41 +00002027 def __init__(self, test, optionflags=0, setUp=None, tearDown=None,
2028 checker=None):
Jim Fulton07a349c2004-08-22 14:10:00 +00002029
Jim Fultona643b652004-07-14 19:06:50 +00002030 unittest.TestCase.__init__(self)
Tim Peters19397e52004-08-06 22:02:59 +00002031 self._dt_optionflags = optionflags
Edward Loper34fcb142004-08-09 02:45:41 +00002032 self._dt_checker = checker
Tim Peters19397e52004-08-06 22:02:59 +00002033 self._dt_test = test
2034 self._dt_setUp = setUp
2035 self._dt_tearDown = tearDown
Tim Petersdb3756d2003-06-29 05:30:48 +00002036
Jim Fultona643b652004-07-14 19:06:50 +00002037 def setUp(self):
Jim Fultonf54bad42004-08-28 14:57:56 +00002038 test = self._dt_test
Tim Petersdf7a2082004-08-29 00:38:17 +00002039
Tim Peters19397e52004-08-06 22:02:59 +00002040 if self._dt_setUp is not None:
Jim Fultonf54bad42004-08-28 14:57:56 +00002041 self._dt_setUp(test)
Jim Fultona643b652004-07-14 19:06:50 +00002042
2043 def tearDown(self):
Jim Fultonf54bad42004-08-28 14:57:56 +00002044 test = self._dt_test
2045
Tim Peters19397e52004-08-06 22:02:59 +00002046 if self._dt_tearDown is not None:
Jim Fultonf54bad42004-08-28 14:57:56 +00002047 self._dt_tearDown(test)
2048
2049 test.globs.clear()
Jim Fultona643b652004-07-14 19:06:50 +00002050
2051 def runTest(self):
Tim Peters19397e52004-08-06 22:02:59 +00002052 test = self._dt_test
Jim Fultona643b652004-07-14 19:06:50 +00002053 old = sys.stdout
2054 new = StringIO()
Jim Fultonf54bad42004-08-28 14:57:56 +00002055 optionflags = self._dt_optionflags
Tim Petersdf7a2082004-08-29 00:38:17 +00002056
Tim Peters38330fe2004-08-30 16:19:24 +00002057 if not (optionflags & REPORTING_FLAGS):
Jim Fultonf54bad42004-08-28 14:57:56 +00002058 # The option flags don't include any reporting flags,
2059 # so add the default reporting flags
2060 optionflags |= _unittest_reportflags
Tim Petersdf7a2082004-08-29 00:38:17 +00002061
Jim Fultonf54bad42004-08-28 14:57:56 +00002062 runner = DocTestRunner(optionflags=optionflags,
Edward Loper34fcb142004-08-09 02:45:41 +00002063 checker=self._dt_checker, verbose=False)
Tim Peters19397e52004-08-06 22:02:59 +00002064
Jim Fultona643b652004-07-14 19:06:50 +00002065 try:
Tim Peters19397e52004-08-06 22:02:59 +00002066 runner.DIVIDER = "-"*70
Jim Fultonf54bad42004-08-28 14:57:56 +00002067 failures, tries = runner.run(
2068 test, out=new.write, clear_globs=False)
Jim Fultona643b652004-07-14 19:06:50 +00002069 finally:
2070 sys.stdout = old
2071
2072 if failures:
Tim Peters19397e52004-08-06 22:02:59 +00002073 raise self.failureException(self.format_failure(new.getvalue()))
Tim Peters8485b562004-08-04 18:46:34 +00002074
Tim Peters19397e52004-08-06 22:02:59 +00002075 def format_failure(self, err):
2076 test = self._dt_test
2077 if test.lineno is None:
2078 lineno = 'unknown line number'
2079 else:
Jim Fulton07a349c2004-08-22 14:10:00 +00002080 lineno = '%s' % test.lineno
Tim Peters19397e52004-08-06 22:02:59 +00002081 lname = '.'.join(test.name.split('.')[-1:])
2082 return ('Failed doctest test for %s\n'
2083 ' File "%s", line %s, in %s\n\n%s'
2084 % (test.name, test.filename, lineno, lname, err)
2085 )
2086
2087 def debug(self):
2088 r"""Run the test case without results and without catching exceptions
2089
2090 The unit test framework includes a debug method on test cases
2091 and test suites to support post-mortem debugging. The test code
2092 is run in such a way that errors are not caught. This way a
2093 caller can catch the errors and initiate post-mortem debugging.
2094
2095 The DocTestCase provides a debug method that raises
2096 UnexpectedException errors if there is an unexepcted
2097 exception:
2098
Edward Lopera1ef6112004-08-09 16:14:41 +00002099 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
Tim Peters19397e52004-08-06 22:02:59 +00002100 ... {}, 'foo', 'foo.py', 0)
2101 >>> case = DocTestCase(test)
2102 >>> try:
2103 ... case.debug()
Guido van Rossumb940e112007-01-10 16:19:56 +00002104 ... except UnexpectedException as f:
2105 ... failure = f
Tim Peters19397e52004-08-06 22:02:59 +00002106
2107 The UnexpectedException contains the test, the example, and
2108 the original exception:
2109
2110 >>> failure.test is test
2111 True
2112
2113 >>> failure.example.want
2114 '42\n'
2115
2116 >>> exc_info = failure.exc_info
Collin Winter828f04a2007-08-31 00:04:24 +00002117 >>> raise exc_info[1] # Already has the traceback
Tim Peters19397e52004-08-06 22:02:59 +00002118 Traceback (most recent call last):
2119 ...
2120 KeyError
2121
2122 If the output doesn't match, then a DocTestFailure is raised:
2123
Edward Lopera1ef6112004-08-09 16:14:41 +00002124 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00002125 ... >>> x = 1
2126 ... >>> x
2127 ... 2
2128 ... ''', {}, 'foo', 'foo.py', 0)
2129 >>> case = DocTestCase(test)
2130
2131 >>> try:
2132 ... case.debug()
Guido van Rossumb940e112007-01-10 16:19:56 +00002133 ... except DocTestFailure as f:
2134 ... failure = f
Tim Peters19397e52004-08-06 22:02:59 +00002135
2136 DocTestFailure objects provide access to the test:
2137
2138 >>> failure.test is test
2139 True
2140
2141 As well as to the example:
2142
2143 >>> failure.example.want
2144 '2\n'
2145
2146 and the actual output:
2147
2148 >>> failure.got
2149 '1\n'
2150
2151 """
2152
Jim Fultonf54bad42004-08-28 14:57:56 +00002153 self.setUp()
Edward Loper34fcb142004-08-09 02:45:41 +00002154 runner = DebugRunner(optionflags=self._dt_optionflags,
2155 checker=self._dt_checker, verbose=False)
Alexandre Vassalottieca20b62008-05-16 02:54:33 +00002156 runner.run(self._dt_test, clear_globs=False)
Jim Fultonf54bad42004-08-28 14:57:56 +00002157 self.tearDown()
Jim Fultona643b652004-07-14 19:06:50 +00002158
2159 def id(self):
Tim Peters19397e52004-08-06 22:02:59 +00002160 return self._dt_test.name
Jim Fultona643b652004-07-14 19:06:50 +00002161
2162 def __repr__(self):
Tim Peters19397e52004-08-06 22:02:59 +00002163 name = self._dt_test.name.split('.')
Jim Fultona643b652004-07-14 19:06:50 +00002164 return "%s (%s)" % (name[-1], '.'.join(name[:-1]))
2165
2166 __str__ = __repr__
2167
2168 def shortDescription(self):
Tim Peters19397e52004-08-06 22:02:59 +00002169 return "Doctest: " + self._dt_test.name
Jim Fultona643b652004-07-14 19:06:50 +00002170
Jim Fultonf54bad42004-08-28 14:57:56 +00002171def DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None,
2172 **options):
Tim Peters8485b562004-08-04 18:46:34 +00002173 """
Tim Peters75dc5e12004-08-22 17:50:45 +00002174 Convert doctest tests for a module to a unittest test suite.
Jim Fultona643b652004-07-14 19:06:50 +00002175
Tim Peters19397e52004-08-06 22:02:59 +00002176 This converts each documentation string in a module that
2177 contains doctest tests to a unittest test case. If any of the
2178 tests in a doc string fail, then the test case fails. An exception
2179 is raised showing the name of the file containing the test and a
Jim Fultona643b652004-07-14 19:06:50 +00002180 (sometimes approximate) line number.
2181
Tim Peters19397e52004-08-06 22:02:59 +00002182 The `module` argument provides the module to be tested. The argument
Jim Fultona643b652004-07-14 19:06:50 +00002183 can be either a module or a module name.
2184
2185 If no argument is given, the calling module is used.
Jim Fultonf54bad42004-08-28 14:57:56 +00002186
2187 A number of options may be provided as keyword arguments:
2188
Jim Fultonf54bad42004-08-28 14:57:56 +00002189 setUp
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002190 A set-up function. This is called before running the
Jim Fultonf54bad42004-08-28 14:57:56 +00002191 tests in each file. The setUp function will be passed a DocTest
2192 object. The setUp function can access the test globals as the
2193 globs attribute of the test passed.
2194
2195 tearDown
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002196 A tear-down function. This is called after running the
Jim Fultonf54bad42004-08-28 14:57:56 +00002197 tests in each file. The tearDown function will be passed a DocTest
2198 object. The tearDown function can access the test globals as the
2199 globs attribute of the test passed.
2200
2201 globs
2202 A dictionary containing initial global variables for the tests.
2203
2204 optionflags
2205 A set of doctest option flags expressed as an integer.
Jim Fultona643b652004-07-14 19:06:50 +00002206 """
Jim Fultona643b652004-07-14 19:06:50 +00002207
Tim Peters8485b562004-08-04 18:46:34 +00002208 if test_finder is None:
2209 test_finder = DocTestFinder()
Tim Peters8485b562004-08-04 18:46:34 +00002210
Tim Peters19397e52004-08-06 22:02:59 +00002211 module = _normalize_module(module)
2212 tests = test_finder.find(module, globs=globs, extraglobs=extraglobs)
Jim Fultonf54bad42004-08-28 14:57:56 +00002213 if not tests:
2214 # Why do we want to do this? Because it reveals a bug that might
2215 # otherwise be hidden.
Tim Peters19397e52004-08-06 22:02:59 +00002216 raise ValueError(module, "has no tests")
Tim Petersdb3756d2003-06-29 05:30:48 +00002217
2218 tests.sort()
2219 suite = unittest.TestSuite()
Tim Peters8485b562004-08-04 18:46:34 +00002220 for test in tests:
Tim Peters19397e52004-08-06 22:02:59 +00002221 if len(test.examples) == 0:
2222 continue
Tim Peters8485b562004-08-04 18:46:34 +00002223 if not test.filename:
Tim Petersdb3756d2003-06-29 05:30:48 +00002224 filename = module.__file__
Jim Fulton07a349c2004-08-22 14:10:00 +00002225 if filename[-4:] in (".pyc", ".pyo"):
Tim Petersdb3756d2003-06-29 05:30:48 +00002226 filename = filename[:-1]
Tim Peters8485b562004-08-04 18:46:34 +00002227 test.filename = filename
Jim Fultonf54bad42004-08-28 14:57:56 +00002228 suite.addTest(DocTestCase(test, **options))
Tim Peters19397e52004-08-06 22:02:59 +00002229
2230 return suite
2231
2232class DocFileCase(DocTestCase):
2233
2234 def id(self):
2235 return '_'.join(self._dt_test.name.split('.'))
2236
2237 def __repr__(self):
2238 return self._dt_test.filename
2239 __str__ = __repr__
2240
2241 def format_failure(self, err):
2242 return ('Failed doctest test for %s\n File "%s", line 0\n\n%s'
2243 % (self._dt_test.name, self._dt_test.filename, err)
2244 )
2245
Edward Loper052d0cd2004-09-19 17:19:33 +00002246def DocFileTest(path, module_relative=True, package=None,
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00002247 globs=None, parser=DocTestParser(),
2248 encoding=None, **options):
Tim Peters19397e52004-08-06 22:02:59 +00002249 if globs is None:
2250 globs = {}
Fred Drake7c404a42004-12-21 23:46:34 +00002251 else:
2252 globs = globs.copy()
Tim Peters19397e52004-08-06 22:02:59 +00002253
Edward Loper052d0cd2004-09-19 17:19:33 +00002254 if package and not module_relative:
2255 raise ValueError("Package may only be specified for module-"
2256 "relative paths.")
Tim Petersbab3e992004-09-20 19:52:34 +00002257
Edward Loper052d0cd2004-09-19 17:19:33 +00002258 # Relativize the path.
Guido van Rossum1b81e7b2007-08-29 03:53:53 +00002259 doc, path = _load_testfile(path, package, module_relative,
2260 encoding or "utf-8")
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00002261
Fred Drake7c404a42004-12-21 23:46:34 +00002262 if "__file__" not in globs:
2263 globs["__file__"] = path
Tim Peters19397e52004-08-06 22:02:59 +00002264
Edward Loper052d0cd2004-09-19 17:19:33 +00002265 # Find the file and read it.
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002266 name = os.path.basename(path)
Edward Loper052d0cd2004-09-19 17:19:33 +00002267
2268 # Convert it to a test, and wrap it in a DocFileCase.
Edward Loper498a1862004-09-27 03:42:58 +00002269 test = parser.get_doctest(doc, globs, name, path, 0)
Jim Fultonf54bad42004-08-28 14:57:56 +00002270 return DocFileCase(test, **options)
Tim Peters19397e52004-08-06 22:02:59 +00002271
2272def DocFileSuite(*paths, **kw):
Edward Loper052d0cd2004-09-19 17:19:33 +00002273 """A unittest suite for one or more doctest files.
Tim Petersbab3e992004-09-20 19:52:34 +00002274
Edward Loper052d0cd2004-09-19 17:19:33 +00002275 The path to each doctest file is given as a string; the
2276 interpretation of that string depends on the keyword argument
2277 "module_relative".
Tim Peters19397e52004-08-06 22:02:59 +00002278
2279 A number of options may be provided as keyword arguments:
2280
Edward Loper052d0cd2004-09-19 17:19:33 +00002281 module_relative
2282 If "module_relative" is True, then the given file paths are
2283 interpreted as os-independent module-relative paths. By
2284 default, these paths are relative to the calling module's
2285 directory; but if the "package" argument is specified, then
2286 they are relative to that package. To ensure os-independence,
2287 "filename" should use "/" characters to separate path
2288 segments, and may not be an absolute path (i.e., it may not
2289 begin with "/").
Tim Petersbab3e992004-09-20 19:52:34 +00002290
Edward Loper052d0cd2004-09-19 17:19:33 +00002291 If "module_relative" is False, then the given file paths are
2292 interpreted as os-specific paths. These paths may be absolute
2293 or relative (to the current working directory).
2294
Tim Peters19397e52004-08-06 22:02:59 +00002295 package
Edward Loper052d0cd2004-09-19 17:19:33 +00002296 A Python package or the name of a Python package whose directory
2297 should be used as the base directory for module relative paths.
2298 If "package" is not specified, then the calling module's
2299 directory is used as the base directory for module relative
2300 filenames. It is an error to specify "package" if
2301 "module_relative" is False.
Tim Peters19397e52004-08-06 22:02:59 +00002302
2303 setUp
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002304 A set-up function. This is called before running the
Jim Fultonf54bad42004-08-28 14:57:56 +00002305 tests in each file. The setUp function will be passed a DocTest
2306 object. The setUp function can access the test globals as the
2307 globs attribute of the test passed.
Tim Peters19397e52004-08-06 22:02:59 +00002308
2309 tearDown
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002310 A tear-down function. This is called after running the
Jim Fultonf54bad42004-08-28 14:57:56 +00002311 tests in each file. The tearDown function will be passed a DocTest
2312 object. The tearDown function can access the test globals as the
2313 globs attribute of the test passed.
Tim Peters19397e52004-08-06 22:02:59 +00002314
2315 globs
2316 A dictionary containing initial global variables for the tests.
Jim Fultonf54bad42004-08-28 14:57:56 +00002317
2318 optionflags
Edward Loper498a1862004-09-27 03:42:58 +00002319 A set of doctest option flags expressed as an integer.
2320
2321 parser
2322 A DocTestParser (or subclass) that should be used to extract
2323 tests from the files.
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00002324
2325 encoding
2326 An encoding that will be used to convert the files to unicode.
Tim Peters19397e52004-08-06 22:02:59 +00002327 """
2328 suite = unittest.TestSuite()
2329
2330 # We do this here so that _normalize_module is called at the right
2331 # level. If it were called in DocFileTest, then this function
2332 # would be the caller and we might guess the package incorrectly.
Edward Loper052d0cd2004-09-19 17:19:33 +00002333 if kw.get('module_relative', True):
2334 kw['package'] = _normalize_module(kw.get('package'))
Tim Peters19397e52004-08-06 22:02:59 +00002335
2336 for path in paths:
2337 suite.addTest(DocFileTest(path, **kw))
Jim Fultona643b652004-07-14 19:06:50 +00002338
Tim Petersdb3756d2003-06-29 05:30:48 +00002339 return suite
2340
Tim Peters8485b562004-08-04 18:46:34 +00002341######################################################################
Georg Brandl31835852008-05-12 17:38:56 +00002342## 8. Debugging Support
Tim Peters8485b562004-08-04 18:46:34 +00002343######################################################################
Jim Fultona643b652004-07-14 19:06:50 +00002344
Tim Peters19397e52004-08-06 22:02:59 +00002345def script_from_examples(s):
2346 r"""Extract script from text with examples.
2347
2348 Converts text with examples to a Python script. Example input is
2349 converted to regular code. Example output and all other words
2350 are converted to comments:
2351
2352 >>> text = '''
2353 ... Here are examples of simple math.
2354 ...
2355 ... Python has super accurate integer addition
2356 ...
2357 ... >>> 2 + 2
2358 ... 5
2359 ...
2360 ... And very friendly error messages:
2361 ...
2362 ... >>> 1/0
2363 ... To Infinity
2364 ... And
2365 ... Beyond
2366 ...
2367 ... You can use logic if you want:
2368 ...
2369 ... >>> if 0:
2370 ... ... blah
2371 ... ... blah
2372 ... ...
2373 ...
2374 ... Ho hum
2375 ... '''
2376
Guido van Rossum7131f842007-02-09 20:13:25 +00002377 >>> print(script_from_examples(text))
Edward Lopera5db6002004-08-12 02:41:30 +00002378 # Here are examples of simple math.
Tim Peters19397e52004-08-06 22:02:59 +00002379 #
Edward Lopera5db6002004-08-12 02:41:30 +00002380 # Python has super accurate integer addition
Tim Peters19397e52004-08-06 22:02:59 +00002381 #
2382 2 + 2
2383 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +00002384 ## 5
Tim Peters19397e52004-08-06 22:02:59 +00002385 #
Edward Lopera5db6002004-08-12 02:41:30 +00002386 # And very friendly error messages:
Tim Peters19397e52004-08-06 22:02:59 +00002387 #
2388 1/0
2389 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +00002390 ## To Infinity
2391 ## And
2392 ## Beyond
Tim Peters19397e52004-08-06 22:02:59 +00002393 #
Edward Lopera5db6002004-08-12 02:41:30 +00002394 # You can use logic if you want:
Tim Peters19397e52004-08-06 22:02:59 +00002395 #
2396 if 0:
2397 blah
2398 blah
Tim Peters19397e52004-08-06 22:02:59 +00002399 #
Edward Lopera5db6002004-08-12 02:41:30 +00002400 # Ho hum
Georg Brandlecf93c72005-06-26 23:09:51 +00002401 <BLANKLINE>
Tim Peters19397e52004-08-06 22:02:59 +00002402 """
Edward Loper00f8da72004-08-26 18:05:07 +00002403 output = []
2404 for piece in DocTestParser().parse(s):
2405 if isinstance(piece, Example):
2406 # Add the example's source code (strip trailing NL)
2407 output.append(piece.source[:-1])
2408 # Add the expected output:
2409 want = piece.want
2410 if want:
2411 output.append('# Expected:')
2412 output += ['## '+l for l in want.split('\n')[:-1]]
2413 else:
2414 # Add non-example text.
2415 output += [_comment_line(l)
2416 for l in piece.split('\n')[:-1]]
Tim Peters19397e52004-08-06 22:02:59 +00002417
Edward Loper00f8da72004-08-26 18:05:07 +00002418 # Trim junk on both ends.
2419 while output and output[-1] == '#':
2420 output.pop()
2421 while output and output[0] == '#':
2422 output.pop(0)
2423 # Combine the output, and return it.
Georg Brandl1f149642005-06-26 22:22:31 +00002424 # Add a courtesy newline to prevent exec from choking (see bug #1172785)
2425 return '\n'.join(output) + '\n'
Tim Petersdb3756d2003-06-29 05:30:48 +00002426
2427def testsource(module, name):
Tim Peters19397e52004-08-06 22:02:59 +00002428 """Extract the test sources from a doctest docstring as a script.
Tim Petersdb3756d2003-06-29 05:30:48 +00002429
2430 Provide the module (or dotted name of the module) containing the
Jim Fultona643b652004-07-14 19:06:50 +00002431 test to be debugged and the name (within the module) of the object
2432 with the doc string with tests to be debugged.
Tim Petersdb3756d2003-06-29 05:30:48 +00002433 """
Tim Peters8485b562004-08-04 18:46:34 +00002434 module = _normalize_module(module)
2435 tests = DocTestFinder().find(module)
2436 test = [t for t in tests if t.name == name]
Tim Petersdb3756d2003-06-29 05:30:48 +00002437 if not test:
2438 raise ValueError(name, "not found in tests")
2439 test = test[0]
Tim Peters19397e52004-08-06 22:02:59 +00002440 testsrc = script_from_examples(test.docstring)
Jim Fultona643b652004-07-14 19:06:50 +00002441 return testsrc
Tim Petersdb3756d2003-06-29 05:30:48 +00002442
Jim Fultona643b652004-07-14 19:06:50 +00002443def debug_src(src, pm=False, globs=None):
Tim Peters19397e52004-08-06 22:02:59 +00002444 """Debug a single doctest docstring, in argument `src`'"""
2445 testsrc = script_from_examples(src)
Tim Peters8485b562004-08-04 18:46:34 +00002446 debug_script(testsrc, pm, globs)
Tim Petersdb3756d2003-06-29 05:30:48 +00002447
Jim Fultona643b652004-07-14 19:06:50 +00002448def debug_script(src, pm=False, globs=None):
Tim Peters19397e52004-08-06 22:02:59 +00002449 "Debug a test script. `src` is the script, as a string."
Tim Petersdb3756d2003-06-29 05:30:48 +00002450 import pdb
Tim Petersdb3756d2003-06-29 05:30:48 +00002451
Tim Petersb6a04d62004-08-23 21:37:56 +00002452 # Note that tempfile.NameTemporaryFile() cannot be used. As the
2453 # docs say, a file so created cannot be opened by name a second time
Neal Norwitz01688022007-08-12 00:43:29 +00002454 # on modern Windows boxes, and exec() needs to open and read it.
Tim Petersb6a04d62004-08-23 21:37:56 +00002455 srcfilename = tempfile.mktemp(".py", "doctestdebug")
Tim Peters8485b562004-08-04 18:46:34 +00002456 f = open(srcfilename, 'w')
2457 f.write(src)
2458 f.close()
2459
Tim Petersb6a04d62004-08-23 21:37:56 +00002460 try:
2461 if globs:
2462 globs = globs.copy()
2463 else:
2464 globs = {}
Tim Petersdb3756d2003-06-29 05:30:48 +00002465
Tim Petersb6a04d62004-08-23 21:37:56 +00002466 if pm:
2467 try:
Neal Norwitz01688022007-08-12 00:43:29 +00002468 exec(open(srcfilename).read(), globs, globs)
Tim Petersb6a04d62004-08-23 21:37:56 +00002469 except:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00002470 print(sys.exc_info()[1])
Tim Petersb6a04d62004-08-23 21:37:56 +00002471 pdb.post_mortem(sys.exc_info()[2])
2472 else:
Neal Norwitz01688022007-08-12 00:43:29 +00002473 fp = open(srcfilename)
2474 try:
2475 script = fp.read()
2476 finally:
2477 fp.close()
2478 pdb.run("exec(%r)" % script, globs, globs)
Tim Petersb6a04d62004-08-23 21:37:56 +00002479
2480 finally:
2481 os.remove(srcfilename)
Tim Petersdb3756d2003-06-29 05:30:48 +00002482
Jim Fultona643b652004-07-14 19:06:50 +00002483def debug(module, name, pm=False):
Tim Peters19397e52004-08-06 22:02:59 +00002484 """Debug a single doctest docstring.
Jim Fultona643b652004-07-14 19:06:50 +00002485
2486 Provide the module (or dotted name of the module) containing the
2487 test to be debugged and the name (within the module) of the object
Tim Peters19397e52004-08-06 22:02:59 +00002488 with the docstring with tests to be debugged.
Jim Fultona643b652004-07-14 19:06:50 +00002489 """
Tim Peters8485b562004-08-04 18:46:34 +00002490 module = _normalize_module(module)
Jim Fultona643b652004-07-14 19:06:50 +00002491 testsrc = testsource(module, name)
2492 debug_script(testsrc, pm, module.__dict__)
2493
Tim Peters8485b562004-08-04 18:46:34 +00002494######################################################################
Georg Brandl31835852008-05-12 17:38:56 +00002495## 9. Example Usage
Tim Peters8485b562004-08-04 18:46:34 +00002496######################################################################
Tim Peters8a7d2d52001-01-16 07:10:57 +00002497class _TestClass:
2498 """
2499 A pointless class, for sanity-checking of docstring testing.
2500
2501 Methods:
2502 square()
2503 get()
2504
2505 >>> _TestClass(13).get() + _TestClass(-12).get()
2506 1
2507 >>> hex(_TestClass(13).square().get())
2508 '0xa9'
2509 """
2510
2511 def __init__(self, val):
2512 """val -> _TestClass object with associated value val.
2513
2514 >>> t = _TestClass(123)
Guido van Rossum7131f842007-02-09 20:13:25 +00002515 >>> print(t.get())
Tim Peters8a7d2d52001-01-16 07:10:57 +00002516 123
2517 """
2518
2519 self.val = val
2520
2521 def square(self):
2522 """square() -> square TestClass's associated value
2523
2524 >>> _TestClass(13).square().get()
2525 169
2526 """
2527
2528 self.val = self.val ** 2
2529 return self
2530
2531 def get(self):
2532 """get() -> return TestClass's associated value.
2533
2534 >>> x = _TestClass(-42)
Guido van Rossum7131f842007-02-09 20:13:25 +00002535 >>> print(x.get())
Tim Peters8a7d2d52001-01-16 07:10:57 +00002536 -42
2537 """
2538
2539 return self.val
2540
2541__test__ = {"_TestClass": _TestClass,
2542 "string": r"""
2543 Example of a string object, searched as-is.
2544 >>> x = 1; y = 2
2545 >>> x + y, x * y
2546 (3, 2)
Tim Peters6ebe61f2003-06-27 20:48:05 +00002547 """,
Tim Peters3fa8c202004-08-23 21:43:39 +00002548
Tim Peters6ebe61f2003-06-27 20:48:05 +00002549 "bool-int equivalence": r"""
2550 In 2.2, boolean expressions displayed
2551 0 or 1. By default, we still accept
2552 them. This can be disabled by passing
2553 DONT_ACCEPT_TRUE_FOR_1 to the new
2554 optionflags argument.
2555 >>> 4 == 4
2556 1
2557 >>> 4 == 4
2558 True
2559 >>> 4 > 4
2560 0
2561 >>> 4 > 4
2562 False
2563 """,
Tim Peters3fa8c202004-08-23 21:43:39 +00002564
Tim Peters8485b562004-08-04 18:46:34 +00002565 "blank lines": r"""
Tim Peters3fa8c202004-08-23 21:43:39 +00002566 Blank lines can be marked with <BLANKLINE>:
Guido van Rossum7131f842007-02-09 20:13:25 +00002567 >>> print('foo\n\nbar\n')
Tim Peters3fa8c202004-08-23 21:43:39 +00002568 foo
2569 <BLANKLINE>
2570 bar
2571 <BLANKLINE>
Tim Peters8485b562004-08-04 18:46:34 +00002572 """,
Tim Peters3fa8c202004-08-23 21:43:39 +00002573
2574 "ellipsis": r"""
2575 If the ellipsis flag is used, then '...' can be used to
2576 elide substrings in the desired output:
Guido van Rossum805365e2007-05-07 22:24:25 +00002577 >>> print(list(range(1000))) #doctest: +ELLIPSIS
Tim Peters3fa8c202004-08-23 21:43:39 +00002578 [0, 1, 2, ..., 999]
2579 """,
2580
2581 "whitespace normalization": r"""
2582 If the whitespace normalization flag is used, then
2583 differences in whitespace are ignored.
Guido van Rossum805365e2007-05-07 22:24:25 +00002584 >>> print(list(range(30))) #doctest: +NORMALIZE_WHITESPACE
Tim Peters3fa8c202004-08-23 21:43:39 +00002585 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
2586 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,
2587 27, 28, 29]
2588 """,
2589 }
Tim Peters8485b562004-08-04 18:46:34 +00002590
Tim Peters8a7d2d52001-01-16 07:10:57 +00002591def _test():
Guido van Rossumd8faa362007-04-27 19:54:29 +00002592 testfiles = [arg for arg in sys.argv[1:] if arg and arg[0] != '-']
2593 if testfiles:
2594 for filename in testfiles:
2595 if filename.endswith(".py"):
2596 # It is a module -- insert its dir into sys.path and try to
2597 # import it. If it is part of a package, that possibly won't work
2598 # because of package imports.
2599 dirname, filename = os.path.split(filename)
2600 sys.path.insert(0, dirname)
2601 m = __import__(filename[:-3])
2602 del sys.path[0]
Christian Heimes895627f2007-12-08 17:28:33 +00002603 failures, _ = testmod(m)
Guido van Rossumd8faa362007-04-27 19:54:29 +00002604 else:
Christian Heimes895627f2007-12-08 17:28:33 +00002605 failures, _ = testfile(filename, module_relative=False)
2606 if failures:
2607 return 1
Guido van Rossumd8faa362007-04-27 19:54:29 +00002608 else:
2609 r = unittest.TextTestRunner()
2610 r.run(DocTestSuite())
Christian Heimes895627f2007-12-08 17:28:33 +00002611 return 0
Tim Peters8a7d2d52001-01-16 07:10:57 +00002612
2613if __name__ == "__main__":
Christian Heimes895627f2007-12-08 17:28:33 +00002614 sys.exit(_test())