blob: fcfcbb037b7b900111a5773cb0549b4eb2210c29 [file] [log] [blame]
Tim Peters4fd9e2f2001-08-18 00:05:50 +00001# Module doctest.
Tim Peters8485b562004-08-04 18:46:34 +00002# Released to the public domain 16-Jan-2001, by Tim Peters (tim@python.org).
Tim Peters19397e52004-08-06 22:02:59 +00003# Major enhancements and refactoring by:
Tim Peters8485b562004-08-04 18:46:34 +00004# Jim Fulton
5# Edward Loper
Tim Peters8a7d2d52001-01-16 07:10:57 +00006
7# Provided as-is; use at your own risk; no warranty; no promises; enjoy!
8
Martin v. Löwis92816de2004-05-31 19:01:00 +00009r"""Module doctest -- a framework for running examples in docstrings.
Tim Peters8a7d2d52001-01-16 07:10:57 +000010
Tim Peters80e53142004-08-09 04:34:45 +000011In simplest use, end each module M to be tested with:
Tim Peters8a7d2d52001-01-16 07:10:57 +000012
13def _test():
Tim Peters80e53142004-08-09 04:34:45 +000014 import doctest
Tim Peters48983fc2004-09-25 02:41:28 +000015 doctest.testmod()
Tim Peters8a7d2d52001-01-16 07:10:57 +000016
17if __name__ == "__main__":
18 _test()
19
20Then running the module as a script will cause the examples in the
21docstrings to get executed and verified:
22
23python M.py
24
25This won't display anything unless an example fails, in which case the
26failing example(s) and the cause(s) of the failure(s) are printed to stdout
27(why not stderr? because stderr is a lame hack <0.2 wink>), and the final
28line of output is "Test failed.".
29
30Run it with the -v switch instead:
31
32python M.py -v
33
34and a detailed report of all examples tried is printed to stdout, along
35with assorted summaries at the end.
36
Tim Peters80e53142004-08-09 04:34:45 +000037You can force verbose mode by passing "verbose=True" to testmod, or prohibit
38it by passing "verbose=False". In either of those cases, sys.argv is not
Tim Peters8a7d2d52001-01-16 07:10:57 +000039examined by testmod.
40
Tim Peters80e53142004-08-09 04:34:45 +000041There are a variety of other ways to run doctests, including integration
42with the unittest framework, and support for running non-Python text
43files containing doctests. There are also many ways to override parts
44of doctest's default behaviors. See the Library Reference Manual for
45details.
Tim Peters8a7d2d52001-01-16 07:10:57 +000046"""
Tim Peters48983fc2004-09-25 02:41:28 +000047
Edward Loper8e4a34b2004-08-12 02:34:27 +000048__docformat__ = 'reStructuredText en'
Tim Peters8a7d2d52001-01-16 07:10:57 +000049
Tim Peters4fd9e2f2001-08-18 00:05:50 +000050__all__ = [
Edward Loperb7503ff2004-08-19 19:19:03 +000051 # 0, Option Flags
52 'register_optionflag',
53 'DONT_ACCEPT_TRUE_FOR_1',
54 'DONT_ACCEPT_BLANKLINE',
55 'NORMALIZE_WHITESPACE',
56 'ELLIPSIS',
Thomas Wouters477c8d52006-05-27 19:21:47 +000057 'SKIP',
Tim Peters1fbf9c52004-09-04 17:21:02 +000058 'IGNORE_EXCEPTION_DETAIL',
Tim Petersba601962004-09-04 15:04:06 +000059 'COMPARISON_FLAGS',
Edward Loper71f55af2004-08-26 01:41:51 +000060 'REPORT_UDIFF',
61 'REPORT_CDIFF',
62 'REPORT_NDIFF',
Jim Fultonf54bad42004-08-28 14:57:56 +000063 'REPORT_ONLY_FIRST_FAILURE',
Tim Petersba601962004-09-04 15:04:06 +000064 'REPORTING_FLAGS',
R David Murray5a9d7062012-11-21 15:09:21 -050065 'FAIL_FAST',
Edward Loperb7503ff2004-08-19 19:19:03 +000066 # 1. Utility Functions
Edward Loperb7503ff2004-08-19 19:19:03 +000067 # 2. Example & DocTest
Tim Peters8485b562004-08-04 18:46:34 +000068 'Example',
69 'DocTest',
Edward Loperb7503ff2004-08-19 19:19:03 +000070 # 3. Doctest Parser
71 'DocTestParser',
72 # 4. Doctest Finder
Tim Peters8485b562004-08-04 18:46:34 +000073 'DocTestFinder',
Edward Loperb7503ff2004-08-19 19:19:03 +000074 # 5. Doctest Runner
Tim Peters8485b562004-08-04 18:46:34 +000075 'DocTestRunner',
Edward Loperb7503ff2004-08-19 19:19:03 +000076 'OutputChecker',
77 'DocTestFailure',
78 'UnexpectedException',
79 'DebugRunner',
80 # 6. Test Functions
Tim Peters4fd9e2f2001-08-18 00:05:50 +000081 'testmod',
Edward Loper052d0cd2004-09-19 17:19:33 +000082 'testfile',
Tim Peters4fd9e2f2001-08-18 00:05:50 +000083 'run_docstring_examples',
Georg Brandlcc80bfe2008-05-12 18:06:23 +000084 # 7. Unittest Support
Tim Petersdb3756d2003-06-29 05:30:48 +000085 'DocTestSuite',
Edward Loperb7503ff2004-08-19 19:19:03 +000086 'DocFileSuite',
Tim Peters9d02a7c2004-09-26 01:50:24 +000087 'set_unittest_reportflags',
Georg Brandlcc80bfe2008-05-12 18:06:23 +000088 # 8. Debugging Support
Edward Loperb7503ff2004-08-19 19:19:03 +000089 'script_from_examples',
Tim Petersdb3756d2003-06-29 05:30:48 +000090 'testsource',
Edward Loperb7503ff2004-08-19 19:19:03 +000091 'debug_src',
Tim Petersdb3756d2003-06-29 05:30:48 +000092 'debug',
Tim Peters4fd9e2f2001-08-18 00:05:50 +000093]
Tim Peters8a7d2d52001-01-16 07:10:57 +000094
Tim Peters4fd9e2f2001-08-18 00:05:50 +000095import __future__
R David Murray5707d502013-06-23 14:24:13 -040096import argparse
Victor Stinner12b8d142011-06-30 17:35:55 +020097import difflib
98import inspect
99import linecache
100import os
101import pdb
102import re
103import sys
104import traceback
105import unittest
Guido van Rossum34d19282007-08-09 01:03:29 +0000106from io import StringIO
Christian Heimes25bb7832008-01-11 16:17:00 +0000107from collections import namedtuple
108
109TestResults = namedtuple('TestResults', 'failed attempted')
Tim Peters7402f792001-10-02 03:53:41 +0000110
Tim Peters19397e52004-08-06 22:02:59 +0000111# There are 4 basic classes:
112# - Example: a <source, want> pair, plus an intra-docstring line number.
113# - DocTest: a collection of examples, parsed from a docstring, plus
114# info about where the docstring came from (name, filename, lineno).
115# - DocTestFinder: extracts DocTests from a given object's docstring and
116# its contained objects' docstrings.
117# - DocTestRunner: runs DocTest cases, and accumulates statistics.
118#
119# So the basic picture is:
120#
121# list of:
122# +------+ +---------+ +-------+
123# |object| --DocTestFinder-> | DocTest | --DocTestRunner-> |results|
124# +------+ +---------+ +-------+
125# | Example |
126# | ... |
127# | Example |
128# +---------+
129
Edward Loperac20f572004-08-12 02:02:24 +0000130# Option constants.
Tim Peters38330fe2004-08-30 16:19:24 +0000131
Edward Loperac20f572004-08-12 02:02:24 +0000132OPTIONFLAGS_BY_NAME = {}
133def register_optionflag(name):
Thomas Wouters477c8d52006-05-27 19:21:47 +0000134 # Create a new flag unless `name` is already known.
135 return OPTIONFLAGS_BY_NAME.setdefault(name, 1 << len(OPTIONFLAGS_BY_NAME))
Edward Loperac20f572004-08-12 02:02:24 +0000136
137DONT_ACCEPT_TRUE_FOR_1 = register_optionflag('DONT_ACCEPT_TRUE_FOR_1')
138DONT_ACCEPT_BLANKLINE = register_optionflag('DONT_ACCEPT_BLANKLINE')
139NORMALIZE_WHITESPACE = register_optionflag('NORMALIZE_WHITESPACE')
140ELLIPSIS = register_optionflag('ELLIPSIS')
Thomas Wouters477c8d52006-05-27 19:21:47 +0000141SKIP = register_optionflag('SKIP')
Tim Peters1fbf9c52004-09-04 17:21:02 +0000142IGNORE_EXCEPTION_DETAIL = register_optionflag('IGNORE_EXCEPTION_DETAIL')
Tim Peters38330fe2004-08-30 16:19:24 +0000143
144COMPARISON_FLAGS = (DONT_ACCEPT_TRUE_FOR_1 |
145 DONT_ACCEPT_BLANKLINE |
146 NORMALIZE_WHITESPACE |
Tim Peters1fbf9c52004-09-04 17:21:02 +0000147 ELLIPSIS |
Thomas Wouters477c8d52006-05-27 19:21:47 +0000148 SKIP |
Edward Loper7d88a582004-09-28 05:50:57 +0000149 IGNORE_EXCEPTION_DETAIL)
Tim Peters38330fe2004-08-30 16:19:24 +0000150
Edward Loper71f55af2004-08-26 01:41:51 +0000151REPORT_UDIFF = register_optionflag('REPORT_UDIFF')
152REPORT_CDIFF = register_optionflag('REPORT_CDIFF')
153REPORT_NDIFF = register_optionflag('REPORT_NDIFF')
Edward Lopera89f88d2004-08-26 02:45:51 +0000154REPORT_ONLY_FIRST_FAILURE = register_optionflag('REPORT_ONLY_FIRST_FAILURE')
R David Murray5a9d7062012-11-21 15:09:21 -0500155FAIL_FAST = register_optionflag('FAIL_FAST')
Edward Loperac20f572004-08-12 02:02:24 +0000156
Tim Peters38330fe2004-08-30 16:19:24 +0000157REPORTING_FLAGS = (REPORT_UDIFF |
158 REPORT_CDIFF |
159 REPORT_NDIFF |
R David Murray5a9d7062012-11-21 15:09:21 -0500160 REPORT_ONLY_FIRST_FAILURE |
161 FAIL_FAST)
Tim Peters38330fe2004-08-30 16:19:24 +0000162
Edward Loperac20f572004-08-12 02:02:24 +0000163# Special string markers for use in `want` strings:
164BLANKLINE_MARKER = '<BLANKLINE>'
165ELLIPSIS_MARKER = '...'
166
Tim Peters8485b562004-08-04 18:46:34 +0000167######################################################################
168## Table of Contents
169######################################################################
Edward Loper7c748462004-08-09 02:06:06 +0000170# 1. Utility Functions
171# 2. Example & DocTest -- store test cases
172# 3. DocTest Parser -- extracts examples from strings
173# 4. DocTest Finder -- extracts test cases from objects
174# 5. DocTest Runner -- runs test cases
175# 6. Test Functions -- convenient wrappers for testing
Georg Brandl31835852008-05-12 17:38:56 +0000176# 7. Unittest Support
177# 8. Debugging Support
178# 9. Example Usage
Tim Peters8a7d2d52001-01-16 07:10:57 +0000179
Tim Peters8485b562004-08-04 18:46:34 +0000180######################################################################
181## 1. Utility Functions
182######################################################################
Tim Peters8a7d2d52001-01-16 07:10:57 +0000183
Tim Peters8485b562004-08-04 18:46:34 +0000184def _extract_future_flags(globs):
185 """
186 Return the compiler-flags associated with the future features that
187 have been imported into the given namespace (globs).
188 """
189 flags = 0
190 for fname in __future__.all_feature_names:
191 feature = globs.get(fname, None)
192 if feature is getattr(__future__, fname):
193 flags |= feature.compiler_flag
194 return flags
Tim Peters7402f792001-10-02 03:53:41 +0000195
Tim Peters8485b562004-08-04 18:46:34 +0000196def _normalize_module(module, depth=2):
197 """
198 Return the module specified by `module`. In particular:
199 - If `module` is a module, then return module.
200 - If `module` is a string, then import and return the
201 module with that name.
202 - If `module` is None, then return the calling module.
203 The calling module is assumed to be the module of
204 the stack frame at the given depth in the call stack.
205 """
206 if inspect.ismodule(module):
207 return module
Walter Dörwaldaa97f042007-05-03 21:05:51 +0000208 elif isinstance(module, str):
Tim Peters8485b562004-08-04 18:46:34 +0000209 return __import__(module, globals(), locals(), ["*"])
210 elif module is None:
211 return sys.modules[sys._getframe(depth).f_globals['__name__']]
212 else:
213 raise TypeError("Expected a module, string, or None")
Tim Peters7402f792001-10-02 03:53:41 +0000214
Guido van Rossum1b81e7b2007-08-29 03:53:53 +0000215def _load_testfile(filename, package, module_relative, encoding):
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000216 if module_relative:
217 package = _normalize_module(package, 3)
218 filename = _module_relative_path(package, filename)
Brett Cannon4c14b5d2013-05-04 13:56:58 -0400219 if getattr(package, '__loader__', None) is not None:
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000220 if hasattr(package.__loader__, 'get_data'):
Guido van Rossumcd4d4522007-11-22 00:30:02 +0000221 file_contents = package.__loader__.get_data(filename)
222 file_contents = file_contents.decode(encoding)
223 # get_data() opens files as 'rb', so one must do the equivalent
224 # conversion as universal newlines would do.
225 return file_contents.replace(os.linesep, '\n'), filename
Antoine Pitrou92f60ed2010-10-14 22:11:44 +0000226 with open(filename, encoding=encoding) as f:
227 return f.read(), filename
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000228
Edward Loperaacf0832004-08-26 01:19:50 +0000229def _indent(s, indent=4):
Tim Peters8485b562004-08-04 18:46:34 +0000230 """
Florent Xicluna59250852010-02-27 14:21:57 +0000231 Add the given number of space characters to the beginning of
232 every non-blank line in `s`, and return the result.
Tim Peters8485b562004-08-04 18:46:34 +0000233 """
Edward Loperaacf0832004-08-26 01:19:50 +0000234 # This regexp matches the start of non-blank lines:
235 return re.sub('(?m)^(?!$)', indent*' ', s)
Tim Peters8a7d2d52001-01-16 07:10:57 +0000236
Edward Loper8e4a34b2004-08-12 02:34:27 +0000237def _exception_traceback(exc_info):
238 """
239 Return a string containing a traceback message for the given
240 exc_info tuple (as returned by sys.exc_info()).
241 """
242 # Get a traceback message.
243 excout = StringIO()
244 exc_type, exc_val, exc_tb = exc_info
245 traceback.print_exception(exc_type, exc_val, exc_tb, file=excout)
246 return excout.getvalue()
247
Tim Peters8485b562004-08-04 18:46:34 +0000248# Override some StringIO methods.
249class _SpoofOut(StringIO):
250 def getvalue(self):
251 result = StringIO.getvalue(self)
252 # If anything at all was written, make sure there's a trailing
253 # newline. There's no way for the expected output to indicate
254 # that a trailing newline is missing.
255 if result and not result.endswith("\n"):
256 result += "\n"
Tim Peters8485b562004-08-04 18:46:34 +0000257 return result
Tim Peters8a7d2d52001-01-16 07:10:57 +0000258
Guido van Rossum79139b22007-02-09 23:20:19 +0000259 def truncate(self, size=None):
Antoine Pitroub3d77002010-01-31 23:12:29 +0000260 self.seek(size)
261 StringIO.truncate(self)
Tim Peters8a7d2d52001-01-16 07:10:57 +0000262
Tim Peters26b3ebb2004-08-19 08:10:08 +0000263# Worst-case linear-time ellipsis matching.
Tim Petersb0a04e12004-08-20 02:08:04 +0000264def _ellipsis_match(want, got):
Tim Petersdc5de3b2004-08-19 14:06:20 +0000265 """
266 Essentially the only subtle case:
Tim Petersb0a04e12004-08-20 02:08:04 +0000267 >>> _ellipsis_match('aa...aa', 'aaa')
Tim Petersdc5de3b2004-08-19 14:06:20 +0000268 False
269 """
Tim Peters26b3ebb2004-08-19 08:10:08 +0000270 if ELLIPSIS_MARKER not in want:
271 return want == got
Tim Petersdc5de3b2004-08-19 14:06:20 +0000272
Tim Peters26b3ebb2004-08-19 08:10:08 +0000273 # Find "the real" strings.
274 ws = want.split(ELLIPSIS_MARKER)
275 assert len(ws) >= 2
Tim Peters26b3ebb2004-08-19 08:10:08 +0000276
Tim Petersdc5de3b2004-08-19 14:06:20 +0000277 # Deal with exact matches possibly needed at one or both ends.
278 startpos, endpos = 0, len(got)
279 w = ws[0]
280 if w: # starts with exact match
281 if got.startswith(w):
282 startpos = len(w)
283 del ws[0]
284 else:
285 return False
286 w = ws[-1]
287 if w: # ends with exact match
288 if got.endswith(w):
289 endpos -= len(w)
290 del ws[-1]
291 else:
292 return False
293
294 if startpos > endpos:
295 # Exact end matches required more characters than we have, as in
Tim Petersb0a04e12004-08-20 02:08:04 +0000296 # _ellipsis_match('aa...aa', 'aaa')
Tim Petersdc5de3b2004-08-19 14:06:20 +0000297 return False
298
299 # For the rest, we only need to find the leftmost non-overlapping
300 # match for each piece. If there's no overall match that way alone,
301 # there's no overall match period.
Tim Peters26b3ebb2004-08-19 08:10:08 +0000302 for w in ws:
303 # w may be '' at times, if there are consecutive ellipses, or
304 # due to an ellipsis at the start or end of `want`. That's OK.
Tim Petersdc5de3b2004-08-19 14:06:20 +0000305 # Search for an empty string succeeds, and doesn't change startpos.
306 startpos = got.find(w, startpos, endpos)
307 if startpos < 0:
Tim Peters26b3ebb2004-08-19 08:10:08 +0000308 return False
Tim Petersdc5de3b2004-08-19 14:06:20 +0000309 startpos += len(w)
Tim Peters26b3ebb2004-08-19 08:10:08 +0000310
Tim Petersdc5de3b2004-08-19 14:06:20 +0000311 return True
Tim Peters26b3ebb2004-08-19 08:10:08 +0000312
Edward Loper00f8da72004-08-26 18:05:07 +0000313def _comment_line(line):
314 "Return a commented form of the given line"
315 line = line.rstrip()
316 if line:
317 return '# '+line
318 else:
319 return '#'
320
Tim Petersf9a07f22013-12-03 21:02:05 -0600321def _strip_exception_details(msg):
322 # Support for IGNORE_EXCEPTION_DETAIL.
323 # Get rid of everything except the exception name; in particular, drop
324 # the possibly dotted module path (if any) and the exception message (if
325 # any). We assume that a colon is never part of a dotted name, or of an
326 # exception name.
327 # E.g., given
328 # "foo.bar.MyError: la di da"
329 # return "MyError"
330 # Or for "abc.def" or "abc.def:\n" return "def".
331
332 start, end = 0, len(msg)
333 # The exception name must appear on the first line.
334 i = msg.find("\n")
335 if i >= 0:
336 end = i
337 # retain up to the first colon (if any)
338 i = msg.find(':', 0, end)
339 if i >= 0:
340 end = i
341 # retain just the exception name
342 i = msg.rfind('.', 0, end)
343 if i >= 0:
344 start = i+1
345 return msg[start: end]
346
Edward Loper2de91ba2004-08-27 02:07:46 +0000347class _OutputRedirectingPdb(pdb.Pdb):
348 """
349 A specialized version of the python debugger that redirects stdout
350 to a given stream when interacting with the user. Stdout is *not*
351 redirected when traced code is executed.
352 """
353 def __init__(self, out):
354 self.__out = out
Guido van Rossum0d3fb8a2007-11-26 23:23:18 +0000355 self.__debugger_used = False
Georg Brandl34748cd2010-12-04 17:11:36 +0000356 # do not play signal games in the pdb
357 pdb.Pdb.__init__(self, stdout=out, nosigint=True)
Georg Brandld72e0432010-07-30 09:59:28 +0000358 # still use input() to get user input
359 self.use_rawinput = 1
Edward Loper2de91ba2004-08-27 02:07:46 +0000360
Guido van Rossum0d3fb8a2007-11-26 23:23:18 +0000361 def set_trace(self, frame=None):
362 self.__debugger_used = True
363 if frame is None:
364 frame = sys._getframe().f_back
365 pdb.Pdb.set_trace(self, frame)
366
367 def set_continue(self):
368 # Calling set_continue unconditionally would break unit test
369 # coverage reporting, as Bdb.set_continue calls sys.settrace(None).
370 if self.__debugger_used:
371 pdb.Pdb.set_continue(self)
372
Edward Loper2de91ba2004-08-27 02:07:46 +0000373 def trace_dispatch(self, *args):
374 # Redirect stdout to the given stream.
375 save_stdout = sys.stdout
376 sys.stdout = self.__out
377 # Call Pdb's trace dispatch method.
Tim Petersd7bbbbc2004-11-08 22:30:28 +0000378 try:
379 return pdb.Pdb.trace_dispatch(self, *args)
380 finally:
Tim Petersd7bbbbc2004-11-08 22:30:28 +0000381 sys.stdout = save_stdout
Edward Loper2de91ba2004-08-27 02:07:46 +0000382
Edward Lopera2fc7ec2004-09-21 03:24:24 +0000383# [XX] Normalize with respect to os.path.pardir?
Edward Loper052d0cd2004-09-19 17:19:33 +0000384def _module_relative_path(module, path):
385 if not inspect.ismodule(module):
Collin Winterce36ad82007-08-30 01:19:48 +0000386 raise TypeError('Expected a module: %r' % module)
Edward Loper052d0cd2004-09-19 17:19:33 +0000387 if path.startswith('/'):
Collin Winterce36ad82007-08-30 01:19:48 +0000388 raise ValueError('Module-relative files may not have absolute paths')
Edward Loper052d0cd2004-09-19 17:19:33 +0000389
390 # Find the base directory for the path.
391 if hasattr(module, '__file__'):
392 # A normal module/package
393 basedir = os.path.split(module.__file__)[0]
394 elif module.__name__ == '__main__':
395 # An interactive session.
396 if len(sys.argv)>0 and sys.argv[0] != '':
397 basedir = os.path.split(sys.argv[0])[0]
398 else:
399 basedir = os.curdir
400 else:
401 # A module w/o __file__ (this includes builtins)
402 raise ValueError("Can't resolve paths relative to the module " +
403 module + " (it has no __file__)")
404
405 # Combine the base directory and the path.
406 return os.path.join(basedir, *(path.split('/')))
407
Tim Peters8485b562004-08-04 18:46:34 +0000408######################################################################
409## 2. Example & DocTest
410######################################################################
411## - An "example" is a <source, want> pair, where "source" is a
412## fragment of source code, and "want" is the expected output for
413## "source." The Example class also includes information about
414## where the example was extracted from.
415##
Edward Lopera1ef6112004-08-09 16:14:41 +0000416## - A "doctest" is a collection of examples, typically extracted from
417## a string (such as an object's docstring). The DocTest class also
418## includes information about where the string was extracted from.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000419
Tim Peters8485b562004-08-04 18:46:34 +0000420class Example:
421 """
422 A single doctest example, consisting of source code and expected
Edward Lopera1ef6112004-08-09 16:14:41 +0000423 output. `Example` defines the following attributes:
Tim Peters8a7d2d52001-01-16 07:10:57 +0000424
Edward Loper74bca7a2004-08-12 02:27:44 +0000425 - source: A single Python statement, always ending with a newline.
Tim Petersbb431472004-08-09 03:51:46 +0000426 The constructor adds a newline if needed.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000427
Edward Loper74bca7a2004-08-12 02:27:44 +0000428 - want: The expected output from running the source code (either
Tim Petersbb431472004-08-09 03:51:46 +0000429 from stdout, or a traceback in case of exception). `want` ends
430 with a newline unless it's empty, in which case it's an empty
431 string. The constructor adds a newline if needed.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000432
Edward Lopera6b68322004-08-26 00:05:43 +0000433 - exc_msg: The exception message generated by the example, if
434 the example is expected to generate an exception; or `None` if
435 it is not expected to generate an exception. This exception
436 message is compared against the return value of
437 `traceback.format_exception_only()`. `exc_msg` ends with a
438 newline unless it's `None`. The constructor adds a newline
439 if needed.
440
Edward Loper74bca7a2004-08-12 02:27:44 +0000441 - lineno: The line number within the DocTest string containing
Tim Peters8485b562004-08-04 18:46:34 +0000442 this Example where the Example begins. This line number is
443 zero-based, with respect to the beginning of the DocTest.
Edward Loper74bca7a2004-08-12 02:27:44 +0000444
445 - indent: The example's indentation in the DocTest string.
Ezio Melotti30b9d5d2013-08-17 15:50:46 +0300446 I.e., the number of space characters that precede the
Edward Loper74bca7a2004-08-12 02:27:44 +0000447 example's first prompt.
448
449 - options: A dictionary mapping from option flags to True or
450 False, which is used to override default options for this
451 example. Any option flags not contained in this dictionary
452 are left at their default value (as specified by the
453 DocTestRunner's optionflags). By default, no options are set.
Tim Peters8485b562004-08-04 18:46:34 +0000454 """
Edward Lopera6b68322004-08-26 00:05:43 +0000455 def __init__(self, source, want, exc_msg=None, lineno=0, indent=0,
456 options=None):
Tim Petersbb431472004-08-09 03:51:46 +0000457 # Normalize inputs.
458 if not source.endswith('\n'):
459 source += '\n'
460 if want and not want.endswith('\n'):
461 want += '\n'
Edward Lopera6b68322004-08-26 00:05:43 +0000462 if exc_msg is not None and not exc_msg.endswith('\n'):
463 exc_msg += '\n'
Tim Peters8485b562004-08-04 18:46:34 +0000464 # Store properties.
465 self.source = source
466 self.want = want
467 self.lineno = lineno
Edward Loper74bca7a2004-08-12 02:27:44 +0000468 self.indent = indent
469 if options is None: options = {}
470 self.options = options
Edward Lopera6b68322004-08-26 00:05:43 +0000471 self.exc_msg = exc_msg
Tim Peters8a7d2d52001-01-16 07:10:57 +0000472
Antoine Pitrou2bc801c2011-12-18 19:27:45 +0100473 def __eq__(self, other):
474 if type(self) is not type(other):
475 return NotImplemented
476
477 return self.source == other.source and \
478 self.want == other.want and \
479 self.lineno == other.lineno and \
480 self.indent == other.indent and \
481 self.options == other.options and \
482 self.exc_msg == other.exc_msg
483
484 def __ne__(self, other):
485 return not self == other
486
Antoine Pitrou165b1282011-12-18 20:20:17 +0100487 def __hash__(self):
488 return hash((self.source, self.want, self.lineno, self.indent,
489 self.exc_msg))
Antoine Pitrou2bc801c2011-12-18 19:27:45 +0100490
Tim Peters8485b562004-08-04 18:46:34 +0000491class DocTest:
492 """
493 A collection of doctest examples that should be run in a single
Edward Lopera1ef6112004-08-09 16:14:41 +0000494 namespace. Each `DocTest` defines the following attributes:
Tim Peters8a7d2d52001-01-16 07:10:57 +0000495
Tim Peters8485b562004-08-04 18:46:34 +0000496 - examples: the list of examples.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000497
Tim Peters8485b562004-08-04 18:46:34 +0000498 - globs: The namespace (aka globals) that the examples should
499 be run in.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000500
Tim Peters8485b562004-08-04 18:46:34 +0000501 - name: A name identifying the DocTest (typically, the name of
502 the object whose docstring this DocTest was extracted from).
Tim Peters8a7d2d52001-01-16 07:10:57 +0000503
Tim Peters8485b562004-08-04 18:46:34 +0000504 - filename: The name of the file that this DocTest was extracted
Edward Lopera1ef6112004-08-09 16:14:41 +0000505 from, or `None` if the filename is unknown.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000506
Tim Peters8485b562004-08-04 18:46:34 +0000507 - lineno: The line number within filename where this DocTest
Edward Lopera1ef6112004-08-09 16:14:41 +0000508 begins, or `None` if the line number is unavailable. This
509 line number is zero-based, with respect to the beginning of
510 the file.
511
512 - docstring: The string that the examples were extracted from,
513 or `None` if the string is unavailable.
Tim Peters8485b562004-08-04 18:46:34 +0000514 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000515 def __init__(self, examples, globs, name, filename, lineno, docstring):
Tim Peters8485b562004-08-04 18:46:34 +0000516 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000517 Create a new DocTest containing the given examples. The
518 DocTest's globals are initialized with a copy of `globs`.
Tim Peters8485b562004-08-04 18:46:34 +0000519 """
Guido van Rossum3172c5d2007-10-16 18:12:55 +0000520 assert not isinstance(examples, str), \
Edward Lopera1ef6112004-08-09 16:14:41 +0000521 "DocTest no longer accepts str; use DocTestParser instead"
522 self.examples = examples
523 self.docstring = docstring
Tim Peters8485b562004-08-04 18:46:34 +0000524 self.globs = globs.copy()
Tim Peters8485b562004-08-04 18:46:34 +0000525 self.name = name
526 self.filename = filename
527 self.lineno = lineno
Tim Peters8485b562004-08-04 18:46:34 +0000528
529 def __repr__(self):
530 if len(self.examples) == 0:
531 examples = 'no examples'
532 elif len(self.examples) == 1:
533 examples = '1 example'
534 else:
535 examples = '%d examples' % len(self.examples)
536 return ('<DocTest %s from %s:%s (%s)>' %
537 (self.name, self.filename, self.lineno, examples))
538
Antoine Pitrou2bc801c2011-12-18 19:27:45 +0100539 def __eq__(self, other):
540 if type(self) is not type(other):
541 return NotImplemented
542
543 return self.examples == other.examples and \
544 self.docstring == other.docstring and \
545 self.globs == other.globs and \
546 self.name == other.name and \
547 self.filename == other.filename and \
548 self.lineno == other.lineno
549
550 def __ne__(self, other):
551 return not self == other
Tim Peters8485b562004-08-04 18:46:34 +0000552
Antoine Pitrou165b1282011-12-18 20:20:17 +0100553 def __hash__(self):
554 return hash((self.docstring, self.name, self.filename, self.lineno))
555
Tim Peters8485b562004-08-04 18:46:34 +0000556 # This lets us sort tests by name:
Guido van Rossum47b9ff62006-08-24 00:41:19 +0000557 def __lt__(self, other):
Tim Peters8485b562004-08-04 18:46:34 +0000558 if not isinstance(other, DocTest):
Guido van Rossum47b9ff62006-08-24 00:41:19 +0000559 return NotImplemented
560 return ((self.name, self.filename, self.lineno, id(self))
561 <
562 (other.name, other.filename, other.lineno, id(other)))
Tim Peters8485b562004-08-04 18:46:34 +0000563
564######################################################################
Edward Loperb7503ff2004-08-19 19:19:03 +0000565## 3. DocTestParser
Edward Loper7c748462004-08-09 02:06:06 +0000566######################################################################
567
Edward Lopera1ef6112004-08-09 16:14:41 +0000568class DocTestParser:
Edward Loper7c748462004-08-09 02:06:06 +0000569 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000570 A class used to parse strings containing doctest examples.
Edward Loper7c748462004-08-09 02:06:06 +0000571 """
Edward Loper8e4a34b2004-08-12 02:34:27 +0000572 # This regular expression is used to find doctest examples in a
573 # string. It defines three groups: `source` is the source code
574 # (including leading indentation and prompts); `indent` is the
575 # indentation of the first (PS1) line of the source code; and
576 # `want` is the expected output (including leading indentation).
Edward Loper7c748462004-08-09 02:06:06 +0000577 _EXAMPLE_RE = re.compile(r'''
Tim Petersd40a92b2004-08-09 03:28:45 +0000578 # Source consists of a PS1 line followed by zero or more PS2 lines.
579 (?P<source>
580 (?:^(?P<indent> [ ]*) >>> .*) # PS1 line
581 (?:\n [ ]* \.\.\. .*)*) # PS2 lines
582 \n?
583 # Want consists of any non-blank lines that do not start with PS1.
584 (?P<want> (?:(?![ ]*$) # Not a blank line
585 (?![ ]*>>>) # Not a line starting with PS1
Serhiy Storchaka1ca66ed2013-08-19 22:59:31 +0300586 .+$\n? # But any other line
Tim Petersd40a92b2004-08-09 03:28:45 +0000587 )*)
588 ''', re.MULTILINE | re.VERBOSE)
Edward Loper8e4a34b2004-08-12 02:34:27 +0000589
Edward Lopera6b68322004-08-26 00:05:43 +0000590 # A regular expression for handling `want` strings that contain
591 # expected exceptions. It divides `want` into three pieces:
592 # - the traceback header line (`hdr`)
593 # - the traceback stack (`stack`)
594 # - the exception message (`msg`), as generated by
595 # traceback.format_exception_only()
596 # `msg` may have multiple lines. We assume/require that the
597 # exception message is the first non-indented line starting with a word
598 # character following the traceback header line.
599 _EXCEPTION_RE = re.compile(r"""
600 # Grab the traceback header. Different versions of Python have
601 # said different things on the first traceback line.
602 ^(?P<hdr> Traceback\ \(
603 (?: most\ recent\ call\ last
604 | innermost\ last
605 ) \) :
606 )
607 \s* $ # toss trailing whitespace on the header.
608 (?P<stack> .*?) # don't blink: absorb stuff until...
609 ^ (?P<msg> \w+ .*) # a line *starts* with alphanum.
610 """, re.VERBOSE | re.MULTILINE | re.DOTALL)
611
Tim Peters7ea48dd2004-08-13 01:52:59 +0000612 # A callable returning a true value iff its argument is a blank line
613 # or contains a single comment.
Edward Loper8e4a34b2004-08-12 02:34:27 +0000614 _IS_BLANK_OR_COMMENT = re.compile(r'^[ ]*(#.*)?$').match
Edward Loper7c748462004-08-09 02:06:06 +0000615
Edward Loper00f8da72004-08-26 18:05:07 +0000616 def parse(self, string, name='<string>'):
617 """
618 Divide the given string into examples and intervening text,
619 and return them as a list of alternating Examples and strings.
620 Line numbers for the Examples are 0-based. The optional
621 argument `name` is a name identifying this string, and is only
622 used for error messages.
623 """
624 string = string.expandtabs()
625 # If all lines begin with the same indentation, then strip it.
626 min_indent = self._min_indent(string)
627 if min_indent > 0:
628 string = '\n'.join([l[min_indent:] for l in string.split('\n')])
629
630 output = []
631 charno, lineno = 0, 0
632 # Find all doctest examples in the string:
Edward Loper2de91ba2004-08-27 02:07:46 +0000633 for m in self._EXAMPLE_RE.finditer(string):
Edward Loper00f8da72004-08-26 18:05:07 +0000634 # Add the pre-example text to `output`.
635 output.append(string[charno:m.start()])
636 # Update lineno (lines before this example)
637 lineno += string.count('\n', charno, m.start())
638 # Extract info from the regexp match.
639 (source, options, want, exc_msg) = \
640 self._parse_example(m, name, lineno)
641 # Create an Example, and add it to the list.
642 if not self._IS_BLANK_OR_COMMENT(source):
643 output.append( Example(source, want, exc_msg,
644 lineno=lineno,
645 indent=min_indent+len(m.group('indent')),
646 options=options) )
647 # Update lineno (lines inside this example)
648 lineno += string.count('\n', m.start(), m.end())
649 # Update charno.
650 charno = m.end()
651 # Add any remaining post-example text to `output`.
652 output.append(string[charno:])
653 return output
654
Edward Lopera1ef6112004-08-09 16:14:41 +0000655 def get_doctest(self, string, globs, name, filename, lineno):
Edward Loper7c748462004-08-09 02:06:06 +0000656 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000657 Extract all doctest examples from the given string, and
658 collect them into a `DocTest` object.
659
660 `globs`, `name`, `filename`, and `lineno` are attributes for
661 the new `DocTest` object. See the documentation for `DocTest`
662 for more information.
663 """
664 return DocTest(self.get_examples(string, name), globs,
665 name, filename, lineno, string)
666
667 def get_examples(self, string, name='<string>'):
668 """
669 Extract all doctest examples from the given string, and return
670 them as a list of `Example` objects. Line numbers are
671 0-based, because it's most common in doctests that nothing
672 interesting appears on the same line as opening triple-quote,
673 and so the first interesting line is called \"line 1\" then.
674
675 The optional argument `name` is a name identifying this
676 string, and is only used for error messages.
Edward Loper7c748462004-08-09 02:06:06 +0000677 """
Edward Loper00f8da72004-08-26 18:05:07 +0000678 return [x for x in self.parse(string, name)
679 if isinstance(x, Example)]
Edward Loper7c748462004-08-09 02:06:06 +0000680
Edward Loper74bca7a2004-08-12 02:27:44 +0000681 def _parse_example(self, m, name, lineno):
682 """
683 Given a regular expression match from `_EXAMPLE_RE` (`m`),
684 return a pair `(source, want)`, where `source` is the matched
685 example's source code (with prompts and indentation stripped);
686 and `want` is the example's expected output (with indentation
687 stripped).
688
689 `name` is the string's name, and `lineno` is the line number
690 where the example starts; both are used for error messages.
691 """
Edward Loper7c748462004-08-09 02:06:06 +0000692 # Get the example's indentation level.
693 indent = len(m.group('indent'))
694
695 # Divide source into lines; check that they're properly
696 # indented; and then strip their indentation & prompts.
697 source_lines = m.group('source').split('\n')
Edward Lopera1ef6112004-08-09 16:14:41 +0000698 self._check_prompt_blank(source_lines, indent, name, lineno)
Tim Petersc5049152004-08-22 17:34:58 +0000699 self._check_prefix(source_lines[1:], ' '*indent + '.', name, lineno)
Edward Loper7c748462004-08-09 02:06:06 +0000700 source = '\n'.join([sl[indent+4:] for sl in source_lines])
Edward Loper7c748462004-08-09 02:06:06 +0000701
Tim Petersc5049152004-08-22 17:34:58 +0000702 # Divide want into lines; check that it's properly indented; and
703 # then strip the indentation. Spaces before the last newline should
704 # be preserved, so plain rstrip() isn't good enough.
Jim Fulton07a349c2004-08-22 14:10:00 +0000705 want = m.group('want')
Jim Fulton07a349c2004-08-22 14:10:00 +0000706 want_lines = want.split('\n')
Tim Petersc5049152004-08-22 17:34:58 +0000707 if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]):
708 del want_lines[-1] # forget final newline & spaces after it
Edward Lopera1ef6112004-08-09 16:14:41 +0000709 self._check_prefix(want_lines, ' '*indent, name,
Tim Petersc5049152004-08-22 17:34:58 +0000710 lineno + len(source_lines))
Edward Loper7c748462004-08-09 02:06:06 +0000711 want = '\n'.join([wl[indent:] for wl in want_lines])
Edward Loper7c748462004-08-09 02:06:06 +0000712
Edward Lopera6b68322004-08-26 00:05:43 +0000713 # If `want` contains a traceback message, then extract it.
714 m = self._EXCEPTION_RE.match(want)
715 if m:
716 exc_msg = m.group('msg')
717 else:
718 exc_msg = None
719
Edward Loper00f8da72004-08-26 18:05:07 +0000720 # Extract options from the source.
721 options = self._find_options(source, name, lineno)
722
723 return source, options, want, exc_msg
Edward Loper7c748462004-08-09 02:06:06 +0000724
Edward Loper74bca7a2004-08-12 02:27:44 +0000725 # This regular expression looks for option directives in the
726 # source code of an example. Option directives are comments
727 # starting with "doctest:". Warning: this may give false
728 # positives for string-literals that contain the string
729 # "#doctest:". Eliminating these false positives would require
730 # actually parsing the string; but we limit them by ignoring any
731 # line containing "#doctest:" that is *followed* by a quote mark.
732 _OPTION_DIRECTIVE_RE = re.compile(r'#\s*doctest:\s*([^\n\'"]*)$',
733 re.MULTILINE)
734
735 def _find_options(self, source, name, lineno):
736 """
737 Return a dictionary containing option overrides extracted from
738 option directives in the given source string.
739
740 `name` is the string's name, and `lineno` is the line number
741 where the example starts; both are used for error messages.
742 """
743 options = {}
744 # (note: with the current regexp, this will match at most once:)
745 for m in self._OPTION_DIRECTIVE_RE.finditer(source):
746 option_strings = m.group(1).replace(',', ' ').split()
747 for option in option_strings:
748 if (option[0] not in '+-' or
749 option[1:] not in OPTIONFLAGS_BY_NAME):
750 raise ValueError('line %r of the doctest for %s '
751 'has an invalid option: %r' %
752 (lineno+1, name, option))
753 flag = OPTIONFLAGS_BY_NAME[option[1:]]
754 options[flag] = (option[0] == '+')
755 if options and self._IS_BLANK_OR_COMMENT(source):
756 raise ValueError('line %r of the doctest for %s has an option '
757 'directive on a line with no example: %r' %
758 (lineno, name, source))
759 return options
760
Edward Lopera5db6002004-08-12 02:41:30 +0000761 # This regular expression finds the indentation of every non-blank
762 # line in a string.
Edward Loper00f8da72004-08-26 18:05:07 +0000763 _INDENT_RE = re.compile('^([ ]*)(?=\S)', re.MULTILINE)
Edward Lopera5db6002004-08-12 02:41:30 +0000764
765 def _min_indent(self, s):
766 "Return the minimum indentation of any non-blank line in `s`"
Edward Loper00f8da72004-08-26 18:05:07 +0000767 indents = [len(indent) for indent in self._INDENT_RE.findall(s)]
768 if len(indents) > 0:
769 return min(indents)
Tim Petersdd0e4752004-08-09 03:31:56 +0000770 else:
Edward Loper00f8da72004-08-26 18:05:07 +0000771 return 0
Edward Loper7c748462004-08-09 02:06:06 +0000772
Edward Lopera1ef6112004-08-09 16:14:41 +0000773 def _check_prompt_blank(self, lines, indent, name, lineno):
Edward Loper74bca7a2004-08-12 02:27:44 +0000774 """
775 Given the lines of a source string (including prompts and
776 leading indentation), check to make sure that every prompt is
777 followed by a space character. If any line is not followed by
778 a space character, then raise ValueError.
779 """
Edward Loper7c748462004-08-09 02:06:06 +0000780 for i, line in enumerate(lines):
781 if len(line) >= indent+4 and line[indent+3] != ' ':
782 raise ValueError('line %r of the docstring for %s '
783 'lacks blank after %s: %r' %
Edward Lopera1ef6112004-08-09 16:14:41 +0000784 (lineno+i+1, name,
Edward Loper7c748462004-08-09 02:06:06 +0000785 line[indent:indent+3], line))
786
Edward Lopera1ef6112004-08-09 16:14:41 +0000787 def _check_prefix(self, lines, prefix, name, lineno):
Edward Loper74bca7a2004-08-12 02:27:44 +0000788 """
789 Check that every line in the given list starts with the given
790 prefix; if any line does not, then raise a ValueError.
791 """
Edward Loper7c748462004-08-09 02:06:06 +0000792 for i, line in enumerate(lines):
793 if line and not line.startswith(prefix):
794 raise ValueError('line %r of the docstring for %s has '
795 'inconsistent leading whitespace: %r' %
Edward Lopera1ef6112004-08-09 16:14:41 +0000796 (lineno+i+1, name, line))
Edward Loper7c748462004-08-09 02:06:06 +0000797
798
799######################################################################
800## 4. DocTest Finder
Tim Peters8485b562004-08-04 18:46:34 +0000801######################################################################
802
803class DocTestFinder:
804 """
805 A class used to extract the DocTests that are relevant to a given
806 object, from its docstring and the docstrings of its contained
807 objects. Doctests can currently be extracted from the following
808 object types: modules, functions, classes, methods, staticmethods,
809 classmethods, and properties.
Tim Peters8485b562004-08-04 18:46:34 +0000810 """
811
Edward Lopera1ef6112004-08-09 16:14:41 +0000812 def __init__(self, verbose=False, parser=DocTestParser(),
Thomas Wouters73e5a5b2006-06-08 15:35:45 +0000813 recurse=True, exclude_empty=True):
Tim Peters8485b562004-08-04 18:46:34 +0000814 """
815 Create a new doctest finder.
816
Edward Lopera1ef6112004-08-09 16:14:41 +0000817 The optional argument `parser` specifies a class or
Tim Peters19397e52004-08-06 22:02:59 +0000818 function that should be used to create new DocTest objects (or
Tim Peters161c9632004-08-08 03:38:33 +0000819 objects that implement the same interface as DocTest). The
Tim Peters19397e52004-08-06 22:02:59 +0000820 signature for this factory function should match the signature
821 of the DocTest constructor.
822
Tim Peters8485b562004-08-04 18:46:34 +0000823 If the optional argument `recurse` is false, then `find` will
824 only examine the given object, and not any contained objects.
Edward Loper32ddbf72004-09-13 05:47:24 +0000825
Tim Peters958cc892004-09-13 14:53:28 +0000826 If the optional argument `exclude_empty` is false, then `find`
827 will include tests for objects with empty docstrings.
Tim Peters8485b562004-08-04 18:46:34 +0000828 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000829 self._parser = parser
Tim Peters8485b562004-08-04 18:46:34 +0000830 self._verbose = verbose
Tim Peters8485b562004-08-04 18:46:34 +0000831 self._recurse = recurse
Edward Loper32ddbf72004-09-13 05:47:24 +0000832 self._exclude_empty = exclude_empty
Tim Peters8485b562004-08-04 18:46:34 +0000833
Thomas Wouters73e5a5b2006-06-08 15:35:45 +0000834 def find(self, obj, name=None, module=None, globs=None, extraglobs=None):
Tim Peters8485b562004-08-04 18:46:34 +0000835 """
836 Return a list of the DocTests that are defined by the given
837 object's docstring, or by any of its contained objects'
838 docstrings.
839
840 The optional parameter `module` is the module that contains
Tim Petersf3f57472004-08-08 06:11:48 +0000841 the given object. If the module is not specified or is None, then
842 the test finder will attempt to automatically determine the
Tim Peters8485b562004-08-04 18:46:34 +0000843 correct module. The object's module is used:
844
845 - As a default namespace, if `globs` is not specified.
846 - To prevent the DocTestFinder from extracting DocTests
Tim Petersf3f57472004-08-08 06:11:48 +0000847 from objects that are imported from other modules.
Tim Peters8485b562004-08-04 18:46:34 +0000848 - To find the name of the file containing the object.
849 - To help find the line number of the object within its
850 file.
851
Tim Petersf3f57472004-08-08 06:11:48 +0000852 Contained objects whose module does not match `module` are ignored.
853
854 If `module` is False, no attempt to find the module will be made.
855 This is obscure, of use mostly in tests: if `module` is False, or
856 is None but cannot be found automatically, then all objects are
857 considered to belong to the (non-existent) module, so all contained
858 objects will (recursively) be searched for doctests.
859
Tim Peters8485b562004-08-04 18:46:34 +0000860 The globals for each DocTest is formed by combining `globs`
861 and `extraglobs` (bindings in `extraglobs` override bindings
862 in `globs`). A new copy of the globals dictionary is created
863 for each DocTest. If `globs` is not specified, then it
864 defaults to the module's `__dict__`, if specified, or {}
865 otherwise. If `extraglobs` is not specified, then it defaults
866 to {}.
867
Tim Peters8485b562004-08-04 18:46:34 +0000868 """
869 # If name was not specified, then extract it from the object.
870 if name is None:
871 name = getattr(obj, '__name__', None)
872 if name is None:
873 raise ValueError("DocTestFinder.find: name must be given "
874 "when obj.__name__ doesn't exist: %r" %
875 (type(obj),))
876
877 # Find the module that contains the given object (if obj is
878 # a module, then module=obj.). Note: this may fail, in which
879 # case module will be None.
Tim Petersf3f57472004-08-08 06:11:48 +0000880 if module is False:
881 module = None
882 elif module is None:
Tim Peters8485b562004-08-04 18:46:34 +0000883 module = inspect.getmodule(obj)
884
885 # Read the module's source code. This is used by
886 # DocTestFinder._find_lineno to find the line number for a
887 # given object's docstring.
888 try:
R. David Murray58641de2009-06-12 15:33:19 +0000889 file = inspect.getsourcefile(obj)
Tim Peters8485b562004-08-04 18:46:34 +0000890 except TypeError:
891 source_lines = None
R. David Murray58641de2009-06-12 15:33:19 +0000892 else:
893 if not file:
894 # Check to see if it's one of our special internal "files"
895 # (see __patched_linecache_getlines).
896 file = inspect.getfile(obj)
897 if not file[0]+file[-2:] == '<]>': file = None
R. David Murray765b9762009-07-15 14:16:54 +0000898 if file is None:
899 source_lines = None
R. David Murray58641de2009-06-12 15:33:19 +0000900 else:
901 if module is not None:
902 # Supply the module globals in case the module was
903 # originally loaded via a PEP 302 loader and
904 # file is not a valid filesystem path
905 source_lines = linecache.getlines(file, module.__dict__)
906 else:
907 # No access to a loader, so assume it's a normal
908 # filesystem path
909 source_lines = linecache.getlines(file)
910 if not source_lines:
911 source_lines = None
Tim Peters8485b562004-08-04 18:46:34 +0000912
913 # Initialize globals, and merge in extraglobs.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000914 if globs is None:
Tim Peters8485b562004-08-04 18:46:34 +0000915 if module is None:
916 globs = {}
917 else:
918 globs = module.__dict__.copy()
919 else:
920 globs = globs.copy()
921 if extraglobs is not None:
922 globs.update(extraglobs)
Raymond Hettinger0f055172009-01-27 10:06:09 +0000923 if '__name__' not in globs:
924 globs['__name__'] = '__main__' # provide a default module name
Tim Peters8a7d2d52001-01-16 07:10:57 +0000925
Ezio Melotti30b9d5d2013-08-17 15:50:46 +0300926 # Recursively explore `obj`, extracting DocTests.
Tim Peters8485b562004-08-04 18:46:34 +0000927 tests = []
Tim Petersf3f57472004-08-08 06:11:48 +0000928 self._find(tests, obj, name, module, source_lines, globs, {})
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000929 # Sort the tests by alpha order of names, for consistency in
930 # verbose-mode output. This was a feature of doctest in Pythons
931 # <= 2.3 that got lost by accident in 2.4. It was repaired in
932 # 2.4.4 and 2.5.
933 tests.sort()
Tim Peters8485b562004-08-04 18:46:34 +0000934 return tests
935
Tim Peters8485b562004-08-04 18:46:34 +0000936 def _from_module(self, module, object):
937 """
938 Return true if the given object is defined in the given
939 module.
940 """
941 if module is None:
942 return True
Benjamin Peterson6cadba72008-11-19 22:38:29 +0000943 elif inspect.getmodule(object) is not None:
944 return module is inspect.getmodule(object)
Tim Peters8485b562004-08-04 18:46:34 +0000945 elif inspect.isfunction(object):
Neal Norwitz221085d2007-02-25 20:55:47 +0000946 return module.__dict__ is object.__globals__
Zachary Warea4b7a752013-11-24 01:19:09 -0600947 elif inspect.ismethoddescriptor(object):
948 return module.__name__ == object.__objclass__.__module__
Tim Peters8485b562004-08-04 18:46:34 +0000949 elif inspect.isclass(object):
950 return module.__name__ == object.__module__
Tim Peters8485b562004-08-04 18:46:34 +0000951 elif hasattr(object, '__module__'):
952 return module.__name__ == object.__module__
953 elif isinstance(object, property):
954 return True # [XX] no way not be sure.
955 else:
956 raise ValueError("object must be a class or function")
957
Tim Petersf3f57472004-08-08 06:11:48 +0000958 def _find(self, tests, obj, name, module, source_lines, globs, seen):
Tim Peters8485b562004-08-04 18:46:34 +0000959 """
960 Find tests for the given object and any contained objects, and
961 add them to `tests`.
962 """
963 if self._verbose:
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000964 print('Finding tests in %s' % name)
Tim Peters8485b562004-08-04 18:46:34 +0000965
966 # If we've already processed this object, then ignore it.
967 if id(obj) in seen:
968 return
969 seen[id(obj)] = 1
970
971 # Find a test for this object, and add it to the list of tests.
972 test = self._get_test(obj, name, module, globs, source_lines)
973 if test is not None:
974 tests.append(test)
975
976 # Look for tests in a module's contained objects.
977 if inspect.ismodule(obj) and self._recurse:
978 for valname, val in obj.__dict__.items():
Tim Peters8485b562004-08-04 18:46:34 +0000979 valname = '%s.%s' % (name, valname)
980 # Recurse to functions & classes.
Zachary Warea4b7a752013-11-24 01:19:09 -0600981 if ((inspect.isroutine(val) or inspect.isclass(val)) and
Tim Petersf3f57472004-08-08 06:11:48 +0000982 self._from_module(module, val)):
Tim Peters8485b562004-08-04 18:46:34 +0000983 self._find(tests, val, valname, module, source_lines,
Tim Petersf3f57472004-08-08 06:11:48 +0000984 globs, seen)
Tim Peters8485b562004-08-04 18:46:34 +0000985
986 # Look for tests in a module's __test__ dictionary.
987 if inspect.ismodule(obj) and self._recurse:
988 for valname, val in getattr(obj, '__test__', {}).items():
Guido van Rossum3172c5d2007-10-16 18:12:55 +0000989 if not isinstance(valname, str):
Tim Peters8485b562004-08-04 18:46:34 +0000990 raise ValueError("DocTestFinder.find: __test__ keys "
991 "must be strings: %r" %
992 (type(valname),))
Zachary Warea4b7a752013-11-24 01:19:09 -0600993 if not (inspect.isroutine(val) or inspect.isclass(val) or
994 inspect.ismodule(val) or isinstance(val, str)):
Tim Peters8485b562004-08-04 18:46:34 +0000995 raise ValueError("DocTestFinder.find: __test__ values "
996 "must be strings, functions, methods, "
997 "classes, or modules: %r" %
998 (type(val),))
Tim Petersc5684782004-09-13 01:07:12 +0000999 valname = '%s.__test__.%s' % (name, valname)
Tim Peters8485b562004-08-04 18:46:34 +00001000 self._find(tests, val, valname, module, source_lines,
Tim Petersf3f57472004-08-08 06:11:48 +00001001 globs, seen)
Tim Peters8485b562004-08-04 18:46:34 +00001002
1003 # Look for tests in a class's contained objects.
1004 if inspect.isclass(obj) and self._recurse:
1005 for valname, val in obj.__dict__.items():
Tim Peters8485b562004-08-04 18:46:34 +00001006 # Special handling for staticmethod/classmethod.
1007 if isinstance(val, staticmethod):
1008 val = getattr(obj, valname)
1009 if isinstance(val, classmethod):
Christian Heimesff737952007-11-27 10:40:20 +00001010 val = getattr(obj, valname).__func__
Tim Peters8485b562004-08-04 18:46:34 +00001011
1012 # Recurse to methods, properties, and nested classes.
Zachary Warea4b7a752013-11-24 01:19:09 -06001013 if ((inspect.isroutine(val) or inspect.isclass(val) or
Tim Petersf3f57472004-08-08 06:11:48 +00001014 isinstance(val, property)) and
1015 self._from_module(module, val)):
Tim Peters8485b562004-08-04 18:46:34 +00001016 valname = '%s.%s' % (name, valname)
1017 self._find(tests, val, valname, module, source_lines,
Tim Petersf3f57472004-08-08 06:11:48 +00001018 globs, seen)
Tim Peters8485b562004-08-04 18:46:34 +00001019
1020 def _get_test(self, obj, name, module, globs, source_lines):
1021 """
1022 Return a DocTest for the given object, if it defines a docstring;
1023 otherwise, return None.
1024 """
1025 # Extract the object's docstring. If it doesn't have one,
1026 # then return None (no test for this object).
Guido van Rossum3172c5d2007-10-16 18:12:55 +00001027 if isinstance(obj, str):
Tim Peters8485b562004-08-04 18:46:34 +00001028 docstring = obj
1029 else:
1030 try:
1031 if obj.__doc__ is None:
Edward Loper32ddbf72004-09-13 05:47:24 +00001032 docstring = ''
1033 else:
Jim Fulton7d428782004-10-13 14:15:32 +00001034 docstring = obj.__doc__
Guido van Rossum3172c5d2007-10-16 18:12:55 +00001035 if not isinstance(docstring, str):
Jim Fulton7d428782004-10-13 14:15:32 +00001036 docstring = str(docstring)
Tim Peters8485b562004-08-04 18:46:34 +00001037 except (TypeError, AttributeError):
Edward Loper32ddbf72004-09-13 05:47:24 +00001038 docstring = ''
Tim Peters8485b562004-08-04 18:46:34 +00001039
1040 # Find the docstring's location in the file.
1041 lineno = self._find_lineno(obj, source_lines)
1042
Edward Loper32ddbf72004-09-13 05:47:24 +00001043 # Don't bother if the docstring is empty.
1044 if self._exclude_empty and not docstring:
1045 return None
1046
Tim Peters8485b562004-08-04 18:46:34 +00001047 # Return a DocTest for this object.
1048 if module is None:
1049 filename = None
1050 else:
1051 filename = getattr(module, '__file__', module.__name__)
Jim Fulton07a349c2004-08-22 14:10:00 +00001052 if filename[-4:] in (".pyc", ".pyo"):
1053 filename = filename[:-1]
Edward Lopera1ef6112004-08-09 16:14:41 +00001054 return self._parser.get_doctest(docstring, globs, name,
1055 filename, lineno)
Tim Peters8485b562004-08-04 18:46:34 +00001056
1057 def _find_lineno(self, obj, source_lines):
1058 """
1059 Return a line number of the given object's docstring. Note:
1060 this method assumes that the object has a docstring.
1061 """
1062 lineno = None
1063
1064 # Find the line number for modules.
1065 if inspect.ismodule(obj):
1066 lineno = 0
1067
1068 # Find the line number for classes.
1069 # Note: this could be fooled if a class is defined multiple
1070 # times in a single file.
1071 if inspect.isclass(obj):
1072 if source_lines is None:
1073 return None
1074 pat = re.compile(r'^\s*class\s*%s\b' %
1075 getattr(obj, '__name__', '-'))
1076 for i, line in enumerate(source_lines):
1077 if pat.match(line):
1078 lineno = i
1079 break
1080
1081 # Find the line number for functions & methods.
Christian Heimesff737952007-11-27 10:40:20 +00001082 if inspect.ismethod(obj): obj = obj.__func__
Neal Norwitz221085d2007-02-25 20:55:47 +00001083 if inspect.isfunction(obj): obj = obj.__code__
Tim Peters8485b562004-08-04 18:46:34 +00001084 if inspect.istraceback(obj): obj = obj.tb_frame
1085 if inspect.isframe(obj): obj = obj.f_code
1086 if inspect.iscode(obj):
1087 lineno = getattr(obj, 'co_firstlineno', None)-1
1088
1089 # Find the line number where the docstring starts. Assume
1090 # that it's the first line that begins with a quote mark.
1091 # Note: this could be fooled by a multiline function
1092 # signature, where a continuation line begins with a quote
1093 # mark.
1094 if lineno is not None:
1095 if source_lines is None:
1096 return lineno+1
1097 pat = re.compile('(^|.*:)\s*\w*("|\')')
1098 for lineno in range(lineno, len(source_lines)):
1099 if pat.match(source_lines[lineno]):
1100 return lineno
1101
1102 # We couldn't find the line number.
1103 return None
1104
1105######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00001106## 5. DocTest Runner
Tim Peters8485b562004-08-04 18:46:34 +00001107######################################################################
1108
Tim Peters8485b562004-08-04 18:46:34 +00001109class DocTestRunner:
1110 """
1111 A class used to run DocTest test cases, and accumulate statistics.
1112 The `run` method is used to process a single DocTest case. It
1113 returns a tuple `(f, t)`, where `t` is the number of test cases
1114 tried, and `f` is the number of test cases that failed.
1115
1116 >>> tests = DocTestFinder().find(_TestClass)
1117 >>> runner = DocTestRunner(verbose=False)
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00001118 >>> tests.sort(key = lambda test: test.name)
Tim Peters8485b562004-08-04 18:46:34 +00001119 >>> for test in tests:
Guido van Rossum7131f842007-02-09 20:13:25 +00001120 ... print(test.name, '->', runner.run(test))
Christian Heimes25bb7832008-01-11 16:17:00 +00001121 _TestClass -> TestResults(failed=0, attempted=2)
1122 _TestClass.__init__ -> TestResults(failed=0, attempted=2)
1123 _TestClass.get -> TestResults(failed=0, attempted=2)
1124 _TestClass.square -> TestResults(failed=0, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +00001125
1126 The `summarize` method prints a summary of all the test cases that
1127 have been run by the runner, and returns an aggregated `(f, t)`
1128 tuple:
1129
1130 >>> runner.summarize(verbose=1)
1131 4 items passed all tests:
1132 2 tests in _TestClass
1133 2 tests in _TestClass.__init__
1134 2 tests in _TestClass.get
1135 1 tests in _TestClass.square
1136 7 tests in 4 items.
1137 7 passed and 0 failed.
1138 Test passed.
Christian Heimes25bb7832008-01-11 16:17:00 +00001139 TestResults(failed=0, attempted=7)
Tim Peters8485b562004-08-04 18:46:34 +00001140
1141 The aggregated number of tried examples and failed examples is
1142 also available via the `tries` and `failures` attributes:
1143
1144 >>> runner.tries
1145 7
1146 >>> runner.failures
1147 0
1148
1149 The comparison between expected outputs and actual outputs is done
Edward Loper34fcb142004-08-09 02:45:41 +00001150 by an `OutputChecker`. This comparison may be customized with a
1151 number of option flags; see the documentation for `testmod` for
1152 more information. If the option flags are insufficient, then the
1153 comparison may also be customized by passing a subclass of
1154 `OutputChecker` to the constructor.
Tim Peters8485b562004-08-04 18:46:34 +00001155
1156 The test runner's display output can be controlled in two ways.
1157 First, an output function (`out) can be passed to
1158 `TestRunner.run`; this function will be called with strings that
1159 should be displayed. It defaults to `sys.stdout.write`. If
1160 capturing the output is not sufficient, then the display output
1161 can be also customized by subclassing DocTestRunner, and
1162 overriding the methods `report_start`, `report_success`,
1163 `report_unexpected_exception`, and `report_failure`.
1164 """
1165 # This divider string is used to separate failure messages, and to
1166 # separate sections of the summary.
1167 DIVIDER = "*" * 70
1168
Edward Loper34fcb142004-08-09 02:45:41 +00001169 def __init__(self, checker=None, verbose=None, optionflags=0):
Tim Peters8485b562004-08-04 18:46:34 +00001170 """
1171 Create a new test runner.
1172
Edward Loper34fcb142004-08-09 02:45:41 +00001173 Optional keyword arg `checker` is the `OutputChecker` that
1174 should be used to compare the expected outputs and actual
1175 outputs of doctest examples.
1176
Tim Peters8485b562004-08-04 18:46:34 +00001177 Optional keyword arg 'verbose' prints lots of stuff if true,
1178 only failures if false; by default, it's true iff '-v' is in
1179 sys.argv.
1180
1181 Optional argument `optionflags` can be used to control how the
1182 test runner compares expected output to actual output, and how
1183 it displays failures. See the documentation for `testmod` for
1184 more information.
1185 """
Edward Loper34fcb142004-08-09 02:45:41 +00001186 self._checker = checker or OutputChecker()
Tim Peters8a7d2d52001-01-16 07:10:57 +00001187 if verbose is None:
Tim Peters8485b562004-08-04 18:46:34 +00001188 verbose = '-v' in sys.argv
1189 self._verbose = verbose
Tim Peters6ebe61f2003-06-27 20:48:05 +00001190 self.optionflags = optionflags
Jim Fulton07a349c2004-08-22 14:10:00 +00001191 self.original_optionflags = optionflags
Tim Peters6ebe61f2003-06-27 20:48:05 +00001192
Tim Peters8485b562004-08-04 18:46:34 +00001193 # Keep track of the examples we've run.
1194 self.tries = 0
1195 self.failures = 0
1196 self._name2ft = {}
Tim Peters8a7d2d52001-01-16 07:10:57 +00001197
Tim Peters8485b562004-08-04 18:46:34 +00001198 # Create a fake output target for capturing doctest output.
1199 self._fakeout = _SpoofOut()
Tim Peters4fd9e2f2001-08-18 00:05:50 +00001200
Tim Peters8485b562004-08-04 18:46:34 +00001201 #/////////////////////////////////////////////////////////////////
Tim Peters8485b562004-08-04 18:46:34 +00001202 # Reporting methods
1203 #/////////////////////////////////////////////////////////////////
Tim Peters17111f32001-10-03 04:08:26 +00001204
Tim Peters8485b562004-08-04 18:46:34 +00001205 def report_start(self, out, test, example):
Tim Peters8a7d2d52001-01-16 07:10:57 +00001206 """
Tim Peters8485b562004-08-04 18:46:34 +00001207 Report that the test runner is about to process the given
1208 example. (Only displays a message if verbose=True)
1209 """
1210 if self._verbose:
Edward Loperaacf0832004-08-26 01:19:50 +00001211 if example.want:
1212 out('Trying:\n' + _indent(example.source) +
1213 'Expecting:\n' + _indent(example.want))
1214 else:
1215 out('Trying:\n' + _indent(example.source) +
1216 'Expecting nothing\n')
Tim Peters8a7d2d52001-01-16 07:10:57 +00001217
Tim Peters8485b562004-08-04 18:46:34 +00001218 def report_success(self, out, test, example, got):
1219 """
1220 Report that the given example ran successfully. (Only
1221 displays a message if verbose=True)
1222 """
1223 if self._verbose:
1224 out("ok\n")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001225
Tim Peters8485b562004-08-04 18:46:34 +00001226 def report_failure(self, out, test, example, got):
1227 """
1228 Report that the given example failed.
1229 """
Edward Loper8e4a34b2004-08-12 02:34:27 +00001230 out(self._failure_header(test, example) +
Edward Loperca9111e2004-08-26 03:00:24 +00001231 self._checker.output_difference(example, got, self.optionflags))
Tim Peters7402f792001-10-02 03:53:41 +00001232
Tim Peters8485b562004-08-04 18:46:34 +00001233 def report_unexpected_exception(self, out, test, example, exc_info):
1234 """
1235 Report that the given example raised an unexpected exception.
1236 """
Edward Loper8e4a34b2004-08-12 02:34:27 +00001237 out(self._failure_header(test, example) +
Edward Loperaacf0832004-08-26 01:19:50 +00001238 'Exception raised:\n' + _indent(_exception_traceback(exc_info)))
Tim Peters7402f792001-10-02 03:53:41 +00001239
Edward Loper8e4a34b2004-08-12 02:34:27 +00001240 def _failure_header(self, test, example):
Jim Fulton07a349c2004-08-22 14:10:00 +00001241 out = [self.DIVIDER]
1242 if test.filename:
1243 if test.lineno is not None and example.lineno is not None:
1244 lineno = test.lineno + example.lineno + 1
1245 else:
1246 lineno = '?'
1247 out.append('File "%s", line %s, in %s' %
1248 (test.filename, lineno, test.name))
Tim Peters8485b562004-08-04 18:46:34 +00001249 else:
Jim Fulton07a349c2004-08-22 14:10:00 +00001250 out.append('Line %s, in %s' % (example.lineno+1, test.name))
1251 out.append('Failed example:')
1252 source = example.source
Edward Loperaacf0832004-08-26 01:19:50 +00001253 out.append(_indent(source))
1254 return '\n'.join(out)
Tim Peters7402f792001-10-02 03:53:41 +00001255
Tim Peters8485b562004-08-04 18:46:34 +00001256 #/////////////////////////////////////////////////////////////////
1257 # DocTest Running
1258 #/////////////////////////////////////////////////////////////////
Tim Peters7402f792001-10-02 03:53:41 +00001259
Tim Peters8485b562004-08-04 18:46:34 +00001260 def __run(self, test, compileflags, out):
Tim Peters8a7d2d52001-01-16 07:10:57 +00001261 """
Tim Peters8485b562004-08-04 18:46:34 +00001262 Run the examples in `test`. Write the outcome of each example
1263 with one of the `DocTestRunner.report_*` methods, using the
1264 writer function `out`. `compileflags` is the set of compiler
1265 flags that should be used to execute examples. Return a tuple
1266 `(f, t)`, where `t` is the number of examples tried, and `f`
1267 is the number of examples that failed. The examples are run
1268 in the namespace `test.globs`.
1269 """
1270 # Keep track of the number of failures and tries.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001271 failures = tries = 0
Tim Peters8485b562004-08-04 18:46:34 +00001272
1273 # Save the option flags (since option directives can be used
1274 # to modify them).
1275 original_optionflags = self.optionflags
1276
Tim Peters1fbf9c52004-09-04 17:21:02 +00001277 SUCCESS, FAILURE, BOOM = range(3) # `outcome` state
1278
1279 check = self._checker.check_output
1280
Tim Peters8485b562004-08-04 18:46:34 +00001281 # Process each example.
Edward Loper2de91ba2004-08-27 02:07:46 +00001282 for examplenum, example in enumerate(test.examples):
1283
Ezio Melotti13925002011-03-16 11:05:33 +02001284 # If REPORT_ONLY_FIRST_FAILURE is set, then suppress
Edward Lopera89f88d2004-08-26 02:45:51 +00001285 # reporting after the first failure.
1286 quiet = (self.optionflags & REPORT_ONLY_FIRST_FAILURE and
1287 failures > 0)
1288
Edward Loper74bca7a2004-08-12 02:27:44 +00001289 # Merge in the example's options.
1290 self.optionflags = original_optionflags
1291 if example.options:
1292 for (optionflag, val) in example.options.items():
1293 if val:
1294 self.optionflags |= optionflag
1295 else:
1296 self.optionflags &= ~optionflag
Tim Peters8485b562004-08-04 18:46:34 +00001297
Thomas Wouters477c8d52006-05-27 19:21:47 +00001298 # If 'SKIP' is set, then skip this example.
1299 if self.optionflags & SKIP:
1300 continue
1301
Tim Peters8485b562004-08-04 18:46:34 +00001302 # Record that we started this example.
1303 tries += 1
Edward Lopera89f88d2004-08-26 02:45:51 +00001304 if not quiet:
1305 self.report_start(out, test, example)
Tim Peters8485b562004-08-04 18:46:34 +00001306
Edward Loper2de91ba2004-08-27 02:07:46 +00001307 # Use a special filename for compile(), so we can retrieve
1308 # the source code during interactive debugging (see
1309 # __patched_linecache_getlines).
1310 filename = '<doctest %s[%d]>' % (test.name, examplenum)
1311
Tim Peters8485b562004-08-04 18:46:34 +00001312 # Run the example in the given context (globs), and record
1313 # any exception that gets raised. (But don't intercept
1314 # keyboard interrupts.)
1315 try:
Tim Peters208ca702004-08-09 04:12:36 +00001316 # Don't blink! This is where the user's code gets run.
Georg Brandl7cae87c2006-09-06 06:51:57 +00001317 exec(compile(example.source, filename, "single",
1318 compileflags, 1), test.globs)
Edward Loper2de91ba2004-08-27 02:07:46 +00001319 self.debugger.set_continue() # ==== Example Finished ====
Tim Peters8485b562004-08-04 18:46:34 +00001320 exception = None
1321 except KeyboardInterrupt:
1322 raise
1323 except:
1324 exception = sys.exc_info()
Edward Loper2de91ba2004-08-27 02:07:46 +00001325 self.debugger.set_continue() # ==== Example Finished ====
Tim Peters8485b562004-08-04 18:46:34 +00001326
Tim Peters208ca702004-08-09 04:12:36 +00001327 got = self._fakeout.getvalue() # the actual output
Tim Peters8485b562004-08-04 18:46:34 +00001328 self._fakeout.truncate(0)
Tim Peters1fbf9c52004-09-04 17:21:02 +00001329 outcome = FAILURE # guilty until proved innocent or insane
Tim Peters8485b562004-08-04 18:46:34 +00001330
1331 # If the example executed without raising any exceptions,
Tim Peters1fbf9c52004-09-04 17:21:02 +00001332 # verify its output.
Tim Peters8485b562004-08-04 18:46:34 +00001333 if exception is None:
Tim Peters1fbf9c52004-09-04 17:21:02 +00001334 if check(example.want, got, self.optionflags):
1335 outcome = SUCCESS
Tim Peters8485b562004-08-04 18:46:34 +00001336
Tim Peters1fbf9c52004-09-04 17:21:02 +00001337 # The example raised an exception: check if it was expected.
Tim Peters8485b562004-08-04 18:46:34 +00001338 else:
Benjamin Petersoneec3d712008-06-11 15:59:43 +00001339 exc_msg = traceback.format_exception_only(*exception[:2])[-1]
Tim Peters1fbf9c52004-09-04 17:21:02 +00001340 if not quiet:
Benjamin Petersoneec3d712008-06-11 15:59:43 +00001341 got += _exception_traceback(exception)
Tim Peters8485b562004-08-04 18:46:34 +00001342
Tim Peters1fbf9c52004-09-04 17:21:02 +00001343 # If `example.exc_msg` is None, then we weren't expecting
1344 # an exception.
Edward Lopera6b68322004-08-26 00:05:43 +00001345 if example.exc_msg is None:
Tim Peters1fbf9c52004-09-04 17:21:02 +00001346 outcome = BOOM
1347
1348 # We expected an exception: see whether it matches.
1349 elif check(example.exc_msg, exc_msg, self.optionflags):
1350 outcome = SUCCESS
1351
1352 # Another chance if they didn't care about the detail.
1353 elif self.optionflags & IGNORE_EXCEPTION_DETAIL:
Tim Petersf9a07f22013-12-03 21:02:05 -06001354 if check(_strip_exception_details(example.exc_msg),
1355 _strip_exception_details(exc_msg),
1356 self.optionflags):
Tim Peters1fbf9c52004-09-04 17:21:02 +00001357 outcome = SUCCESS
1358
1359 # Report the outcome.
1360 if outcome is SUCCESS:
1361 if not quiet:
1362 self.report_success(out, test, example, got)
1363 elif outcome is FAILURE:
1364 if not quiet:
1365 self.report_failure(out, test, example, got)
1366 failures += 1
1367 elif outcome is BOOM:
1368 if not quiet:
1369 self.report_unexpected_exception(out, test, example,
Benjamin Petersoneec3d712008-06-11 15:59:43 +00001370 exception)
Tim Peters1fbf9c52004-09-04 17:21:02 +00001371 failures += 1
1372 else:
1373 assert False, ("unknown outcome", outcome)
Tim Peters8485b562004-08-04 18:46:34 +00001374
R David Murray5a9d7062012-11-21 15:09:21 -05001375 if failures and self.optionflags & FAIL_FAST:
1376 break
1377
Tim Peters8485b562004-08-04 18:46:34 +00001378 # Restore the option flags (in case they were modified)
1379 self.optionflags = original_optionflags
1380
1381 # Record and return the number of failures and tries.
1382 self.__record_outcome(test, failures, tries)
Christian Heimes25bb7832008-01-11 16:17:00 +00001383 return TestResults(failures, tries)
Tim Peters8a7d2d52001-01-16 07:10:57 +00001384
Tim Peters8485b562004-08-04 18:46:34 +00001385 def __record_outcome(self, test, f, t):
1386 """
1387 Record the fact that the given DocTest (`test`) generated `f`
1388 failures out of `t` tried examples.
1389 """
1390 f2, t2 = self._name2ft.get(test.name, (0,0))
1391 self._name2ft[test.name] = (f+f2, t+t2)
1392 self.failures += f
1393 self.tries += t
1394
Edward Loper2de91ba2004-08-27 02:07:46 +00001395 __LINECACHE_FILENAME_RE = re.compile(r'<doctest '
Florent Xiclunad9f57632010-10-14 20:56:20 +00001396 r'(?P<name>.+)'
Edward Loper2de91ba2004-08-27 02:07:46 +00001397 r'\[(?P<examplenum>\d+)\]>$')
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00001398 def __patched_linecache_getlines(self, filename, module_globals=None):
Edward Loper2de91ba2004-08-27 02:07:46 +00001399 m = self.__LINECACHE_FILENAME_RE.match(filename)
1400 if m and m.group('name') == self.test.name:
1401 example = self.test.examples[int(m.group('examplenum'))]
Ezio Melottid8b509b2011-09-28 17:37:55 +03001402 return example.source.splitlines(keepends=True)
Edward Loper2de91ba2004-08-27 02:07:46 +00001403 else:
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00001404 return self.save_linecache_getlines(filename, module_globals)
Edward Loper2de91ba2004-08-27 02:07:46 +00001405
Tim Peters8485b562004-08-04 18:46:34 +00001406 def run(self, test, compileflags=None, out=None, clear_globs=True):
1407 """
1408 Run the examples in `test`, and display the results using the
1409 writer function `out`.
1410
1411 The examples are run in the namespace `test.globs`. If
1412 `clear_globs` is true (the default), then this namespace will
1413 be cleared after the test runs, to help with garbage
1414 collection. If you would like to examine the namespace after
1415 the test completes, then use `clear_globs=False`.
1416
1417 `compileflags` gives the set of flags that should be used by
1418 the Python compiler when running the examples. If not
1419 specified, then it will default to the set of future-import
1420 flags that apply to `globs`.
1421
1422 The output of each example is checked using
1423 `DocTestRunner.check_output`, and the results are formatted by
1424 the `DocTestRunner.report_*` methods.
1425 """
Edward Loper2de91ba2004-08-27 02:07:46 +00001426 self.test = test
1427
Tim Peters8485b562004-08-04 18:46:34 +00001428 if compileflags is None:
1429 compileflags = _extract_future_flags(test.globs)
Jim Fulton356fd192004-08-09 11:34:47 +00001430
Tim Peters6c542b72004-08-09 16:43:36 +00001431 save_stdout = sys.stdout
Tim Peters8485b562004-08-04 18:46:34 +00001432 if out is None:
Florent Xicluna59250852010-02-27 14:21:57 +00001433 encoding = save_stdout.encoding
1434 if encoding is None or encoding.lower() == 'utf-8':
1435 out = save_stdout.write
1436 else:
1437 # Use backslashreplace error handling on write
1438 def out(s):
1439 s = str(s.encode(encoding, 'backslashreplace'), encoding)
1440 save_stdout.write(s)
Tim Peters6c542b72004-08-09 16:43:36 +00001441 sys.stdout = self._fakeout
Tim Peters8485b562004-08-04 18:46:34 +00001442
Edward Loper2de91ba2004-08-27 02:07:46 +00001443 # Patch pdb.set_trace to restore sys.stdout during interactive
1444 # debugging (so it's not still redirected to self._fakeout).
1445 # Note that the interactive output will go to *our*
1446 # save_stdout, even if that's not the real sys.stdout; this
1447 # allows us to write test cases for the set_trace behavior.
Brett Cannon31f59292011-02-21 19:29:56 +00001448 save_trace = sys.gettrace()
Tim Peters6c542b72004-08-09 16:43:36 +00001449 save_set_trace = pdb.set_trace
Edward Loper2de91ba2004-08-27 02:07:46 +00001450 self.debugger = _OutputRedirectingPdb(save_stdout)
1451 self.debugger.reset()
1452 pdb.set_trace = self.debugger.set_trace
1453
1454 # Patch linecache.getlines, so we can see the example's source
1455 # when we're inside the debugger.
1456 self.save_linecache_getlines = linecache.getlines
1457 linecache.getlines = self.__patched_linecache_getlines
1458
Georg Brandl25fbb892010-07-30 09:23:23 +00001459 # Make sure sys.displayhook just prints the value to stdout
1460 save_displayhook = sys.displayhook
1461 sys.displayhook = sys.__displayhook__
1462
Tim Peters8485b562004-08-04 18:46:34 +00001463 try:
Tim Peters8485b562004-08-04 18:46:34 +00001464 return self.__run(test, compileflags, out)
1465 finally:
Tim Peters6c542b72004-08-09 16:43:36 +00001466 sys.stdout = save_stdout
1467 pdb.set_trace = save_set_trace
Brett Cannon31f59292011-02-21 19:29:56 +00001468 sys.settrace(save_trace)
Edward Loper2de91ba2004-08-27 02:07:46 +00001469 linecache.getlines = self.save_linecache_getlines
Georg Brandl25fbb892010-07-30 09:23:23 +00001470 sys.displayhook = save_displayhook
Tim Peters8485b562004-08-04 18:46:34 +00001471 if clear_globs:
1472 test.globs.clear()
Benjamin Petersonfbf66bd2008-07-29 15:55:50 +00001473 import builtins
1474 builtins._ = None
Tim Peters8485b562004-08-04 18:46:34 +00001475
1476 #/////////////////////////////////////////////////////////////////
1477 # Summarization
1478 #/////////////////////////////////////////////////////////////////
Tim Peters8a7d2d52001-01-16 07:10:57 +00001479 def summarize(self, verbose=None):
1480 """
Tim Peters8485b562004-08-04 18:46:34 +00001481 Print a summary of all the test cases that have been run by
1482 this DocTestRunner, and return a tuple `(f, t)`, where `f` is
1483 the total number of failed examples, and `t` is the total
1484 number of tried examples.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001485
Tim Peters8485b562004-08-04 18:46:34 +00001486 The optional `verbose` argument controls how detailed the
1487 summary is. If the verbosity is not specified, then the
1488 DocTestRunner's verbosity is used.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001489 """
Tim Peters8a7d2d52001-01-16 07:10:57 +00001490 if verbose is None:
Tim Peters8485b562004-08-04 18:46:34 +00001491 verbose = self._verbose
Tim Peters8a7d2d52001-01-16 07:10:57 +00001492 notests = []
1493 passed = []
1494 failed = []
1495 totalt = totalf = 0
Tim Peters8485b562004-08-04 18:46:34 +00001496 for x in self._name2ft.items():
Tim Peters8a7d2d52001-01-16 07:10:57 +00001497 name, (f, t) = x
1498 assert f <= t
Tim Peters8485b562004-08-04 18:46:34 +00001499 totalt += t
1500 totalf += f
Tim Peters8a7d2d52001-01-16 07:10:57 +00001501 if t == 0:
1502 notests.append(name)
1503 elif f == 0:
1504 passed.append( (name, t) )
1505 else:
1506 failed.append(x)
1507 if verbose:
1508 if notests:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001509 print(len(notests), "items had no tests:")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001510 notests.sort()
1511 for thing in notests:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001512 print(" ", thing)
Tim Peters8a7d2d52001-01-16 07:10:57 +00001513 if passed:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001514 print(len(passed), "items passed all tests:")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001515 passed.sort()
1516 for thing, count in passed:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001517 print(" %3d tests in %s" % (count, thing))
Tim Peters8a7d2d52001-01-16 07:10:57 +00001518 if failed:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001519 print(self.DIVIDER)
1520 print(len(failed), "items had failures:")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001521 failed.sort()
1522 for thing, (f, t) in failed:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001523 print(" %3d of %3d in %s" % (f, t, thing))
Tim Peters8a7d2d52001-01-16 07:10:57 +00001524 if verbose:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001525 print(totalt, "tests in", len(self._name2ft), "items.")
1526 print(totalt - totalf, "passed and", totalf, "failed.")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001527 if totalf:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001528 print("***Test Failed***", totalf, "failures.")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001529 elif verbose:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001530 print("Test passed.")
Christian Heimes25bb7832008-01-11 16:17:00 +00001531 return TestResults(totalf, totalt)
Tim Peters8a7d2d52001-01-16 07:10:57 +00001532
Tim Peters82076ef2004-09-13 00:52:51 +00001533 #/////////////////////////////////////////////////////////////////
1534 # Backward compatibility cruft to maintain doctest.master.
1535 #/////////////////////////////////////////////////////////////////
1536 def merge(self, other):
1537 d = self._name2ft
1538 for name, (f, t) in other._name2ft.items():
1539 if name in d:
Nick Coghlan38622002008-12-15 12:01:34 +00001540 # Don't print here by default, since doing
1541 # so breaks some of the buildbots
1542 #print("*** DocTestRunner.merge: '" + name + "' in both" \
1543 # " testers; summing outcomes.")
Tim Peters82076ef2004-09-13 00:52:51 +00001544 f2, t2 = d[name]
1545 f = f + f2
1546 t = t + t2
1547 d[name] = f, t
1548
Edward Loper34fcb142004-08-09 02:45:41 +00001549class OutputChecker:
1550 """
1551 A class used to check the whether the actual output from a doctest
1552 example matches the expected output. `OutputChecker` defines two
1553 methods: `check_output`, which compares a given pair of outputs,
1554 and returns true if they match; and `output_difference`, which
1555 returns a string describing the differences between two outputs.
1556 """
Georg Brandl559e5d72008-06-11 18:37:52 +00001557 def _toAscii(self, s):
1558 """
1559 Convert string to hex-escaped ASCII string.
1560 """
1561 return str(s.encode('ASCII', 'backslashreplace'), "ASCII")
1562
Edward Loper34fcb142004-08-09 02:45:41 +00001563 def check_output(self, want, got, optionflags):
1564 """
Edward Loper74bca7a2004-08-12 02:27:44 +00001565 Return True iff the actual output from an example (`got`)
1566 matches the expected output (`want`). These strings are
1567 always considered to match if they are identical; but
1568 depending on what option flags the test runner is using,
1569 several non-exact match types are also possible. See the
1570 documentation for `TestRunner` for more information about
1571 option flags.
Edward Loper34fcb142004-08-09 02:45:41 +00001572 """
Georg Brandl559e5d72008-06-11 18:37:52 +00001573
1574 # If `want` contains hex-escaped character such as "\u1234",
1575 # then `want` is a string of six characters(e.g. [\,u,1,2,3,4]).
1576 # On the other hand, `got` could be an another sequence of
1577 # characters such as [\u1234], so `want` and `got` should
1578 # be folded to hex-escaped ASCII string to compare.
1579 got = self._toAscii(got)
1580 want = self._toAscii(want)
1581
Edward Loper34fcb142004-08-09 02:45:41 +00001582 # Handle the common case first, for efficiency:
1583 # if they're string-identical, always return true.
1584 if got == want:
1585 return True
1586
1587 # The values True and False replaced 1 and 0 as the return
1588 # value for boolean comparisons in Python 2.3.
1589 if not (optionflags & DONT_ACCEPT_TRUE_FOR_1):
1590 if (got,want) == ("True\n", "1\n"):
1591 return True
1592 if (got,want) == ("False\n", "0\n"):
1593 return True
1594
1595 # <BLANKLINE> can be used as a special sequence to signify a
1596 # blank line, unless the DONT_ACCEPT_BLANKLINE flag is used.
1597 if not (optionflags & DONT_ACCEPT_BLANKLINE):
1598 # Replace <BLANKLINE> in want with a blank line.
1599 want = re.sub('(?m)^%s\s*?$' % re.escape(BLANKLINE_MARKER),
1600 '', want)
1601 # If a line in got contains only spaces, then remove the
1602 # spaces.
1603 got = re.sub('(?m)^\s*?$', '', got)
1604 if got == want:
1605 return True
1606
1607 # This flag causes doctest to ignore any differences in the
1608 # contents of whitespace strings. Note that this can be used
Tim Peters3fa8c202004-08-23 21:43:39 +00001609 # in conjunction with the ELLIPSIS flag.
Tim Peters1cf3aa62004-08-19 06:49:33 +00001610 if optionflags & NORMALIZE_WHITESPACE:
Edward Loper34fcb142004-08-09 02:45:41 +00001611 got = ' '.join(got.split())
1612 want = ' '.join(want.split())
1613 if got == want:
1614 return True
1615
1616 # The ELLIPSIS flag says to let the sequence "..." in `want`
Tim Peters26b3ebb2004-08-19 08:10:08 +00001617 # match any substring in `got`.
Tim Peters1cf3aa62004-08-19 06:49:33 +00001618 if optionflags & ELLIPSIS:
Tim Petersb0a04e12004-08-20 02:08:04 +00001619 if _ellipsis_match(want, got):
Edward Loper34fcb142004-08-09 02:45:41 +00001620 return True
1621
1622 # We didn't find any match; return false.
1623 return False
1624
Tim Petersc6cbab02004-08-22 19:43:28 +00001625 # Should we do a fancy diff?
1626 def _do_a_fancy_diff(self, want, got, optionflags):
1627 # Not unless they asked for a fancy diff.
Edward Loper71f55af2004-08-26 01:41:51 +00001628 if not optionflags & (REPORT_UDIFF |
1629 REPORT_CDIFF |
1630 REPORT_NDIFF):
Tim Petersc6cbab02004-08-22 19:43:28 +00001631 return False
Tim Peters5b799c12004-08-26 05:21:59 +00001632
Tim Petersc6cbab02004-08-22 19:43:28 +00001633 # If expected output uses ellipsis, a meaningful fancy diff is
Tim Peters5b799c12004-08-26 05:21:59 +00001634 # too hard ... or maybe not. In two real-life failures Tim saw,
1635 # a diff was a major help anyway, so this is commented out.
1636 # [todo] _ellipsis_match() knows which pieces do and don't match,
1637 # and could be the basis for a kick-ass diff in this case.
1638 ##if optionflags & ELLIPSIS and ELLIPSIS_MARKER in want:
1639 ## return False
1640
Tim Petersc6cbab02004-08-22 19:43:28 +00001641 # ndiff does intraline difference marking, so can be useful even
Tim Peters5b799c12004-08-26 05:21:59 +00001642 # for 1-line differences.
Edward Loper71f55af2004-08-26 01:41:51 +00001643 if optionflags & REPORT_NDIFF:
Tim Petersc6cbab02004-08-22 19:43:28 +00001644 return True
Tim Peters5b799c12004-08-26 05:21:59 +00001645
Tim Petersc6cbab02004-08-22 19:43:28 +00001646 # The other diff types need at least a few lines to be helpful.
1647 return want.count('\n') > 2 and got.count('\n') > 2
1648
Edward Loperca9111e2004-08-26 03:00:24 +00001649 def output_difference(self, example, got, optionflags):
Edward Loper34fcb142004-08-09 02:45:41 +00001650 """
1651 Return a string describing the differences between the
Edward Loperca9111e2004-08-26 03:00:24 +00001652 expected output for a given example (`example`) and the actual
1653 output (`got`). `optionflags` is the set of option flags used
1654 to compare `want` and `got`.
Edward Loper34fcb142004-08-09 02:45:41 +00001655 """
Edward Loperca9111e2004-08-26 03:00:24 +00001656 want = example.want
Edward Loper68ba9a62004-08-12 02:43:49 +00001657 # If <BLANKLINE>s are being used, then replace blank lines
1658 # with <BLANKLINE> in the actual output string.
Edward Loper34fcb142004-08-09 02:45:41 +00001659 if not (optionflags & DONT_ACCEPT_BLANKLINE):
Edward Loper68ba9a62004-08-12 02:43:49 +00001660 got = re.sub('(?m)^[ ]*(?=\n)', BLANKLINE_MARKER, got)
Edward Loper34fcb142004-08-09 02:45:41 +00001661
Tim Peters5b799c12004-08-26 05:21:59 +00001662 # Check if we should use diff.
Tim Petersc6cbab02004-08-22 19:43:28 +00001663 if self._do_a_fancy_diff(want, got, optionflags):
Edward Loper34fcb142004-08-09 02:45:41 +00001664 # Split want & got into lines.
Ezio Melottid8b509b2011-09-28 17:37:55 +03001665 want_lines = want.splitlines(keepends=True)
1666 got_lines = got.splitlines(keepends=True)
Edward Loper34fcb142004-08-09 02:45:41 +00001667 # Use difflib to find their differences.
Edward Loper71f55af2004-08-26 01:41:51 +00001668 if optionflags & REPORT_UDIFF:
Edward Loper56629292004-08-26 01:31:56 +00001669 diff = difflib.unified_diff(want_lines, got_lines, n=2)
1670 diff = list(diff)[2:] # strip the diff header
1671 kind = 'unified diff with -expected +actual'
Edward Loper71f55af2004-08-26 01:41:51 +00001672 elif optionflags & REPORT_CDIFF:
Edward Loper56629292004-08-26 01:31:56 +00001673 diff = difflib.context_diff(want_lines, got_lines, n=2)
1674 diff = list(diff)[2:] # strip the diff header
1675 kind = 'context diff with expected followed by actual'
Edward Loper71f55af2004-08-26 01:41:51 +00001676 elif optionflags & REPORT_NDIFF:
Tim Petersc6cbab02004-08-22 19:43:28 +00001677 engine = difflib.Differ(charjunk=difflib.IS_CHARACTER_JUNK)
1678 diff = list(engine.compare(want_lines, got_lines))
1679 kind = 'ndiff with -expected +actual'
Edward Loper34fcb142004-08-09 02:45:41 +00001680 else:
1681 assert 0, 'Bad diff option'
1682 # Remove trailing whitespace on diff output.
1683 diff = [line.rstrip() + '\n' for line in diff]
Edward Loperaacf0832004-08-26 01:19:50 +00001684 return 'Differences (%s):\n' % kind + _indent(''.join(diff))
Edward Loper34fcb142004-08-09 02:45:41 +00001685
1686 # If we're not using diff, then simply list the expected
1687 # output followed by the actual output.
Edward Loperaacf0832004-08-26 01:19:50 +00001688 if want and got:
1689 return 'Expected:\n%sGot:\n%s' % (_indent(want), _indent(got))
1690 elif want:
1691 return 'Expected:\n%sGot nothing\n' % _indent(want)
1692 elif got:
1693 return 'Expected nothing\nGot:\n%s' % _indent(got)
1694 else:
1695 return 'Expected nothing\nGot nothing\n'
Edward Loper34fcb142004-08-09 02:45:41 +00001696
Tim Peters19397e52004-08-06 22:02:59 +00001697class DocTestFailure(Exception):
1698 """A DocTest example has failed in debugging mode.
1699
1700 The exception instance has variables:
1701
1702 - test: the DocTest object being run
1703
Neal Norwitzc082cb72006-08-29 05:40:08 +00001704 - example: the Example object that failed
Tim Peters19397e52004-08-06 22:02:59 +00001705
1706 - got: the actual output
1707 """
1708 def __init__(self, test, example, got):
1709 self.test = test
1710 self.example = example
1711 self.got = got
1712
1713 def __str__(self):
1714 return str(self.test)
1715
1716class UnexpectedException(Exception):
1717 """A DocTest example has encountered an unexpected exception
1718
1719 The exception instance has variables:
1720
1721 - test: the DocTest object being run
1722
Guido van Rossum6a2a2a02006-08-26 20:37:44 +00001723 - example: the Example object that failed
Tim Peters19397e52004-08-06 22:02:59 +00001724
1725 - exc_info: the exception info
1726 """
1727 def __init__(self, test, example, exc_info):
1728 self.test = test
1729 self.example = example
1730 self.exc_info = exc_info
1731
1732 def __str__(self):
1733 return str(self.test)
Tim Petersd1b78272004-08-07 06:03:09 +00001734
Tim Peters19397e52004-08-06 22:02:59 +00001735class DebugRunner(DocTestRunner):
1736 r"""Run doc tests but raise an exception as soon as there is a failure.
1737
1738 If an unexpected exception occurs, an UnexpectedException is raised.
1739 It contains the test, the example, and the original exception:
1740
1741 >>> runner = DebugRunner(verbose=False)
Edward Lopera1ef6112004-08-09 16:14:41 +00001742 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
1743 ... {}, 'foo', 'foo.py', 0)
Tim Peters19397e52004-08-06 22:02:59 +00001744 >>> try:
1745 ... runner.run(test)
Guido van Rossumb940e112007-01-10 16:19:56 +00001746 ... except UnexpectedException as f:
1747 ... failure = f
Tim Peters19397e52004-08-06 22:02:59 +00001748
1749 >>> failure.test is test
1750 True
1751
1752 >>> failure.example.want
1753 '42\n'
1754
1755 >>> exc_info = failure.exc_info
Collin Winter828f04a2007-08-31 00:04:24 +00001756 >>> raise exc_info[1] # Already has the traceback
Tim Peters19397e52004-08-06 22:02:59 +00001757 Traceback (most recent call last):
1758 ...
1759 KeyError
1760
1761 We wrap the original exception to give the calling application
1762 access to the test and example information.
1763
1764 If the output doesn't match, then a DocTestFailure is raised:
1765
Edward Lopera1ef6112004-08-09 16:14:41 +00001766 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00001767 ... >>> x = 1
1768 ... >>> x
1769 ... 2
1770 ... ''', {}, 'foo', 'foo.py', 0)
1771
1772 >>> try:
1773 ... runner.run(test)
Guido van Rossumb940e112007-01-10 16:19:56 +00001774 ... except DocTestFailure as f:
1775 ... failure = f
Tim Peters19397e52004-08-06 22:02:59 +00001776
1777 DocTestFailure objects provide access to the test:
1778
1779 >>> failure.test is test
1780 True
1781
1782 As well as to the example:
1783
1784 >>> failure.example.want
1785 '2\n'
1786
1787 and the actual output:
1788
1789 >>> failure.got
1790 '1\n'
1791
1792 If a failure or error occurs, the globals are left intact:
1793
1794 >>> del test.globs['__builtins__']
1795 >>> test.globs
1796 {'x': 1}
1797
Edward Lopera1ef6112004-08-09 16:14:41 +00001798 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00001799 ... >>> x = 2
1800 ... >>> raise KeyError
1801 ... ''', {}, 'foo', 'foo.py', 0)
1802
1803 >>> runner.run(test)
1804 Traceback (most recent call last):
1805 ...
Guido van Rossum6a2a2a02006-08-26 20:37:44 +00001806 doctest.UnexpectedException: <DocTest foo from foo.py:0 (2 examples)>
Tim Petersd1b78272004-08-07 06:03:09 +00001807
Tim Peters19397e52004-08-06 22:02:59 +00001808 >>> del test.globs['__builtins__']
1809 >>> test.globs
1810 {'x': 2}
1811
1812 But the globals are cleared if there is no error:
1813
Edward Lopera1ef6112004-08-09 16:14:41 +00001814 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00001815 ... >>> x = 2
1816 ... ''', {}, 'foo', 'foo.py', 0)
1817
1818 >>> runner.run(test)
Christian Heimes25bb7832008-01-11 16:17:00 +00001819 TestResults(failed=0, attempted=1)
Tim Peters19397e52004-08-06 22:02:59 +00001820
1821 >>> test.globs
1822 {}
1823
1824 """
1825
1826 def run(self, test, compileflags=None, out=None, clear_globs=True):
1827 r = DocTestRunner.run(self, test, compileflags, out, False)
1828 if clear_globs:
1829 test.globs.clear()
1830 return r
1831
1832 def report_unexpected_exception(self, out, test, example, exc_info):
1833 raise UnexpectedException(test, example, exc_info)
1834
1835 def report_failure(self, out, test, example, got):
1836 raise DocTestFailure(test, example, got)
1837
Tim Peters8485b562004-08-04 18:46:34 +00001838######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00001839## 6. Test Functions
Tim Peters8485b562004-08-04 18:46:34 +00001840######################################################################
1841# These should be backwards compatible.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001842
Tim Peters82076ef2004-09-13 00:52:51 +00001843# For backward compatibility, a global instance of a DocTestRunner
1844# class, updated by testmod.
1845master = None
1846
Thomas Wouters73e5a5b2006-06-08 15:35:45 +00001847def testmod(m=None, name=None, globs=None, verbose=None,
Tim Peters19397e52004-08-06 22:02:59 +00001848 report=True, optionflags=0, extraglobs=None,
Tim Peters958cc892004-09-13 14:53:28 +00001849 raise_on_error=False, exclude_empty=False):
Thomas Wouters73e5a5b2006-06-08 15:35:45 +00001850 """m=None, name=None, globs=None, verbose=None, report=True,
1851 optionflags=0, extraglobs=None, raise_on_error=False,
Tim Peters958cc892004-09-13 14:53:28 +00001852 exclude_empty=False
Tim Peters8a7d2d52001-01-16 07:10:57 +00001853
Martin v. Löwis4581cfa2002-11-22 08:23:09 +00001854 Test examples in docstrings in functions and classes reachable
1855 from module m (or the current module if m is not supplied), starting
Thomas Wouters73e5a5b2006-06-08 15:35:45 +00001856 with m.__doc__.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001857
1858 Also test examples reachable from dict m.__test__ if it exists and is
Tim Petersc2388a22004-08-10 01:41:28 +00001859 not None. m.__test__ maps names to functions, classes and strings;
Tim Peters8a7d2d52001-01-16 07:10:57 +00001860 function and class docstrings are tested even if the name is private;
1861 strings are tested directly, as if they were docstrings.
1862
1863 Return (#failures, #tests).
1864
Alexander Belopolsky977a6842010-08-16 20:17:07 +00001865 See help(doctest) for an overview.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001866
1867 Optional keyword arg "name" gives the name of the module; by default
1868 use m.__name__.
1869
1870 Optional keyword arg "globs" gives a dict to be used as the globals
1871 when executing examples; by default, use m.__dict__. A copy of this
1872 dict is actually used for each docstring, so that each docstring's
1873 examples start with a clean slate.
1874
Tim Peters8485b562004-08-04 18:46:34 +00001875 Optional keyword arg "extraglobs" gives a dictionary that should be
1876 merged into the globals that are used to execute examples. By
1877 default, no extra globals are used. This is new in 2.4.
1878
Tim Peters8a7d2d52001-01-16 07:10:57 +00001879 Optional keyword arg "verbose" prints lots of stuff if true, prints
1880 only failures if false; by default, it's true iff "-v" is in sys.argv.
1881
Tim Peters8a7d2d52001-01-16 07:10:57 +00001882 Optional keyword arg "report" prints a summary at the end when true,
1883 else prints nothing at the end. In verbose mode, the summary is
1884 detailed, else very brief (in fact, empty if all tests passed).
1885
Tim Peters6ebe61f2003-06-27 20:48:05 +00001886 Optional keyword arg "optionflags" or's together module constants,
Tim Petersf82a9de2004-08-22 20:51:53 +00001887 and defaults to 0. This is new in 2.3. Possible values (see the
1888 docs for details):
Tim Peters6ebe61f2003-06-27 20:48:05 +00001889
1890 DONT_ACCEPT_TRUE_FOR_1
Tim Peters8485b562004-08-04 18:46:34 +00001891 DONT_ACCEPT_BLANKLINE
Tim Peters8485b562004-08-04 18:46:34 +00001892 NORMALIZE_WHITESPACE
Tim Peters8485b562004-08-04 18:46:34 +00001893 ELLIPSIS
Thomas Wouters477c8d52006-05-27 19:21:47 +00001894 SKIP
Edward Loper052d0cd2004-09-19 17:19:33 +00001895 IGNORE_EXCEPTION_DETAIL
Edward Loper71f55af2004-08-26 01:41:51 +00001896 REPORT_UDIFF
1897 REPORT_CDIFF
1898 REPORT_NDIFF
Edward Lopera89f88d2004-08-26 02:45:51 +00001899 REPORT_ONLY_FIRST_FAILURE
Tim Peters19397e52004-08-06 22:02:59 +00001900
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
Tim Peters8a7d2d52001-01-16 07:10:57 +00001905 Advanced tomfoolery: testmod runs methods of a local instance of
1906 class doctest.Tester, then merges the results into (or creates)
1907 global Tester instance doctest.master. Methods of doctest.master
1908 can be called directly too, if you want to do something unusual.
1909 Passing report=0 to testmod is especially useful then, to delay
1910 displaying a summary. Invoke doctest.master.summarize(verbose)
1911 when you're done fiddling.
1912 """
Tim Peters82076ef2004-09-13 00:52:51 +00001913 global master
1914
Tim Peters8485b562004-08-04 18:46:34 +00001915 # If no module was given, then use __main__.
Martin v. Löwis4581cfa2002-11-22 08:23:09 +00001916 if m is None:
Martin v. Löwis4581cfa2002-11-22 08:23:09 +00001917 # DWA - m will still be None if this wasn't invoked from the command
1918 # line, in which case the following TypeError is about as good an error
1919 # as we should expect
1920 m = sys.modules.get('__main__')
1921
Tim Peters8485b562004-08-04 18:46:34 +00001922 # Check that we were actually given a module.
1923 if not inspect.ismodule(m):
Walter Dörwald70a6b492004-02-12 17:35:32 +00001924 raise TypeError("testmod: module required; %r" % (m,))
Tim Peters8485b562004-08-04 18:46:34 +00001925
1926 # If no name was given, then use the module's name.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001927 if name is None:
1928 name = m.__name__
Tim Peters8485b562004-08-04 18:46:34 +00001929
1930 # Find, parse, and run all tests in the given module.
Thomas Wouters73e5a5b2006-06-08 15:35:45 +00001931 finder = DocTestFinder(exclude_empty=exclude_empty)
Tim Peters19397e52004-08-06 22:02:59 +00001932
1933 if raise_on_error:
1934 runner = DebugRunner(verbose=verbose, optionflags=optionflags)
1935 else:
1936 runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1937
Tim Peters8485b562004-08-04 18:46:34 +00001938 for test in finder.find(m, name, globs=globs, extraglobs=extraglobs):
1939 runner.run(test)
1940
Tim Peters8a7d2d52001-01-16 07:10:57 +00001941 if report:
Tim Peters8485b562004-08-04 18:46:34 +00001942 runner.summarize()
Tim Peters8a7d2d52001-01-16 07:10:57 +00001943
Tim Peters82076ef2004-09-13 00:52:51 +00001944 if master is None:
1945 master = runner
1946 else:
1947 master.merge(runner)
1948
Christian Heimes25bb7832008-01-11 16:17:00 +00001949 return TestResults(runner.failures, runner.tries)
Tim Petersdb3756d2003-06-29 05:30:48 +00001950
Edward Loper052d0cd2004-09-19 17:19:33 +00001951def testfile(filename, module_relative=True, name=None, package=None,
1952 globs=None, verbose=None, report=True, optionflags=0,
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00001953 extraglobs=None, raise_on_error=False, parser=DocTestParser(),
1954 encoding=None):
Edward Loper052d0cd2004-09-19 17:19:33 +00001955 """
1956 Test examples in the given file. Return (#failures, #tests).
1957
1958 Optional keyword arg "module_relative" specifies how filenames
1959 should be interpreted:
1960
1961 - If "module_relative" is True (the default), then "filename"
1962 specifies a module-relative path. By default, this path is
1963 relative to the calling module's directory; but if the
1964 "package" argument is specified, then it is relative to that
1965 package. To ensure os-independence, "filename" should use
1966 "/" characters to separate path segments, and should not
1967 be an absolute path (i.e., it may not begin with "/").
1968
1969 - If "module_relative" is False, then "filename" specifies an
1970 os-specific path. The path may be absolute or relative (to
1971 the current working directory).
1972
Edward Lopera2fc7ec2004-09-21 03:24:24 +00001973 Optional keyword arg "name" gives the name of the test; by default
1974 use the file's basename.
Edward Loper052d0cd2004-09-19 17:19:33 +00001975
1976 Optional keyword argument "package" is a Python package or the
1977 name of a Python package whose directory should be used as the
1978 base directory for a module relative filename. If no package is
1979 specified, then the calling module's directory is used as the base
1980 directory for module relative filenames. It is an error to
1981 specify "package" if "module_relative" is False.
1982
1983 Optional keyword arg "globs" gives a dict to be used as the globals
1984 when executing examples; by default, use {}. A copy of this dict
1985 is actually used for each docstring, so that each docstring's
1986 examples start with a clean slate.
1987
1988 Optional keyword arg "extraglobs" gives a dictionary that should be
1989 merged into the globals that are used to execute examples. By
1990 default, no extra globals are used.
1991
1992 Optional keyword arg "verbose" prints lots of stuff if true, prints
1993 only failures if false; by default, it's true iff "-v" is in sys.argv.
1994
1995 Optional keyword arg "report" prints a summary at the end when true,
1996 else prints nothing at the end. In verbose mode, the summary is
1997 detailed, else very brief (in fact, empty if all tests passed).
1998
1999 Optional keyword arg "optionflags" or's together module constants,
2000 and defaults to 0. Possible values (see the docs for details):
2001
2002 DONT_ACCEPT_TRUE_FOR_1
2003 DONT_ACCEPT_BLANKLINE
2004 NORMALIZE_WHITESPACE
2005 ELLIPSIS
Thomas Wouters477c8d52006-05-27 19:21:47 +00002006 SKIP
Edward Loper052d0cd2004-09-19 17:19:33 +00002007 IGNORE_EXCEPTION_DETAIL
2008 REPORT_UDIFF
2009 REPORT_CDIFF
2010 REPORT_NDIFF
2011 REPORT_ONLY_FIRST_FAILURE
2012
2013 Optional keyword arg "raise_on_error" raises an exception on the
2014 first unexpected exception or failure. This allows failures to be
2015 post-mortem debugged.
2016
Edward Loper498a1862004-09-27 03:42:58 +00002017 Optional keyword arg "parser" specifies a DocTestParser (or
2018 subclass) that should be used to extract tests from the files.
2019
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00002020 Optional keyword arg "encoding" specifies an encoding that should
2021 be used to convert the file to unicode.
2022
Edward Loper052d0cd2004-09-19 17:19:33 +00002023 Advanced tomfoolery: testmod runs methods of a local instance of
2024 class doctest.Tester, then merges the results into (or creates)
2025 global Tester instance doctest.master. Methods of doctest.master
2026 can be called directly too, if you want to do something unusual.
2027 Passing report=0 to testmod is especially useful then, to delay
2028 displaying a summary. Invoke doctest.master.summarize(verbose)
2029 when you're done fiddling.
2030 """
2031 global master
2032
2033 if package and not module_relative:
2034 raise ValueError("Package may only be specified for module-"
2035 "relative paths.")
Tim Petersbab3e992004-09-20 19:52:34 +00002036
Edward Loper052d0cd2004-09-19 17:19:33 +00002037 # Relativize the path
Guido van Rossum1b81e7b2007-08-29 03:53:53 +00002038 text, filename = _load_testfile(filename, package, module_relative,
2039 encoding or "utf-8")
Edward Loper052d0cd2004-09-19 17:19:33 +00002040
2041 # If no name was given, then use the file's name.
2042 if name is None:
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002043 name = os.path.basename(filename)
Edward Loper052d0cd2004-09-19 17:19:33 +00002044
2045 # Assemble the globals.
2046 if globs is None:
2047 globs = {}
2048 else:
2049 globs = globs.copy()
2050 if extraglobs is not None:
2051 globs.update(extraglobs)
Raymond Hettinger0f055172009-01-27 10:06:09 +00002052 if '__name__' not in globs:
2053 globs['__name__'] = '__main__'
Edward Loper052d0cd2004-09-19 17:19:33 +00002054
2055 if raise_on_error:
2056 runner = DebugRunner(verbose=verbose, optionflags=optionflags)
2057 else:
2058 runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
2059
2060 # Read the file, convert it to a test, and run it.
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00002061 test = parser.get_doctest(text, globs, name, filename, 0)
Edward Loper052d0cd2004-09-19 17:19:33 +00002062 runner.run(test)
2063
2064 if report:
2065 runner.summarize()
2066
2067 if master is None:
2068 master = runner
2069 else:
2070 master.merge(runner)
2071
Christian Heimes25bb7832008-01-11 16:17:00 +00002072 return TestResults(runner.failures, runner.tries)
Edward Loper052d0cd2004-09-19 17:19:33 +00002073
Tim Peters8485b562004-08-04 18:46:34 +00002074def run_docstring_examples(f, globs, verbose=False, name="NoName",
2075 compileflags=None, optionflags=0):
2076 """
2077 Test examples in the given object's docstring (`f`), using `globs`
2078 as globals. Optional argument `name` is used in failure messages.
2079 If the optional argument `verbose` is true, then generate output
2080 even if there are no failures.
Tim Petersdb3756d2003-06-29 05:30:48 +00002081
Tim Peters8485b562004-08-04 18:46:34 +00002082 `compileflags` gives the set of flags that should be used by the
2083 Python compiler when running the examples. If not specified, then
2084 it will default to the set of future-import flags that apply to
2085 `globs`.
Tim Petersdb3756d2003-06-29 05:30:48 +00002086
Tim Peters8485b562004-08-04 18:46:34 +00002087 Optional keyword arg `optionflags` specifies options for the
2088 testing and output. See the documentation for `testmod` for more
2089 information.
2090 """
2091 # Find, parse, and run all tests in the given module.
2092 finder = DocTestFinder(verbose=verbose, recurse=False)
2093 runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
2094 for test in finder.find(f, name, globs=globs):
2095 runner.run(test, compileflags=compileflags)
Tim Petersdb3756d2003-06-29 05:30:48 +00002096
Tim Peters8485b562004-08-04 18:46:34 +00002097######################################################################
Georg Brandl31835852008-05-12 17:38:56 +00002098## 7. Unittest Support
Tim Peters8485b562004-08-04 18:46:34 +00002099######################################################################
Tim Petersdb3756d2003-06-29 05:30:48 +00002100
Jim Fultonf54bad42004-08-28 14:57:56 +00002101_unittest_reportflags = 0
Tim Peters38330fe2004-08-30 16:19:24 +00002102
Jim Fultonf54bad42004-08-28 14:57:56 +00002103def set_unittest_reportflags(flags):
Tim Peters38330fe2004-08-30 16:19:24 +00002104 """Sets the unittest option flags.
Jim Fultonf54bad42004-08-28 14:57:56 +00002105
2106 The old flag is returned so that a runner could restore the old
2107 value if it wished to:
2108
Tim Petersb7e99b62005-03-28 23:50:54 +00002109 >>> import doctest
2110 >>> old = doctest._unittest_reportflags
2111 >>> doctest.set_unittest_reportflags(REPORT_NDIFF |
Jim Fultonf54bad42004-08-28 14:57:56 +00002112 ... REPORT_ONLY_FIRST_FAILURE) == old
2113 True
2114
Jim Fultonf54bad42004-08-28 14:57:56 +00002115 >>> doctest._unittest_reportflags == (REPORT_NDIFF |
2116 ... REPORT_ONLY_FIRST_FAILURE)
2117 True
Tim Petersdf7a2082004-08-29 00:38:17 +00002118
Jim Fultonf54bad42004-08-28 14:57:56 +00002119 Only reporting flags can be set:
2120
Tim Petersb7e99b62005-03-28 23:50:54 +00002121 >>> doctest.set_unittest_reportflags(ELLIPSIS)
Jim Fultonf54bad42004-08-28 14:57:56 +00002122 Traceback (most recent call last):
2123 ...
Tim Peters38330fe2004-08-30 16:19:24 +00002124 ValueError: ('Only reporting flags allowed', 8)
Jim Fultonf54bad42004-08-28 14:57:56 +00002125
Tim Petersb7e99b62005-03-28 23:50:54 +00002126 >>> doctest.set_unittest_reportflags(old) == (REPORT_NDIFF |
Jim Fultonf54bad42004-08-28 14:57:56 +00002127 ... REPORT_ONLY_FIRST_FAILURE)
2128 True
Jim Fultonf54bad42004-08-28 14:57:56 +00002129 """
Jim Fultonf54bad42004-08-28 14:57:56 +00002130 global _unittest_reportflags
Tim Peters38330fe2004-08-30 16:19:24 +00002131
2132 if (flags & REPORTING_FLAGS) != flags:
2133 raise ValueError("Only reporting flags allowed", flags)
Jim Fultonf54bad42004-08-28 14:57:56 +00002134 old = _unittest_reportflags
2135 _unittest_reportflags = flags
2136 return old
Tim Petersdf7a2082004-08-29 00:38:17 +00002137
Jim Fultonf54bad42004-08-28 14:57:56 +00002138
Tim Peters19397e52004-08-06 22:02:59 +00002139class DocTestCase(unittest.TestCase):
Tim Petersdb3756d2003-06-29 05:30:48 +00002140
Edward Loper34fcb142004-08-09 02:45:41 +00002141 def __init__(self, test, optionflags=0, setUp=None, tearDown=None,
2142 checker=None):
Jim Fulton07a349c2004-08-22 14:10:00 +00002143
Jim Fultona643b652004-07-14 19:06:50 +00002144 unittest.TestCase.__init__(self)
Tim Peters19397e52004-08-06 22:02:59 +00002145 self._dt_optionflags = optionflags
Edward Loper34fcb142004-08-09 02:45:41 +00002146 self._dt_checker = checker
Tim Peters19397e52004-08-06 22:02:59 +00002147 self._dt_test = test
2148 self._dt_setUp = setUp
2149 self._dt_tearDown = tearDown
Tim Petersdb3756d2003-06-29 05:30:48 +00002150
Jim Fultona643b652004-07-14 19:06:50 +00002151 def setUp(self):
Jim Fultonf54bad42004-08-28 14:57:56 +00002152 test = self._dt_test
Tim Petersdf7a2082004-08-29 00:38:17 +00002153
Tim Peters19397e52004-08-06 22:02:59 +00002154 if self._dt_setUp is not None:
Jim Fultonf54bad42004-08-28 14:57:56 +00002155 self._dt_setUp(test)
Jim Fultona643b652004-07-14 19:06:50 +00002156
2157 def tearDown(self):
Jim Fultonf54bad42004-08-28 14:57:56 +00002158 test = self._dt_test
2159
Tim Peters19397e52004-08-06 22:02:59 +00002160 if self._dt_tearDown is not None:
Jim Fultonf54bad42004-08-28 14:57:56 +00002161 self._dt_tearDown(test)
2162
2163 test.globs.clear()
Jim Fultona643b652004-07-14 19:06:50 +00002164
2165 def runTest(self):
Tim Peters19397e52004-08-06 22:02:59 +00002166 test = self._dt_test
Jim Fultona643b652004-07-14 19:06:50 +00002167 old = sys.stdout
2168 new = StringIO()
Jim Fultonf54bad42004-08-28 14:57:56 +00002169 optionflags = self._dt_optionflags
Tim Petersdf7a2082004-08-29 00:38:17 +00002170
Tim Peters38330fe2004-08-30 16:19:24 +00002171 if not (optionflags & REPORTING_FLAGS):
Jim Fultonf54bad42004-08-28 14:57:56 +00002172 # The option flags don't include any reporting flags,
2173 # so add the default reporting flags
2174 optionflags |= _unittest_reportflags
Tim Petersdf7a2082004-08-29 00:38:17 +00002175
Jim Fultonf54bad42004-08-28 14:57:56 +00002176 runner = DocTestRunner(optionflags=optionflags,
Edward Loper34fcb142004-08-09 02:45:41 +00002177 checker=self._dt_checker, verbose=False)
Tim Peters19397e52004-08-06 22:02:59 +00002178
Jim Fultona643b652004-07-14 19:06:50 +00002179 try:
Tim Peters19397e52004-08-06 22:02:59 +00002180 runner.DIVIDER = "-"*70
Jim Fultonf54bad42004-08-28 14:57:56 +00002181 failures, tries = runner.run(
2182 test, out=new.write, clear_globs=False)
Jim Fultona643b652004-07-14 19:06:50 +00002183 finally:
2184 sys.stdout = old
2185
2186 if failures:
Tim Peters19397e52004-08-06 22:02:59 +00002187 raise self.failureException(self.format_failure(new.getvalue()))
Tim Peters8485b562004-08-04 18:46:34 +00002188
Tim Peters19397e52004-08-06 22:02:59 +00002189 def format_failure(self, err):
2190 test = self._dt_test
2191 if test.lineno is None:
2192 lineno = 'unknown line number'
2193 else:
Jim Fulton07a349c2004-08-22 14:10:00 +00002194 lineno = '%s' % test.lineno
Tim Peters19397e52004-08-06 22:02:59 +00002195 lname = '.'.join(test.name.split('.')[-1:])
2196 return ('Failed doctest test for %s\n'
2197 ' File "%s", line %s, in %s\n\n%s'
2198 % (test.name, test.filename, lineno, lname, err)
2199 )
2200
2201 def debug(self):
2202 r"""Run the test case without results and without catching exceptions
2203
2204 The unit test framework includes a debug method on test cases
2205 and test suites to support post-mortem debugging. The test code
2206 is run in such a way that errors are not caught. This way a
2207 caller can catch the errors and initiate post-mortem debugging.
2208
2209 The DocTestCase provides a debug method that raises
Ezio Melotti13925002011-03-16 11:05:33 +02002210 UnexpectedException errors if there is an unexpected
Tim Peters19397e52004-08-06 22:02:59 +00002211 exception:
2212
Edward Lopera1ef6112004-08-09 16:14:41 +00002213 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
Tim Peters19397e52004-08-06 22:02:59 +00002214 ... {}, 'foo', 'foo.py', 0)
2215 >>> case = DocTestCase(test)
2216 >>> try:
2217 ... case.debug()
Guido van Rossumb940e112007-01-10 16:19:56 +00002218 ... except UnexpectedException as f:
2219 ... failure = f
Tim Peters19397e52004-08-06 22:02:59 +00002220
2221 The UnexpectedException contains the test, the example, and
2222 the original exception:
2223
2224 >>> failure.test is test
2225 True
2226
2227 >>> failure.example.want
2228 '42\n'
2229
2230 >>> exc_info = failure.exc_info
Collin Winter828f04a2007-08-31 00:04:24 +00002231 >>> raise exc_info[1] # Already has the traceback
Tim Peters19397e52004-08-06 22:02:59 +00002232 Traceback (most recent call last):
2233 ...
2234 KeyError
2235
2236 If the output doesn't match, then a DocTestFailure is raised:
2237
Edward Lopera1ef6112004-08-09 16:14:41 +00002238 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00002239 ... >>> x = 1
2240 ... >>> x
2241 ... 2
2242 ... ''', {}, 'foo', 'foo.py', 0)
2243 >>> case = DocTestCase(test)
2244
2245 >>> try:
2246 ... case.debug()
Guido van Rossumb940e112007-01-10 16:19:56 +00002247 ... except DocTestFailure as f:
2248 ... failure = f
Tim Peters19397e52004-08-06 22:02:59 +00002249
2250 DocTestFailure objects provide access to the test:
2251
2252 >>> failure.test is test
2253 True
2254
2255 As well as to the example:
2256
2257 >>> failure.example.want
2258 '2\n'
2259
2260 and the actual output:
2261
2262 >>> failure.got
2263 '1\n'
2264
2265 """
2266
Jim Fultonf54bad42004-08-28 14:57:56 +00002267 self.setUp()
Edward Loper34fcb142004-08-09 02:45:41 +00002268 runner = DebugRunner(optionflags=self._dt_optionflags,
2269 checker=self._dt_checker, verbose=False)
Alexandre Vassalottieca20b62008-05-16 02:54:33 +00002270 runner.run(self._dt_test, clear_globs=False)
Jim Fultonf54bad42004-08-28 14:57:56 +00002271 self.tearDown()
Jim Fultona643b652004-07-14 19:06:50 +00002272
2273 def id(self):
Tim Peters19397e52004-08-06 22:02:59 +00002274 return self._dt_test.name
Jim Fultona643b652004-07-14 19:06:50 +00002275
Antoine Pitrou2bc801c2011-12-18 19:27:45 +01002276 def __eq__(self, other):
2277 if type(self) is not type(other):
2278 return NotImplemented
2279
2280 return self._dt_test == other._dt_test and \
2281 self._dt_optionflags == other._dt_optionflags and \
2282 self._dt_setUp == other._dt_setUp and \
2283 self._dt_tearDown == other._dt_tearDown and \
2284 self._dt_checker == other._dt_checker
2285
2286 def __ne__(self, other):
2287 return not self == other
2288
Antoine Pitrou165b1282011-12-18 20:20:17 +01002289 def __hash__(self):
2290 return hash((self._dt_optionflags, self._dt_setUp, self._dt_tearDown,
2291 self._dt_checker))
2292
Jim Fultona643b652004-07-14 19:06:50 +00002293 def __repr__(self):
Tim Peters19397e52004-08-06 22:02:59 +00002294 name = self._dt_test.name.split('.')
Jim Fultona643b652004-07-14 19:06:50 +00002295 return "%s (%s)" % (name[-1], '.'.join(name[:-1]))
2296
2297 __str__ = __repr__
2298
2299 def shortDescription(self):
Tim Peters19397e52004-08-06 22:02:59 +00002300 return "Doctest: " + self._dt_test.name
Jim Fultona643b652004-07-14 19:06:50 +00002301
R. David Murray378c0cf2010-02-24 01:46:21 +00002302class SkipDocTestCase(DocTestCase):
R David Murraye1121532012-03-21 14:53:42 -04002303 def __init__(self, module):
2304 self.module = module
R. David Murray378c0cf2010-02-24 01:46:21 +00002305 DocTestCase.__init__(self, None)
2306
2307 def setUp(self):
2308 self.skipTest("DocTestSuite will not work with -O2 and above")
2309
2310 def test_skip(self):
2311 pass
2312
2313 def shortDescription(self):
R David Murraye1121532012-03-21 14:53:42 -04002314 return "Skipping tests from %s" % self.module.__name__
2315
2316 __str__ = shortDescription
2317
R. David Murray378c0cf2010-02-24 01:46:21 +00002318
Andrew Svetlov7c1017b2013-08-29 01:24:39 +03002319class _DocTestSuite(unittest.TestSuite):
2320
2321 def _removeTestAtIndex(self, index):
2322 pass
2323
2324
Jim Fultonf54bad42004-08-28 14:57:56 +00002325def DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None,
2326 **options):
Tim Peters8485b562004-08-04 18:46:34 +00002327 """
Tim Peters75dc5e12004-08-22 17:50:45 +00002328 Convert doctest tests for a module to a unittest test suite.
Jim Fultona643b652004-07-14 19:06:50 +00002329
Tim Peters19397e52004-08-06 22:02:59 +00002330 This converts each documentation string in a module that
2331 contains doctest tests to a unittest test case. If any of the
2332 tests in a doc string fail, then the test case fails. An exception
2333 is raised showing the name of the file containing the test and a
Jim Fultona643b652004-07-14 19:06:50 +00002334 (sometimes approximate) line number.
2335
Tim Peters19397e52004-08-06 22:02:59 +00002336 The `module` argument provides the module to be tested. The argument
Jim Fultona643b652004-07-14 19:06:50 +00002337 can be either a module or a module name.
2338
2339 If no argument is given, the calling module is used.
Jim Fultonf54bad42004-08-28 14:57:56 +00002340
2341 A number of options may be provided as keyword arguments:
2342
Jim Fultonf54bad42004-08-28 14:57:56 +00002343 setUp
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002344 A set-up function. This is called before running the
Jim Fultonf54bad42004-08-28 14:57:56 +00002345 tests in each file. The setUp function will be passed a DocTest
2346 object. The setUp function can access the test globals as the
2347 globs attribute of the test passed.
2348
2349 tearDown
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002350 A tear-down function. This is called after running the
Jim Fultonf54bad42004-08-28 14:57:56 +00002351 tests in each file. The tearDown function will be passed a DocTest
2352 object. The tearDown function can access the test globals as the
2353 globs attribute of the test passed.
2354
2355 globs
2356 A dictionary containing initial global variables for the tests.
2357
2358 optionflags
2359 A set of doctest option flags expressed as an integer.
Jim Fultona643b652004-07-14 19:06:50 +00002360 """
Jim Fultona643b652004-07-14 19:06:50 +00002361
Tim Peters8485b562004-08-04 18:46:34 +00002362 if test_finder is None:
2363 test_finder = DocTestFinder()
Tim Peters8485b562004-08-04 18:46:34 +00002364
Tim Peters19397e52004-08-06 22:02:59 +00002365 module = _normalize_module(module)
2366 tests = test_finder.find(module, globs=globs, extraglobs=extraglobs)
R. David Murray378c0cf2010-02-24 01:46:21 +00002367
2368 if not tests and sys.flags.optimize >=2:
2369 # Skip doctests when running with -O2
Andrew Svetlov7c1017b2013-08-29 01:24:39 +03002370 suite = _DocTestSuite()
R David Murraye1121532012-03-21 14:53:42 -04002371 suite.addTest(SkipDocTestCase(module))
R. David Murray378c0cf2010-02-24 01:46:21 +00002372 return suite
2373 elif not tests:
Jim Fultonf54bad42004-08-28 14:57:56 +00002374 # Why do we want to do this? Because it reveals a bug that might
2375 # otherwise be hidden.
R David Murray5abd76a2012-09-10 10:15:58 -04002376 # It is probably a bug that this exception is not also raised if the
2377 # number of doctest examples in tests is zero (i.e. if no doctest
2378 # examples were found). However, we should probably not be raising
2379 # an exception at all here, though it is too late to make this change
2380 # for a maintenance release. See also issue #14649.
2381 raise ValueError(module, "has no docstrings")
Tim Petersdb3756d2003-06-29 05:30:48 +00002382
2383 tests.sort()
Andrew Svetlov7c1017b2013-08-29 01:24:39 +03002384 suite = _DocTestSuite()
R. David Murray378c0cf2010-02-24 01:46:21 +00002385
Tim Peters8485b562004-08-04 18:46:34 +00002386 for test in tests:
Tim Peters19397e52004-08-06 22:02:59 +00002387 if len(test.examples) == 0:
2388 continue
Tim Peters8485b562004-08-04 18:46:34 +00002389 if not test.filename:
Tim Petersdb3756d2003-06-29 05:30:48 +00002390 filename = module.__file__
Jim Fulton07a349c2004-08-22 14:10:00 +00002391 if filename[-4:] in (".pyc", ".pyo"):
Tim Petersdb3756d2003-06-29 05:30:48 +00002392 filename = filename[:-1]
Tim Peters8485b562004-08-04 18:46:34 +00002393 test.filename = filename
Jim Fultonf54bad42004-08-28 14:57:56 +00002394 suite.addTest(DocTestCase(test, **options))
Tim Peters19397e52004-08-06 22:02:59 +00002395
2396 return suite
2397
2398class DocFileCase(DocTestCase):
2399
2400 def id(self):
2401 return '_'.join(self._dt_test.name.split('.'))
2402
2403 def __repr__(self):
2404 return self._dt_test.filename
2405 __str__ = __repr__
2406
2407 def format_failure(self, err):
2408 return ('Failed doctest test for %s\n File "%s", line 0\n\n%s'
2409 % (self._dt_test.name, self._dt_test.filename, err)
2410 )
2411
Edward Loper052d0cd2004-09-19 17:19:33 +00002412def DocFileTest(path, module_relative=True, package=None,
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00002413 globs=None, parser=DocTestParser(),
2414 encoding=None, **options):
Tim Peters19397e52004-08-06 22:02:59 +00002415 if globs is None:
2416 globs = {}
Fred Drake7c404a42004-12-21 23:46:34 +00002417 else:
2418 globs = globs.copy()
Tim Peters19397e52004-08-06 22:02:59 +00002419
Edward Loper052d0cd2004-09-19 17:19:33 +00002420 if package and not module_relative:
2421 raise ValueError("Package may only be specified for module-"
2422 "relative paths.")
Tim Petersbab3e992004-09-20 19:52:34 +00002423
Edward Loper052d0cd2004-09-19 17:19:33 +00002424 # Relativize the path.
Guido van Rossum1b81e7b2007-08-29 03:53:53 +00002425 doc, path = _load_testfile(path, package, module_relative,
2426 encoding or "utf-8")
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00002427
Fred Drake7c404a42004-12-21 23:46:34 +00002428 if "__file__" not in globs:
2429 globs["__file__"] = path
Tim Peters19397e52004-08-06 22:02:59 +00002430
Edward Loper052d0cd2004-09-19 17:19:33 +00002431 # Find the file and read it.
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002432 name = os.path.basename(path)
Edward Loper052d0cd2004-09-19 17:19:33 +00002433
2434 # Convert it to a test, and wrap it in a DocFileCase.
Edward Loper498a1862004-09-27 03:42:58 +00002435 test = parser.get_doctest(doc, globs, name, path, 0)
Jim Fultonf54bad42004-08-28 14:57:56 +00002436 return DocFileCase(test, **options)
Tim Peters19397e52004-08-06 22:02:59 +00002437
2438def DocFileSuite(*paths, **kw):
Edward Loper052d0cd2004-09-19 17:19:33 +00002439 """A unittest suite for one or more doctest files.
Tim Petersbab3e992004-09-20 19:52:34 +00002440
Edward Loper052d0cd2004-09-19 17:19:33 +00002441 The path to each doctest file is given as a string; the
2442 interpretation of that string depends on the keyword argument
2443 "module_relative".
Tim Peters19397e52004-08-06 22:02:59 +00002444
2445 A number of options may be provided as keyword arguments:
2446
Edward Loper052d0cd2004-09-19 17:19:33 +00002447 module_relative
2448 If "module_relative" is True, then the given file paths are
2449 interpreted as os-independent module-relative paths. By
2450 default, these paths are relative to the calling module's
2451 directory; but if the "package" argument is specified, then
2452 they are relative to that package. To ensure os-independence,
2453 "filename" should use "/" characters to separate path
2454 segments, and may not be an absolute path (i.e., it may not
2455 begin with "/").
Tim Petersbab3e992004-09-20 19:52:34 +00002456
Edward Loper052d0cd2004-09-19 17:19:33 +00002457 If "module_relative" is False, then the given file paths are
2458 interpreted as os-specific paths. These paths may be absolute
2459 or relative (to the current working directory).
2460
Tim Peters19397e52004-08-06 22:02:59 +00002461 package
Edward Loper052d0cd2004-09-19 17:19:33 +00002462 A Python package or the name of a Python package whose directory
2463 should be used as the base directory for module relative paths.
2464 If "package" is not specified, then the calling module's
2465 directory is used as the base directory for module relative
2466 filenames. It is an error to specify "package" if
2467 "module_relative" is False.
Tim Peters19397e52004-08-06 22:02:59 +00002468
2469 setUp
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002470 A set-up function. This is called before running the
Jim Fultonf54bad42004-08-28 14:57:56 +00002471 tests in each file. The setUp function will be passed a DocTest
2472 object. The setUp function can access the test globals as the
2473 globs attribute of the test passed.
Tim Peters19397e52004-08-06 22:02:59 +00002474
2475 tearDown
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002476 A tear-down function. This is called after running the
Jim Fultonf54bad42004-08-28 14:57:56 +00002477 tests in each file. The tearDown function will be passed a DocTest
2478 object. The tearDown function can access the test globals as the
2479 globs attribute of the test passed.
Tim Peters19397e52004-08-06 22:02:59 +00002480
2481 globs
2482 A dictionary containing initial global variables for the tests.
Jim Fultonf54bad42004-08-28 14:57:56 +00002483
2484 optionflags
Edward Loper498a1862004-09-27 03:42:58 +00002485 A set of doctest option flags expressed as an integer.
2486
2487 parser
2488 A DocTestParser (or subclass) that should be used to extract
2489 tests from the files.
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00002490
2491 encoding
2492 An encoding that will be used to convert the files to unicode.
Tim Peters19397e52004-08-06 22:02:59 +00002493 """
Andrew Svetlov7c1017b2013-08-29 01:24:39 +03002494 suite = _DocTestSuite()
Tim Peters19397e52004-08-06 22:02:59 +00002495
2496 # We do this here so that _normalize_module is called at the right
2497 # level. If it were called in DocFileTest, then this function
2498 # would be the caller and we might guess the package incorrectly.
Edward Loper052d0cd2004-09-19 17:19:33 +00002499 if kw.get('module_relative', True):
2500 kw['package'] = _normalize_module(kw.get('package'))
Tim Peters19397e52004-08-06 22:02:59 +00002501
2502 for path in paths:
2503 suite.addTest(DocFileTest(path, **kw))
Jim Fultona643b652004-07-14 19:06:50 +00002504
Tim Petersdb3756d2003-06-29 05:30:48 +00002505 return suite
2506
Tim Peters8485b562004-08-04 18:46:34 +00002507######################################################################
Georg Brandl31835852008-05-12 17:38:56 +00002508## 8. Debugging Support
Tim Peters8485b562004-08-04 18:46:34 +00002509######################################################################
Jim Fultona643b652004-07-14 19:06:50 +00002510
Tim Peters19397e52004-08-06 22:02:59 +00002511def script_from_examples(s):
2512 r"""Extract script from text with examples.
2513
2514 Converts text with examples to a Python script. Example input is
2515 converted to regular code. Example output and all other words
2516 are converted to comments:
2517
2518 >>> text = '''
2519 ... Here are examples of simple math.
2520 ...
2521 ... Python has super accurate integer addition
2522 ...
2523 ... >>> 2 + 2
2524 ... 5
2525 ...
2526 ... And very friendly error messages:
2527 ...
2528 ... >>> 1/0
2529 ... To Infinity
2530 ... And
2531 ... Beyond
2532 ...
2533 ... You can use logic if you want:
2534 ...
2535 ... >>> if 0:
2536 ... ... blah
2537 ... ... blah
2538 ... ...
2539 ...
2540 ... Ho hum
2541 ... '''
2542
Guido van Rossum7131f842007-02-09 20:13:25 +00002543 >>> print(script_from_examples(text))
Edward Lopera5db6002004-08-12 02:41:30 +00002544 # Here are examples of simple math.
Tim Peters19397e52004-08-06 22:02:59 +00002545 #
Edward Lopera5db6002004-08-12 02:41:30 +00002546 # Python has super accurate integer addition
Tim Peters19397e52004-08-06 22:02:59 +00002547 #
2548 2 + 2
2549 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +00002550 ## 5
Tim Peters19397e52004-08-06 22:02:59 +00002551 #
Edward Lopera5db6002004-08-12 02:41:30 +00002552 # And very friendly error messages:
Tim Peters19397e52004-08-06 22:02:59 +00002553 #
2554 1/0
2555 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +00002556 ## To Infinity
2557 ## And
2558 ## Beyond
Tim Peters19397e52004-08-06 22:02:59 +00002559 #
Edward Lopera5db6002004-08-12 02:41:30 +00002560 # You can use logic if you want:
Tim Peters19397e52004-08-06 22:02:59 +00002561 #
2562 if 0:
2563 blah
2564 blah
Tim Peters19397e52004-08-06 22:02:59 +00002565 #
Edward Lopera5db6002004-08-12 02:41:30 +00002566 # Ho hum
Georg Brandlecf93c72005-06-26 23:09:51 +00002567 <BLANKLINE>
Tim Peters19397e52004-08-06 22:02:59 +00002568 """
Edward Loper00f8da72004-08-26 18:05:07 +00002569 output = []
2570 for piece in DocTestParser().parse(s):
2571 if isinstance(piece, Example):
2572 # Add the example's source code (strip trailing NL)
2573 output.append(piece.source[:-1])
2574 # Add the expected output:
2575 want = piece.want
2576 if want:
2577 output.append('# Expected:')
2578 output += ['## '+l for l in want.split('\n')[:-1]]
2579 else:
2580 # Add non-example text.
2581 output += [_comment_line(l)
2582 for l in piece.split('\n')[:-1]]
Tim Peters19397e52004-08-06 22:02:59 +00002583
Edward Loper00f8da72004-08-26 18:05:07 +00002584 # Trim junk on both ends.
2585 while output and output[-1] == '#':
2586 output.pop()
2587 while output and output[0] == '#':
2588 output.pop(0)
2589 # Combine the output, and return it.
Georg Brandl1f149642005-06-26 22:22:31 +00002590 # Add a courtesy newline to prevent exec from choking (see bug #1172785)
2591 return '\n'.join(output) + '\n'
Tim Petersdb3756d2003-06-29 05:30:48 +00002592
2593def testsource(module, name):
Tim Peters19397e52004-08-06 22:02:59 +00002594 """Extract the test sources from a doctest docstring as a script.
Tim Petersdb3756d2003-06-29 05:30:48 +00002595
2596 Provide the module (or dotted name of the module) containing the
Jim Fultona643b652004-07-14 19:06:50 +00002597 test to be debugged and the name (within the module) of the object
2598 with the doc string with tests to be debugged.
Tim Petersdb3756d2003-06-29 05:30:48 +00002599 """
Tim Peters8485b562004-08-04 18:46:34 +00002600 module = _normalize_module(module)
2601 tests = DocTestFinder().find(module)
2602 test = [t for t in tests if t.name == name]
Tim Petersdb3756d2003-06-29 05:30:48 +00002603 if not test:
2604 raise ValueError(name, "not found in tests")
2605 test = test[0]
Tim Peters19397e52004-08-06 22:02:59 +00002606 testsrc = script_from_examples(test.docstring)
Jim Fultona643b652004-07-14 19:06:50 +00002607 return testsrc
Tim Petersdb3756d2003-06-29 05:30:48 +00002608
Jim Fultona643b652004-07-14 19:06:50 +00002609def debug_src(src, pm=False, globs=None):
Tim Peters19397e52004-08-06 22:02:59 +00002610 """Debug a single doctest docstring, in argument `src`'"""
2611 testsrc = script_from_examples(src)
Tim Peters8485b562004-08-04 18:46:34 +00002612 debug_script(testsrc, pm, globs)
Tim Petersdb3756d2003-06-29 05:30:48 +00002613
Jim Fultona643b652004-07-14 19:06:50 +00002614def debug_script(src, pm=False, globs=None):
Tim Peters19397e52004-08-06 22:02:59 +00002615 "Debug a test script. `src` is the script, as a string."
Tim Petersdb3756d2003-06-29 05:30:48 +00002616 import pdb
Tim Petersdb3756d2003-06-29 05:30:48 +00002617
Victor Stinner12b8d142011-06-30 17:35:55 +02002618 if globs:
2619 globs = globs.copy()
2620 else:
2621 globs = {}
Tim Peters8485b562004-08-04 18:46:34 +00002622
Victor Stinner12b8d142011-06-30 17:35:55 +02002623 if pm:
2624 try:
2625 exec(src, globs, globs)
2626 except:
2627 print(sys.exc_info()[1])
2628 p = pdb.Pdb(nosigint=True)
2629 p.reset()
2630 p.interaction(None, sys.exc_info()[2])
2631 else:
2632 pdb.Pdb(nosigint=True).run("exec(%r)" % src, globs, globs)
Tim Petersdb3756d2003-06-29 05:30:48 +00002633
Jim Fultona643b652004-07-14 19:06:50 +00002634def debug(module, name, pm=False):
Tim Peters19397e52004-08-06 22:02:59 +00002635 """Debug a single doctest docstring.
Jim Fultona643b652004-07-14 19:06:50 +00002636
2637 Provide the module (or dotted name of the module) containing the
2638 test to be debugged and the name (within the module) of the object
Tim Peters19397e52004-08-06 22:02:59 +00002639 with the docstring with tests to be debugged.
Jim Fultona643b652004-07-14 19:06:50 +00002640 """
Tim Peters8485b562004-08-04 18:46:34 +00002641 module = _normalize_module(module)
Jim Fultona643b652004-07-14 19:06:50 +00002642 testsrc = testsource(module, name)
2643 debug_script(testsrc, pm, module.__dict__)
2644
Tim Peters8485b562004-08-04 18:46:34 +00002645######################################################################
Georg Brandl31835852008-05-12 17:38:56 +00002646## 9. Example Usage
Tim Peters8485b562004-08-04 18:46:34 +00002647######################################################################
Tim Peters8a7d2d52001-01-16 07:10:57 +00002648class _TestClass:
2649 """
2650 A pointless class, for sanity-checking of docstring testing.
2651
2652 Methods:
2653 square()
2654 get()
2655
2656 >>> _TestClass(13).get() + _TestClass(-12).get()
2657 1
2658 >>> hex(_TestClass(13).square().get())
2659 '0xa9'
2660 """
2661
2662 def __init__(self, val):
2663 """val -> _TestClass object with associated value val.
2664
2665 >>> t = _TestClass(123)
Guido van Rossum7131f842007-02-09 20:13:25 +00002666 >>> print(t.get())
Tim Peters8a7d2d52001-01-16 07:10:57 +00002667 123
2668 """
2669
2670 self.val = val
2671
2672 def square(self):
2673 """square() -> square TestClass's associated value
2674
2675 >>> _TestClass(13).square().get()
2676 169
2677 """
2678
2679 self.val = self.val ** 2
2680 return self
2681
2682 def get(self):
2683 """get() -> return TestClass's associated value.
2684
2685 >>> x = _TestClass(-42)
Guido van Rossum7131f842007-02-09 20:13:25 +00002686 >>> print(x.get())
Tim Peters8a7d2d52001-01-16 07:10:57 +00002687 -42
2688 """
2689
2690 return self.val
2691
2692__test__ = {"_TestClass": _TestClass,
2693 "string": r"""
2694 Example of a string object, searched as-is.
2695 >>> x = 1; y = 2
2696 >>> x + y, x * y
2697 (3, 2)
Tim Peters6ebe61f2003-06-27 20:48:05 +00002698 """,
Tim Peters3fa8c202004-08-23 21:43:39 +00002699
Tim Peters6ebe61f2003-06-27 20:48:05 +00002700 "bool-int equivalence": r"""
2701 In 2.2, boolean expressions displayed
2702 0 or 1. By default, we still accept
2703 them. This can be disabled by passing
2704 DONT_ACCEPT_TRUE_FOR_1 to the new
2705 optionflags argument.
2706 >>> 4 == 4
2707 1
2708 >>> 4 == 4
2709 True
2710 >>> 4 > 4
2711 0
2712 >>> 4 > 4
2713 False
2714 """,
Tim Peters3fa8c202004-08-23 21:43:39 +00002715
Tim Peters8485b562004-08-04 18:46:34 +00002716 "blank lines": r"""
Tim Peters3fa8c202004-08-23 21:43:39 +00002717 Blank lines can be marked with <BLANKLINE>:
Guido van Rossum7131f842007-02-09 20:13:25 +00002718 >>> print('foo\n\nbar\n')
Tim Peters3fa8c202004-08-23 21:43:39 +00002719 foo
2720 <BLANKLINE>
2721 bar
2722 <BLANKLINE>
Tim Peters8485b562004-08-04 18:46:34 +00002723 """,
Tim Peters3fa8c202004-08-23 21:43:39 +00002724
2725 "ellipsis": r"""
2726 If the ellipsis flag is used, then '...' can be used to
2727 elide substrings in the desired output:
Guido van Rossum805365e2007-05-07 22:24:25 +00002728 >>> print(list(range(1000))) #doctest: +ELLIPSIS
Tim Peters3fa8c202004-08-23 21:43:39 +00002729 [0, 1, 2, ..., 999]
2730 """,
2731
2732 "whitespace normalization": r"""
2733 If the whitespace normalization flag is used, then
2734 differences in whitespace are ignored.
Guido van Rossum805365e2007-05-07 22:24:25 +00002735 >>> print(list(range(30))) #doctest: +NORMALIZE_WHITESPACE
Tim Peters3fa8c202004-08-23 21:43:39 +00002736 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
2737 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,
2738 27, 28, 29]
2739 """,
2740 }
Tim Peters8485b562004-08-04 18:46:34 +00002741
R. David Murray445448c2009-12-20 17:28:31 +00002742
Tim Peters8a7d2d52001-01-16 07:10:57 +00002743def _test():
R David Murray5707d502013-06-23 14:24:13 -04002744 parser = argparse.ArgumentParser(description="doctest runner")
2745 parser.add_argument('-v', '--verbose', action='store_true', default=False,
2746 help='print very verbose output for all tests')
2747 parser.add_argument('-o', '--option', action='append',
2748 choices=OPTIONFLAGS_BY_NAME.keys(), default=[],
2749 help=('specify a doctest option flag to apply'
2750 ' to the test run; may be specified more'
2751 ' than once to apply multiple options'))
2752 parser.add_argument('-f', '--fail-fast', action='store_true',
2753 help=('stop running tests after first failure (this'
2754 ' is a shorthand for -o FAIL_FAST, and is'
2755 ' in addition to any other -o options)'))
2756 parser.add_argument('file', nargs='+',
2757 help='file containing the tests to run')
2758 args = parser.parse_args()
2759 testfiles = args.file
2760 # Verbose used to be handled by the "inspect argv" magic in DocTestRunner,
2761 # but since we are using argparse we are passing it manually now.
2762 verbose = args.verbose
2763 options = 0
2764 for option in args.option:
2765 options |= OPTIONFLAGS_BY_NAME[option]
2766 if args.fail_fast:
2767 options |= FAIL_FAST
R. David Murray445448c2009-12-20 17:28:31 +00002768 for filename in testfiles:
2769 if filename.endswith(".py"):
2770 # It is a module -- insert its dir into sys.path and try to
2771 # import it. If it is part of a package, that possibly
2772 # won't work because of package imports.
2773 dirname, filename = os.path.split(filename)
2774 sys.path.insert(0, dirname)
2775 m = __import__(filename[:-3])
2776 del sys.path[0]
R David Murray5707d502013-06-23 14:24:13 -04002777 failures, _ = testmod(m, verbose=verbose, optionflags=options)
R. David Murray445448c2009-12-20 17:28:31 +00002778 else:
R David Murray5707d502013-06-23 14:24:13 -04002779 failures, _ = testfile(filename, module_relative=False,
2780 verbose=verbose, optionflags=options)
R. David Murray445448c2009-12-20 17:28:31 +00002781 if failures:
2782 return 1
Christian Heimes895627f2007-12-08 17:28:33 +00002783 return 0
Tim Peters8a7d2d52001-01-16 07:10:57 +00002784
R. David Murray445448c2009-12-20 17:28:31 +00002785
Tim Peters8a7d2d52001-01-16 07:10:57 +00002786if __name__ == "__main__":
Christian Heimes895627f2007-12-08 17:28:33 +00002787 sys.exit(_test())