blob: f60b06d7c9acfa936d59b2376494687053f641e9 [file] [log] [blame]
Tim Peters4fd9e2f2001-08-18 00:05:50 +00001# Module doctest.
Tim Peters8485b562004-08-04 18:46:34 +00002# Released to the public domain 16-Jan-2001, by Tim Peters (tim@python.org).
Tim Peters19397e52004-08-06 22:02:59 +00003# Major enhancements and refactoring by:
Tim Peters8485b562004-08-04 18:46:34 +00004# Jim Fulton
5# Edward Loper
Tim Peters8a7d2d52001-01-16 07:10:57 +00006
7# Provided as-is; use at your own risk; no warranty; no promises; enjoy!
8
Martin v. Löwis92816de2004-05-31 19:01:00 +00009r"""Module doctest -- a framework for running examples in docstrings.
Tim Peters8a7d2d52001-01-16 07:10:57 +000010
Tim Peters80e53142004-08-09 04:34:45 +000011In simplest use, end each module M to be tested with:
Tim Peters8a7d2d52001-01-16 07:10:57 +000012
13def _test():
Tim Peters80e53142004-08-09 04:34:45 +000014 import doctest
Tim Peters48983fc2004-09-25 02:41:28 +000015 doctest.testmod()
Tim Peters8a7d2d52001-01-16 07:10:57 +000016
17if __name__ == "__main__":
18 _test()
19
20Then running the module as a script will cause the examples in the
21docstrings to get executed and verified:
22
23python M.py
24
25This won't display anything unless an example fails, in which case the
26failing example(s) and the cause(s) of the failure(s) are printed to stdout
27(why not stderr? because stderr is a lame hack <0.2 wink>), and the final
28line of output is "Test failed.".
29
30Run it with the -v switch instead:
31
32python M.py -v
33
34and a detailed report of all examples tried is printed to stdout, along
35with assorted summaries at the end.
36
Tim Peters80e53142004-08-09 04:34:45 +000037You can force verbose mode by passing "verbose=True" to testmod, or prohibit
38it by passing "verbose=False". In either of those cases, sys.argv is not
Tim Peters8a7d2d52001-01-16 07:10:57 +000039examined by testmod.
40
Tim Peters80e53142004-08-09 04:34:45 +000041There are a variety of other ways to run doctests, including integration
42with the unittest framework, and support for running non-Python text
43files containing doctests. There are also many ways to override parts
44of doctest's default behaviors. See the Library Reference Manual for
45details.
Tim Peters8a7d2d52001-01-16 07:10:57 +000046"""
Tim Peters48983fc2004-09-25 02:41:28 +000047
Edward Loper8e4a34b2004-08-12 02:34:27 +000048__docformat__ = 'reStructuredText en'
Tim Peters8a7d2d52001-01-16 07:10:57 +000049
Tim Peters4fd9e2f2001-08-18 00:05:50 +000050__all__ = [
Edward Loperb7503ff2004-08-19 19:19:03 +000051 # 0, Option Flags
52 'register_optionflag',
53 'DONT_ACCEPT_TRUE_FOR_1',
54 'DONT_ACCEPT_BLANKLINE',
55 'NORMALIZE_WHITESPACE',
56 'ELLIPSIS',
Thomas Wouters477c8d52006-05-27 19:21:47 +000057 'SKIP',
Tim Peters1fbf9c52004-09-04 17:21:02 +000058 'IGNORE_EXCEPTION_DETAIL',
Tim Petersba601962004-09-04 15:04:06 +000059 'COMPARISON_FLAGS',
Edward Loper71f55af2004-08-26 01:41:51 +000060 'REPORT_UDIFF',
61 'REPORT_CDIFF',
62 'REPORT_NDIFF',
Jim Fultonf54bad42004-08-28 14:57:56 +000063 'REPORT_ONLY_FIRST_FAILURE',
Tim Petersba601962004-09-04 15:04:06 +000064 'REPORTING_FLAGS',
Edward Loperb7503ff2004-08-19 19:19:03 +000065 # 1. Utility Functions
Edward Loperb7503ff2004-08-19 19:19:03 +000066 # 2. Example & DocTest
Tim Peters8485b562004-08-04 18:46:34 +000067 'Example',
68 'DocTest',
Edward Loperb7503ff2004-08-19 19:19:03 +000069 # 3. Doctest Parser
70 'DocTestParser',
71 # 4. Doctest Finder
Tim Peters8485b562004-08-04 18:46:34 +000072 'DocTestFinder',
Edward Loperb7503ff2004-08-19 19:19:03 +000073 # 5. Doctest Runner
Tim Peters8485b562004-08-04 18:46:34 +000074 'DocTestRunner',
Edward Loperb7503ff2004-08-19 19:19:03 +000075 'OutputChecker',
76 'DocTestFailure',
77 'UnexpectedException',
78 'DebugRunner',
79 # 6. Test Functions
Tim Peters4fd9e2f2001-08-18 00:05:50 +000080 'testmod',
Edward Loper052d0cd2004-09-19 17:19:33 +000081 'testfile',
Tim Peters4fd9e2f2001-08-18 00:05:50 +000082 'run_docstring_examples',
Georg Brandlcc80bfe2008-05-12 18:06:23 +000083 # 7. Unittest Support
Tim Petersdb3756d2003-06-29 05:30:48 +000084 'DocTestSuite',
Edward Loperb7503ff2004-08-19 19:19:03 +000085 'DocFileSuite',
Tim Peters9d02a7c2004-09-26 01:50:24 +000086 'set_unittest_reportflags',
Georg Brandlcc80bfe2008-05-12 18:06:23 +000087 # 8. Debugging Support
Edward Loperb7503ff2004-08-19 19:19:03 +000088 'script_from_examples',
Tim Petersdb3756d2003-06-29 05:30:48 +000089 'testsource',
Edward Loperb7503ff2004-08-19 19:19:03 +000090 'debug_src',
Tim Petersdb3756d2003-06-29 05:30:48 +000091 'debug',
Tim Peters4fd9e2f2001-08-18 00:05:50 +000092]
Tim Peters8a7d2d52001-01-16 07:10:57 +000093
Tim Peters4fd9e2f2001-08-18 00:05:50 +000094import __future__
Victor Stinner12b8d142011-06-30 17:35:55 +020095import difflib
96import inspect
97import linecache
98import os
99import pdb
100import re
101import sys
102import traceback
103import unittest
Guido van Rossum34d19282007-08-09 01:03:29 +0000104from io import StringIO
Christian Heimes25bb7832008-01-11 16:17:00 +0000105from collections import namedtuple
106
107TestResults = namedtuple('TestResults', 'failed attempted')
Tim Peters7402f792001-10-02 03:53:41 +0000108
Tim Peters19397e52004-08-06 22:02:59 +0000109# There are 4 basic classes:
110# - Example: a <source, want> pair, plus an intra-docstring line number.
111# - DocTest: a collection of examples, parsed from a docstring, plus
112# info about where the docstring came from (name, filename, lineno).
113# - DocTestFinder: extracts DocTests from a given object's docstring and
114# its contained objects' docstrings.
115# - DocTestRunner: runs DocTest cases, and accumulates statistics.
116#
117# So the basic picture is:
118#
119# list of:
120# +------+ +---------+ +-------+
121# |object| --DocTestFinder-> | DocTest | --DocTestRunner-> |results|
122# +------+ +---------+ +-------+
123# | Example |
124# | ... |
125# | Example |
126# +---------+
127
Edward Loperac20f572004-08-12 02:02:24 +0000128# Option constants.
Tim Peters38330fe2004-08-30 16:19:24 +0000129
Edward Loperac20f572004-08-12 02:02:24 +0000130OPTIONFLAGS_BY_NAME = {}
131def register_optionflag(name):
Thomas Wouters477c8d52006-05-27 19:21:47 +0000132 # Create a new flag unless `name` is already known.
133 return OPTIONFLAGS_BY_NAME.setdefault(name, 1 << len(OPTIONFLAGS_BY_NAME))
Edward Loperac20f572004-08-12 02:02:24 +0000134
135DONT_ACCEPT_TRUE_FOR_1 = register_optionflag('DONT_ACCEPT_TRUE_FOR_1')
136DONT_ACCEPT_BLANKLINE = register_optionflag('DONT_ACCEPT_BLANKLINE')
137NORMALIZE_WHITESPACE = register_optionflag('NORMALIZE_WHITESPACE')
138ELLIPSIS = register_optionflag('ELLIPSIS')
Thomas Wouters477c8d52006-05-27 19:21:47 +0000139SKIP = register_optionflag('SKIP')
Tim Peters1fbf9c52004-09-04 17:21:02 +0000140IGNORE_EXCEPTION_DETAIL = register_optionflag('IGNORE_EXCEPTION_DETAIL')
Tim Peters38330fe2004-08-30 16:19:24 +0000141
142COMPARISON_FLAGS = (DONT_ACCEPT_TRUE_FOR_1 |
143 DONT_ACCEPT_BLANKLINE |
144 NORMALIZE_WHITESPACE |
Tim Peters1fbf9c52004-09-04 17:21:02 +0000145 ELLIPSIS |
Thomas Wouters477c8d52006-05-27 19:21:47 +0000146 SKIP |
Edward Loper7d88a582004-09-28 05:50:57 +0000147 IGNORE_EXCEPTION_DETAIL)
Tim Peters38330fe2004-08-30 16:19:24 +0000148
Edward Loper71f55af2004-08-26 01:41:51 +0000149REPORT_UDIFF = register_optionflag('REPORT_UDIFF')
150REPORT_CDIFF = register_optionflag('REPORT_CDIFF')
151REPORT_NDIFF = register_optionflag('REPORT_NDIFF')
Edward Lopera89f88d2004-08-26 02:45:51 +0000152REPORT_ONLY_FIRST_FAILURE = register_optionflag('REPORT_ONLY_FIRST_FAILURE')
Edward Loperac20f572004-08-12 02:02:24 +0000153
Tim Peters38330fe2004-08-30 16:19:24 +0000154REPORTING_FLAGS = (REPORT_UDIFF |
155 REPORT_CDIFF |
156 REPORT_NDIFF |
157 REPORT_ONLY_FIRST_FAILURE)
158
Edward Loperac20f572004-08-12 02:02:24 +0000159# Special string markers for use in `want` strings:
160BLANKLINE_MARKER = '<BLANKLINE>'
161ELLIPSIS_MARKER = '...'
162
Tim Peters8485b562004-08-04 18:46:34 +0000163######################################################################
164## Table of Contents
165######################################################################
Edward Loper7c748462004-08-09 02:06:06 +0000166# 1. Utility Functions
167# 2. Example & DocTest -- store test cases
168# 3. DocTest Parser -- extracts examples from strings
169# 4. DocTest Finder -- extracts test cases from objects
170# 5. DocTest Runner -- runs test cases
171# 6. Test Functions -- convenient wrappers for testing
Georg Brandl31835852008-05-12 17:38:56 +0000172# 7. Unittest Support
173# 8. Debugging Support
174# 9. Example Usage
Tim Peters8a7d2d52001-01-16 07:10:57 +0000175
Tim Peters8485b562004-08-04 18:46:34 +0000176######################################################################
177## 1. Utility Functions
178######################################################################
Tim Peters8a7d2d52001-01-16 07:10:57 +0000179
Tim Peters8485b562004-08-04 18:46:34 +0000180def _extract_future_flags(globs):
181 """
182 Return the compiler-flags associated with the future features that
183 have been imported into the given namespace (globs).
184 """
185 flags = 0
186 for fname in __future__.all_feature_names:
187 feature = globs.get(fname, None)
188 if feature is getattr(__future__, fname):
189 flags |= feature.compiler_flag
190 return flags
Tim Peters7402f792001-10-02 03:53:41 +0000191
Tim Peters8485b562004-08-04 18:46:34 +0000192def _normalize_module(module, depth=2):
193 """
194 Return the module specified by `module`. In particular:
195 - If `module` is a module, then return module.
196 - If `module` is a string, then import and return the
197 module with that name.
198 - If `module` is None, then return the calling module.
199 The calling module is assumed to be the module of
200 the stack frame at the given depth in the call stack.
201 """
202 if inspect.ismodule(module):
203 return module
Walter Dörwaldaa97f042007-05-03 21:05:51 +0000204 elif isinstance(module, str):
Tim Peters8485b562004-08-04 18:46:34 +0000205 return __import__(module, globals(), locals(), ["*"])
206 elif module is None:
207 return sys.modules[sys._getframe(depth).f_globals['__name__']]
208 else:
209 raise TypeError("Expected a module, string, or None")
Tim Peters7402f792001-10-02 03:53:41 +0000210
Guido van Rossum1b81e7b2007-08-29 03:53:53 +0000211def _load_testfile(filename, package, module_relative, encoding):
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000212 if module_relative:
213 package = _normalize_module(package, 3)
214 filename = _module_relative_path(package, filename)
215 if hasattr(package, '__loader__'):
216 if hasattr(package.__loader__, 'get_data'):
Guido van Rossumcd4d4522007-11-22 00:30:02 +0000217 file_contents = package.__loader__.get_data(filename)
218 file_contents = file_contents.decode(encoding)
219 # get_data() opens files as 'rb', so one must do the equivalent
220 # conversion as universal newlines would do.
221 return file_contents.replace(os.linesep, '\n'), filename
Antoine Pitrou92f60ed2010-10-14 22:11:44 +0000222 with open(filename, encoding=encoding) as f:
223 return f.read(), filename
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000224
Edward Loperaacf0832004-08-26 01:19:50 +0000225def _indent(s, indent=4):
Tim Peters8485b562004-08-04 18:46:34 +0000226 """
Florent Xicluna59250852010-02-27 14:21:57 +0000227 Add the given number of space characters to the beginning of
228 every non-blank line in `s`, and return the result.
Tim Peters8485b562004-08-04 18:46:34 +0000229 """
Edward Loperaacf0832004-08-26 01:19:50 +0000230 # This regexp matches the start of non-blank lines:
231 return re.sub('(?m)^(?!$)', indent*' ', s)
Tim Peters8a7d2d52001-01-16 07:10:57 +0000232
Edward Loper8e4a34b2004-08-12 02:34:27 +0000233def _exception_traceback(exc_info):
234 """
235 Return a string containing a traceback message for the given
236 exc_info tuple (as returned by sys.exc_info()).
237 """
238 # Get a traceback message.
239 excout = StringIO()
240 exc_type, exc_val, exc_tb = exc_info
241 traceback.print_exception(exc_type, exc_val, exc_tb, file=excout)
242 return excout.getvalue()
243
Tim Peters8485b562004-08-04 18:46:34 +0000244# Override some StringIO methods.
245class _SpoofOut(StringIO):
246 def getvalue(self):
247 result = StringIO.getvalue(self)
248 # If anything at all was written, make sure there's a trailing
249 # newline. There's no way for the expected output to indicate
250 # that a trailing newline is missing.
251 if result and not result.endswith("\n"):
252 result += "\n"
Tim Peters8485b562004-08-04 18:46:34 +0000253 return result
Tim Peters8a7d2d52001-01-16 07:10:57 +0000254
Guido van Rossum79139b22007-02-09 23:20:19 +0000255 def truncate(self, size=None):
Antoine Pitroub3d77002010-01-31 23:12:29 +0000256 self.seek(size)
257 StringIO.truncate(self)
Tim Peters8a7d2d52001-01-16 07:10:57 +0000258
Tim Peters26b3ebb2004-08-19 08:10:08 +0000259# Worst-case linear-time ellipsis matching.
Tim Petersb0a04e12004-08-20 02:08:04 +0000260def _ellipsis_match(want, got):
Tim Petersdc5de3b2004-08-19 14:06:20 +0000261 """
262 Essentially the only subtle case:
Tim Petersb0a04e12004-08-20 02:08:04 +0000263 >>> _ellipsis_match('aa...aa', 'aaa')
Tim Petersdc5de3b2004-08-19 14:06:20 +0000264 False
265 """
Tim Peters26b3ebb2004-08-19 08:10:08 +0000266 if ELLIPSIS_MARKER not in want:
267 return want == got
Tim Petersdc5de3b2004-08-19 14:06:20 +0000268
Tim Peters26b3ebb2004-08-19 08:10:08 +0000269 # Find "the real" strings.
270 ws = want.split(ELLIPSIS_MARKER)
271 assert len(ws) >= 2
Tim Peters26b3ebb2004-08-19 08:10:08 +0000272
Tim Petersdc5de3b2004-08-19 14:06:20 +0000273 # Deal with exact matches possibly needed at one or both ends.
274 startpos, endpos = 0, len(got)
275 w = ws[0]
276 if w: # starts with exact match
277 if got.startswith(w):
278 startpos = len(w)
279 del ws[0]
280 else:
281 return False
282 w = ws[-1]
283 if w: # ends with exact match
284 if got.endswith(w):
285 endpos -= len(w)
286 del ws[-1]
287 else:
288 return False
289
290 if startpos > endpos:
291 # Exact end matches required more characters than we have, as in
Tim Petersb0a04e12004-08-20 02:08:04 +0000292 # _ellipsis_match('aa...aa', 'aaa')
Tim Petersdc5de3b2004-08-19 14:06:20 +0000293 return False
294
295 # For the rest, we only need to find the leftmost non-overlapping
296 # match for each piece. If there's no overall match that way alone,
297 # there's no overall match period.
Tim Peters26b3ebb2004-08-19 08:10:08 +0000298 for w in ws:
299 # w may be '' at times, if there are consecutive ellipses, or
300 # due to an ellipsis at the start or end of `want`. That's OK.
Tim Petersdc5de3b2004-08-19 14:06:20 +0000301 # Search for an empty string succeeds, and doesn't change startpos.
302 startpos = got.find(w, startpos, endpos)
303 if startpos < 0:
Tim Peters26b3ebb2004-08-19 08:10:08 +0000304 return False
Tim Petersdc5de3b2004-08-19 14:06:20 +0000305 startpos += len(w)
Tim Peters26b3ebb2004-08-19 08:10:08 +0000306
Tim Petersdc5de3b2004-08-19 14:06:20 +0000307 return True
Tim Peters26b3ebb2004-08-19 08:10:08 +0000308
Edward Loper00f8da72004-08-26 18:05:07 +0000309def _comment_line(line):
310 "Return a commented form of the given line"
311 line = line.rstrip()
312 if line:
313 return '# '+line
314 else:
315 return '#'
316
Edward Loper2de91ba2004-08-27 02:07:46 +0000317class _OutputRedirectingPdb(pdb.Pdb):
318 """
319 A specialized version of the python debugger that redirects stdout
320 to a given stream when interacting with the user. Stdout is *not*
321 redirected when traced code is executed.
322 """
323 def __init__(self, out):
324 self.__out = out
Guido van Rossum0d3fb8a2007-11-26 23:23:18 +0000325 self.__debugger_used = False
Georg Brandl34748cd2010-12-04 17:11:36 +0000326 # do not play signal games in the pdb
327 pdb.Pdb.__init__(self, stdout=out, nosigint=True)
Georg Brandld72e0432010-07-30 09:59:28 +0000328 # still use input() to get user input
329 self.use_rawinput = 1
Edward Loper2de91ba2004-08-27 02:07:46 +0000330
Guido van Rossum0d3fb8a2007-11-26 23:23:18 +0000331 def set_trace(self, frame=None):
332 self.__debugger_used = True
333 if frame is None:
334 frame = sys._getframe().f_back
335 pdb.Pdb.set_trace(self, frame)
336
337 def set_continue(self):
338 # Calling set_continue unconditionally would break unit test
339 # coverage reporting, as Bdb.set_continue calls sys.settrace(None).
340 if self.__debugger_used:
341 pdb.Pdb.set_continue(self)
342
Edward Loper2de91ba2004-08-27 02:07:46 +0000343 def trace_dispatch(self, *args):
344 # Redirect stdout to the given stream.
345 save_stdout = sys.stdout
346 sys.stdout = self.__out
347 # Call Pdb's trace dispatch method.
Tim Petersd7bbbbc2004-11-08 22:30:28 +0000348 try:
349 return pdb.Pdb.trace_dispatch(self, *args)
350 finally:
Tim Petersd7bbbbc2004-11-08 22:30:28 +0000351 sys.stdout = save_stdout
Edward Loper2de91ba2004-08-27 02:07:46 +0000352
Edward Lopera2fc7ec2004-09-21 03:24:24 +0000353# [XX] Normalize with respect to os.path.pardir?
Edward Loper052d0cd2004-09-19 17:19:33 +0000354def _module_relative_path(module, path):
355 if not inspect.ismodule(module):
Collin Winterce36ad82007-08-30 01:19:48 +0000356 raise TypeError('Expected a module: %r' % module)
Edward Loper052d0cd2004-09-19 17:19:33 +0000357 if path.startswith('/'):
Collin Winterce36ad82007-08-30 01:19:48 +0000358 raise ValueError('Module-relative files may not have absolute paths')
Edward Loper052d0cd2004-09-19 17:19:33 +0000359
360 # Find the base directory for the path.
361 if hasattr(module, '__file__'):
362 # A normal module/package
363 basedir = os.path.split(module.__file__)[0]
364 elif module.__name__ == '__main__':
365 # An interactive session.
366 if len(sys.argv)>0 and sys.argv[0] != '':
367 basedir = os.path.split(sys.argv[0])[0]
368 else:
369 basedir = os.curdir
370 else:
371 # A module w/o __file__ (this includes builtins)
372 raise ValueError("Can't resolve paths relative to the module " +
373 module + " (it has no __file__)")
374
375 # Combine the base directory and the path.
376 return os.path.join(basedir, *(path.split('/')))
377
Tim Peters8485b562004-08-04 18:46:34 +0000378######################################################################
379## 2. Example & DocTest
380######################################################################
381## - An "example" is a <source, want> pair, where "source" is a
382## fragment of source code, and "want" is the expected output for
383## "source." The Example class also includes information about
384## where the example was extracted from.
385##
Edward Lopera1ef6112004-08-09 16:14:41 +0000386## - A "doctest" is a collection of examples, typically extracted from
387## a string (such as an object's docstring). The DocTest class also
388## includes information about where the string was extracted from.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000389
Tim Peters8485b562004-08-04 18:46:34 +0000390class Example:
391 """
392 A single doctest example, consisting of source code and expected
Edward Lopera1ef6112004-08-09 16:14:41 +0000393 output. `Example` defines the following attributes:
Tim Peters8a7d2d52001-01-16 07:10:57 +0000394
Edward Loper74bca7a2004-08-12 02:27:44 +0000395 - source: A single Python statement, always ending with a newline.
Tim Petersbb431472004-08-09 03:51:46 +0000396 The constructor adds a newline if needed.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000397
Edward Loper74bca7a2004-08-12 02:27:44 +0000398 - want: The expected output from running the source code (either
Tim Petersbb431472004-08-09 03:51:46 +0000399 from stdout, or a traceback in case of exception). `want` ends
400 with a newline unless it's empty, in which case it's an empty
401 string. The constructor adds a newline if needed.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000402
Edward Lopera6b68322004-08-26 00:05:43 +0000403 - exc_msg: The exception message generated by the example, if
404 the example is expected to generate an exception; or `None` if
405 it is not expected to generate an exception. This exception
406 message is compared against the return value of
407 `traceback.format_exception_only()`. `exc_msg` ends with a
408 newline unless it's `None`. The constructor adds a newline
409 if needed.
410
Edward Loper74bca7a2004-08-12 02:27:44 +0000411 - lineno: The line number within the DocTest string containing
Tim Peters8485b562004-08-04 18:46:34 +0000412 this Example where the Example begins. This line number is
413 zero-based, with respect to the beginning of the DocTest.
Edward Loper74bca7a2004-08-12 02:27:44 +0000414
415 - indent: The example's indentation in the DocTest string.
416 I.e., the number of space characters that preceed the
417 example's first prompt.
418
419 - options: A dictionary mapping from option flags to True or
420 False, which is used to override default options for this
421 example. Any option flags not contained in this dictionary
422 are left at their default value (as specified by the
423 DocTestRunner's optionflags). By default, no options are set.
Tim Peters8485b562004-08-04 18:46:34 +0000424 """
Edward Lopera6b68322004-08-26 00:05:43 +0000425 def __init__(self, source, want, exc_msg=None, lineno=0, indent=0,
426 options=None):
Tim Petersbb431472004-08-09 03:51:46 +0000427 # Normalize inputs.
428 if not source.endswith('\n'):
429 source += '\n'
430 if want and not want.endswith('\n'):
431 want += '\n'
Edward Lopera6b68322004-08-26 00:05:43 +0000432 if exc_msg is not None and not exc_msg.endswith('\n'):
433 exc_msg += '\n'
Tim Peters8485b562004-08-04 18:46:34 +0000434 # Store properties.
435 self.source = source
436 self.want = want
437 self.lineno = lineno
Edward Loper74bca7a2004-08-12 02:27:44 +0000438 self.indent = indent
439 if options is None: options = {}
440 self.options = options
Edward Lopera6b68322004-08-26 00:05:43 +0000441 self.exc_msg = exc_msg
Tim Peters8a7d2d52001-01-16 07:10:57 +0000442
Tim Peters8485b562004-08-04 18:46:34 +0000443class DocTest:
444 """
445 A collection of doctest examples that should be run in a single
Edward Lopera1ef6112004-08-09 16:14:41 +0000446 namespace. Each `DocTest` defines the following attributes:
Tim Peters8a7d2d52001-01-16 07:10:57 +0000447
Tim Peters8485b562004-08-04 18:46:34 +0000448 - examples: the list of examples.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000449
Tim Peters8485b562004-08-04 18:46:34 +0000450 - globs: The namespace (aka globals) that the examples should
451 be run in.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000452
Tim Peters8485b562004-08-04 18:46:34 +0000453 - name: A name identifying the DocTest (typically, the name of
454 the object whose docstring this DocTest was extracted from).
Tim Peters8a7d2d52001-01-16 07:10:57 +0000455
Tim Peters8485b562004-08-04 18:46:34 +0000456 - filename: The name of the file that this DocTest was extracted
Edward Lopera1ef6112004-08-09 16:14:41 +0000457 from, or `None` if the filename is unknown.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000458
Tim Peters8485b562004-08-04 18:46:34 +0000459 - lineno: The line number within filename where this DocTest
Edward Lopera1ef6112004-08-09 16:14:41 +0000460 begins, or `None` if the line number is unavailable. This
461 line number is zero-based, with respect to the beginning of
462 the file.
463
464 - docstring: The string that the examples were extracted from,
465 or `None` if the string is unavailable.
Tim Peters8485b562004-08-04 18:46:34 +0000466 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000467 def __init__(self, examples, globs, name, filename, lineno, docstring):
Tim Peters8485b562004-08-04 18:46:34 +0000468 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000469 Create a new DocTest containing the given examples. The
470 DocTest's globals are initialized with a copy of `globs`.
Tim Peters8485b562004-08-04 18:46:34 +0000471 """
Guido van Rossum3172c5d2007-10-16 18:12:55 +0000472 assert not isinstance(examples, str), \
Edward Lopera1ef6112004-08-09 16:14:41 +0000473 "DocTest no longer accepts str; use DocTestParser instead"
474 self.examples = examples
475 self.docstring = docstring
Tim Peters8485b562004-08-04 18:46:34 +0000476 self.globs = globs.copy()
Tim Peters8485b562004-08-04 18:46:34 +0000477 self.name = name
478 self.filename = filename
479 self.lineno = lineno
Tim Peters8485b562004-08-04 18:46:34 +0000480
481 def __repr__(self):
482 if len(self.examples) == 0:
483 examples = 'no examples'
484 elif len(self.examples) == 1:
485 examples = '1 example'
486 else:
487 examples = '%d examples' % len(self.examples)
488 return ('<DocTest %s from %s:%s (%s)>' %
489 (self.name, self.filename, self.lineno, examples))
490
491
492 # This lets us sort tests by name:
Guido van Rossum47b9ff62006-08-24 00:41:19 +0000493 def __lt__(self, other):
Tim Peters8485b562004-08-04 18:46:34 +0000494 if not isinstance(other, DocTest):
Guido van Rossum47b9ff62006-08-24 00:41:19 +0000495 return NotImplemented
496 return ((self.name, self.filename, self.lineno, id(self))
497 <
498 (other.name, other.filename, other.lineno, id(other)))
Tim Peters8485b562004-08-04 18:46:34 +0000499
500######################################################################
Edward Loperb7503ff2004-08-19 19:19:03 +0000501## 3. DocTestParser
Edward Loper7c748462004-08-09 02:06:06 +0000502######################################################################
503
Edward Lopera1ef6112004-08-09 16:14:41 +0000504class DocTestParser:
Edward Loper7c748462004-08-09 02:06:06 +0000505 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000506 A class used to parse strings containing doctest examples.
Edward Loper7c748462004-08-09 02:06:06 +0000507 """
Edward Loper8e4a34b2004-08-12 02:34:27 +0000508 # This regular expression is used to find doctest examples in a
509 # string. It defines three groups: `source` is the source code
510 # (including leading indentation and prompts); `indent` is the
511 # indentation of the first (PS1) line of the source code; and
512 # `want` is the expected output (including leading indentation).
Edward Loper7c748462004-08-09 02:06:06 +0000513 _EXAMPLE_RE = re.compile(r'''
Tim Petersd40a92b2004-08-09 03:28:45 +0000514 # Source consists of a PS1 line followed by zero or more PS2 lines.
515 (?P<source>
516 (?:^(?P<indent> [ ]*) >>> .*) # PS1 line
517 (?:\n [ ]* \.\.\. .*)*) # PS2 lines
518 \n?
519 # Want consists of any non-blank lines that do not start with PS1.
520 (?P<want> (?:(?![ ]*$) # Not a blank line
521 (?![ ]*>>>) # Not a line starting with PS1
522 .*$\n? # But any other line
523 )*)
524 ''', re.MULTILINE | re.VERBOSE)
Edward Loper8e4a34b2004-08-12 02:34:27 +0000525
Edward Lopera6b68322004-08-26 00:05:43 +0000526 # A regular expression for handling `want` strings that contain
527 # expected exceptions. It divides `want` into three pieces:
528 # - the traceback header line (`hdr`)
529 # - the traceback stack (`stack`)
530 # - the exception message (`msg`), as generated by
531 # traceback.format_exception_only()
532 # `msg` may have multiple lines. We assume/require that the
533 # exception message is the first non-indented line starting with a word
534 # character following the traceback header line.
535 _EXCEPTION_RE = re.compile(r"""
536 # Grab the traceback header. Different versions of Python have
537 # said different things on the first traceback line.
538 ^(?P<hdr> Traceback\ \(
539 (?: most\ recent\ call\ last
540 | innermost\ last
541 ) \) :
542 )
543 \s* $ # toss trailing whitespace on the header.
544 (?P<stack> .*?) # don't blink: absorb stuff until...
545 ^ (?P<msg> \w+ .*) # a line *starts* with alphanum.
546 """, re.VERBOSE | re.MULTILINE | re.DOTALL)
547
Tim Peters7ea48dd2004-08-13 01:52:59 +0000548 # A callable returning a true value iff its argument is a blank line
549 # or contains a single comment.
Edward Loper8e4a34b2004-08-12 02:34:27 +0000550 _IS_BLANK_OR_COMMENT = re.compile(r'^[ ]*(#.*)?$').match
Edward Loper7c748462004-08-09 02:06:06 +0000551
Edward Loper00f8da72004-08-26 18:05:07 +0000552 def parse(self, string, name='<string>'):
553 """
554 Divide the given string into examples and intervening text,
555 and return them as a list of alternating Examples and strings.
556 Line numbers for the Examples are 0-based. The optional
557 argument `name` is a name identifying this string, and is only
558 used for error messages.
559 """
560 string = string.expandtabs()
561 # If all lines begin with the same indentation, then strip it.
562 min_indent = self._min_indent(string)
563 if min_indent > 0:
564 string = '\n'.join([l[min_indent:] for l in string.split('\n')])
565
566 output = []
567 charno, lineno = 0, 0
568 # Find all doctest examples in the string:
Edward Loper2de91ba2004-08-27 02:07:46 +0000569 for m in self._EXAMPLE_RE.finditer(string):
Edward Loper00f8da72004-08-26 18:05:07 +0000570 # Add the pre-example text to `output`.
571 output.append(string[charno:m.start()])
572 # Update lineno (lines before this example)
573 lineno += string.count('\n', charno, m.start())
574 # Extract info from the regexp match.
575 (source, options, want, exc_msg) = \
576 self._parse_example(m, name, lineno)
577 # Create an Example, and add it to the list.
578 if not self._IS_BLANK_OR_COMMENT(source):
579 output.append( Example(source, want, exc_msg,
580 lineno=lineno,
581 indent=min_indent+len(m.group('indent')),
582 options=options) )
583 # Update lineno (lines inside this example)
584 lineno += string.count('\n', m.start(), m.end())
585 # Update charno.
586 charno = m.end()
587 # Add any remaining post-example text to `output`.
588 output.append(string[charno:])
589 return output
590
Edward Lopera1ef6112004-08-09 16:14:41 +0000591 def get_doctest(self, string, globs, name, filename, lineno):
Edward Loper7c748462004-08-09 02:06:06 +0000592 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000593 Extract all doctest examples from the given string, and
594 collect them into a `DocTest` object.
595
596 `globs`, `name`, `filename`, and `lineno` are attributes for
597 the new `DocTest` object. See the documentation for `DocTest`
598 for more information.
599 """
600 return DocTest(self.get_examples(string, name), globs,
601 name, filename, lineno, string)
602
603 def get_examples(self, string, name='<string>'):
604 """
605 Extract all doctest examples from the given string, and return
606 them as a list of `Example` objects. Line numbers are
607 0-based, because it's most common in doctests that nothing
608 interesting appears on the same line as opening triple-quote,
609 and so the first interesting line is called \"line 1\" then.
610
611 The optional argument `name` is a name identifying this
612 string, and is only used for error messages.
Edward Loper7c748462004-08-09 02:06:06 +0000613 """
Edward Loper00f8da72004-08-26 18:05:07 +0000614 return [x for x in self.parse(string, name)
615 if isinstance(x, Example)]
Edward Loper7c748462004-08-09 02:06:06 +0000616
Edward Loper74bca7a2004-08-12 02:27:44 +0000617 def _parse_example(self, m, name, lineno):
618 """
619 Given a regular expression match from `_EXAMPLE_RE` (`m`),
620 return a pair `(source, want)`, where `source` is the matched
621 example's source code (with prompts and indentation stripped);
622 and `want` is the example's expected output (with indentation
623 stripped).
624
625 `name` is the string's name, and `lineno` is the line number
626 where the example starts; both are used for error messages.
627 """
Edward Loper7c748462004-08-09 02:06:06 +0000628 # Get the example's indentation level.
629 indent = len(m.group('indent'))
630
631 # Divide source into lines; check that they're properly
632 # indented; and then strip their indentation & prompts.
633 source_lines = m.group('source').split('\n')
Edward Lopera1ef6112004-08-09 16:14:41 +0000634 self._check_prompt_blank(source_lines, indent, name, lineno)
Tim Petersc5049152004-08-22 17:34:58 +0000635 self._check_prefix(source_lines[1:], ' '*indent + '.', name, lineno)
Edward Loper7c748462004-08-09 02:06:06 +0000636 source = '\n'.join([sl[indent+4:] for sl in source_lines])
Edward Loper7c748462004-08-09 02:06:06 +0000637
Tim Petersc5049152004-08-22 17:34:58 +0000638 # Divide want into lines; check that it's properly indented; and
639 # then strip the indentation. Spaces before the last newline should
640 # be preserved, so plain rstrip() isn't good enough.
Jim Fulton07a349c2004-08-22 14:10:00 +0000641 want = m.group('want')
Jim Fulton07a349c2004-08-22 14:10:00 +0000642 want_lines = want.split('\n')
Tim Petersc5049152004-08-22 17:34:58 +0000643 if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]):
644 del want_lines[-1] # forget final newline & spaces after it
Edward Lopera1ef6112004-08-09 16:14:41 +0000645 self._check_prefix(want_lines, ' '*indent, name,
Tim Petersc5049152004-08-22 17:34:58 +0000646 lineno + len(source_lines))
Edward Loper7c748462004-08-09 02:06:06 +0000647 want = '\n'.join([wl[indent:] for wl in want_lines])
Edward Loper7c748462004-08-09 02:06:06 +0000648
Edward Lopera6b68322004-08-26 00:05:43 +0000649 # If `want` contains a traceback message, then extract it.
650 m = self._EXCEPTION_RE.match(want)
651 if m:
652 exc_msg = m.group('msg')
653 else:
654 exc_msg = None
655
Edward Loper00f8da72004-08-26 18:05:07 +0000656 # Extract options from the source.
657 options = self._find_options(source, name, lineno)
658
659 return source, options, want, exc_msg
Edward Loper7c748462004-08-09 02:06:06 +0000660
Edward Loper74bca7a2004-08-12 02:27:44 +0000661 # This regular expression looks for option directives in the
662 # source code of an example. Option directives are comments
663 # starting with "doctest:". Warning: this may give false
664 # positives for string-literals that contain the string
665 # "#doctest:". Eliminating these false positives would require
666 # actually parsing the string; but we limit them by ignoring any
667 # line containing "#doctest:" that is *followed* by a quote mark.
668 _OPTION_DIRECTIVE_RE = re.compile(r'#\s*doctest:\s*([^\n\'"]*)$',
669 re.MULTILINE)
670
671 def _find_options(self, source, name, lineno):
672 """
673 Return a dictionary containing option overrides extracted from
674 option directives in the given source string.
675
676 `name` is the string's name, and `lineno` is the line number
677 where the example starts; both are used for error messages.
678 """
679 options = {}
680 # (note: with the current regexp, this will match at most once:)
681 for m in self._OPTION_DIRECTIVE_RE.finditer(source):
682 option_strings = m.group(1).replace(',', ' ').split()
683 for option in option_strings:
684 if (option[0] not in '+-' or
685 option[1:] not in OPTIONFLAGS_BY_NAME):
686 raise ValueError('line %r of the doctest for %s '
687 'has an invalid option: %r' %
688 (lineno+1, name, option))
689 flag = OPTIONFLAGS_BY_NAME[option[1:]]
690 options[flag] = (option[0] == '+')
691 if options and self._IS_BLANK_OR_COMMENT(source):
692 raise ValueError('line %r of the doctest for %s has an option '
693 'directive on a line with no example: %r' %
694 (lineno, name, source))
695 return options
696
Edward Lopera5db6002004-08-12 02:41:30 +0000697 # This regular expression finds the indentation of every non-blank
698 # line in a string.
Edward Loper00f8da72004-08-26 18:05:07 +0000699 _INDENT_RE = re.compile('^([ ]*)(?=\S)', re.MULTILINE)
Edward Lopera5db6002004-08-12 02:41:30 +0000700
701 def _min_indent(self, s):
702 "Return the minimum indentation of any non-blank line in `s`"
Edward Loper00f8da72004-08-26 18:05:07 +0000703 indents = [len(indent) for indent in self._INDENT_RE.findall(s)]
704 if len(indents) > 0:
705 return min(indents)
Tim Petersdd0e4752004-08-09 03:31:56 +0000706 else:
Edward Loper00f8da72004-08-26 18:05:07 +0000707 return 0
Edward Loper7c748462004-08-09 02:06:06 +0000708
Edward Lopera1ef6112004-08-09 16:14:41 +0000709 def _check_prompt_blank(self, lines, indent, name, lineno):
Edward Loper74bca7a2004-08-12 02:27:44 +0000710 """
711 Given the lines of a source string (including prompts and
712 leading indentation), check to make sure that every prompt is
713 followed by a space character. If any line is not followed by
714 a space character, then raise ValueError.
715 """
Edward Loper7c748462004-08-09 02:06:06 +0000716 for i, line in enumerate(lines):
717 if len(line) >= indent+4 and line[indent+3] != ' ':
718 raise ValueError('line %r of the docstring for %s '
719 'lacks blank after %s: %r' %
Edward Lopera1ef6112004-08-09 16:14:41 +0000720 (lineno+i+1, name,
Edward Loper7c748462004-08-09 02:06:06 +0000721 line[indent:indent+3], line))
722
Edward Lopera1ef6112004-08-09 16:14:41 +0000723 def _check_prefix(self, lines, prefix, name, lineno):
Edward Loper74bca7a2004-08-12 02:27:44 +0000724 """
725 Check that every line in the given list starts with the given
726 prefix; if any line does not, then raise a ValueError.
727 """
Edward Loper7c748462004-08-09 02:06:06 +0000728 for i, line in enumerate(lines):
729 if line and not line.startswith(prefix):
730 raise ValueError('line %r of the docstring for %s has '
731 'inconsistent leading whitespace: %r' %
Edward Lopera1ef6112004-08-09 16:14:41 +0000732 (lineno+i+1, name, line))
Edward Loper7c748462004-08-09 02:06:06 +0000733
734
735######################################################################
736## 4. DocTest Finder
Tim Peters8485b562004-08-04 18:46:34 +0000737######################################################################
738
739class DocTestFinder:
740 """
741 A class used to extract the DocTests that are relevant to a given
742 object, from its docstring and the docstrings of its contained
743 objects. Doctests can currently be extracted from the following
744 object types: modules, functions, classes, methods, staticmethods,
745 classmethods, and properties.
Tim Peters8485b562004-08-04 18:46:34 +0000746 """
747
Edward Lopera1ef6112004-08-09 16:14:41 +0000748 def __init__(self, verbose=False, parser=DocTestParser(),
Thomas Wouters73e5a5b2006-06-08 15:35:45 +0000749 recurse=True, exclude_empty=True):
Tim Peters8485b562004-08-04 18:46:34 +0000750 """
751 Create a new doctest finder.
752
Edward Lopera1ef6112004-08-09 16:14:41 +0000753 The optional argument `parser` specifies a class or
Tim Peters19397e52004-08-06 22:02:59 +0000754 function that should be used to create new DocTest objects (or
Tim Peters161c9632004-08-08 03:38:33 +0000755 objects that implement the same interface as DocTest). The
Tim Peters19397e52004-08-06 22:02:59 +0000756 signature for this factory function should match the signature
757 of the DocTest constructor.
758
Tim Peters8485b562004-08-04 18:46:34 +0000759 If the optional argument `recurse` is false, then `find` will
760 only examine the given object, and not any contained objects.
Edward Loper32ddbf72004-09-13 05:47:24 +0000761
Tim Peters958cc892004-09-13 14:53:28 +0000762 If the optional argument `exclude_empty` is false, then `find`
763 will include tests for objects with empty docstrings.
Tim Peters8485b562004-08-04 18:46:34 +0000764 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000765 self._parser = parser
Tim Peters8485b562004-08-04 18:46:34 +0000766 self._verbose = verbose
Tim Peters8485b562004-08-04 18:46:34 +0000767 self._recurse = recurse
Edward Loper32ddbf72004-09-13 05:47:24 +0000768 self._exclude_empty = exclude_empty
Tim Peters8485b562004-08-04 18:46:34 +0000769
Thomas Wouters73e5a5b2006-06-08 15:35:45 +0000770 def find(self, obj, name=None, module=None, globs=None, extraglobs=None):
Tim Peters8485b562004-08-04 18:46:34 +0000771 """
772 Return a list of the DocTests that are defined by the given
773 object's docstring, or by any of its contained objects'
774 docstrings.
775
776 The optional parameter `module` is the module that contains
Tim Petersf3f57472004-08-08 06:11:48 +0000777 the given object. If the module is not specified or is None, then
778 the test finder will attempt to automatically determine the
Tim Peters8485b562004-08-04 18:46:34 +0000779 correct module. The object's module is used:
780
781 - As a default namespace, if `globs` is not specified.
782 - To prevent the DocTestFinder from extracting DocTests
Tim Petersf3f57472004-08-08 06:11:48 +0000783 from objects that are imported from other modules.
Tim Peters8485b562004-08-04 18:46:34 +0000784 - To find the name of the file containing the object.
785 - To help find the line number of the object within its
786 file.
787
Tim Petersf3f57472004-08-08 06:11:48 +0000788 Contained objects whose module does not match `module` are ignored.
789
790 If `module` is False, no attempt to find the module will be made.
791 This is obscure, of use mostly in tests: if `module` is False, or
792 is None but cannot be found automatically, then all objects are
793 considered to belong to the (non-existent) module, so all contained
794 objects will (recursively) be searched for doctests.
795
Tim Peters8485b562004-08-04 18:46:34 +0000796 The globals for each DocTest is formed by combining `globs`
797 and `extraglobs` (bindings in `extraglobs` override bindings
798 in `globs`). A new copy of the globals dictionary is created
799 for each DocTest. If `globs` is not specified, then it
800 defaults to the module's `__dict__`, if specified, or {}
801 otherwise. If `extraglobs` is not specified, then it defaults
802 to {}.
803
Tim Peters8485b562004-08-04 18:46:34 +0000804 """
805 # If name was not specified, then extract it from the object.
806 if name is None:
807 name = getattr(obj, '__name__', None)
808 if name is None:
809 raise ValueError("DocTestFinder.find: name must be given "
810 "when obj.__name__ doesn't exist: %r" %
811 (type(obj),))
812
813 # Find the module that contains the given object (if obj is
814 # a module, then module=obj.). Note: this may fail, in which
815 # case module will be None.
Tim Petersf3f57472004-08-08 06:11:48 +0000816 if module is False:
817 module = None
818 elif module is None:
Tim Peters8485b562004-08-04 18:46:34 +0000819 module = inspect.getmodule(obj)
820
821 # Read the module's source code. This is used by
822 # DocTestFinder._find_lineno to find the line number for a
823 # given object's docstring.
824 try:
R. David Murray58641de2009-06-12 15:33:19 +0000825 file = inspect.getsourcefile(obj)
Tim Peters8485b562004-08-04 18:46:34 +0000826 except TypeError:
827 source_lines = None
R. David Murray58641de2009-06-12 15:33:19 +0000828 else:
829 if not file:
830 # Check to see if it's one of our special internal "files"
831 # (see __patched_linecache_getlines).
832 file = inspect.getfile(obj)
833 if not file[0]+file[-2:] == '<]>': file = None
R. David Murray765b9762009-07-15 14:16:54 +0000834 if file is None:
835 source_lines = None
R. David Murray58641de2009-06-12 15:33:19 +0000836 else:
837 if module is not None:
838 # Supply the module globals in case the module was
839 # originally loaded via a PEP 302 loader and
840 # file is not a valid filesystem path
841 source_lines = linecache.getlines(file, module.__dict__)
842 else:
843 # No access to a loader, so assume it's a normal
844 # filesystem path
845 source_lines = linecache.getlines(file)
846 if not source_lines:
847 source_lines = None
Tim Peters8485b562004-08-04 18:46:34 +0000848
849 # Initialize globals, and merge in extraglobs.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000850 if globs is None:
Tim Peters8485b562004-08-04 18:46:34 +0000851 if module is None:
852 globs = {}
853 else:
854 globs = module.__dict__.copy()
855 else:
856 globs = globs.copy()
857 if extraglobs is not None:
858 globs.update(extraglobs)
Raymond Hettinger0f055172009-01-27 10:06:09 +0000859 if '__name__' not in globs:
860 globs['__name__'] = '__main__' # provide a default module name
Tim Peters8a7d2d52001-01-16 07:10:57 +0000861
Tim Peters8485b562004-08-04 18:46:34 +0000862 # Recursively expore `obj`, extracting DocTests.
863 tests = []
Tim Petersf3f57472004-08-08 06:11:48 +0000864 self._find(tests, obj, name, module, source_lines, globs, {})
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000865 # Sort the tests by alpha order of names, for consistency in
866 # verbose-mode output. This was a feature of doctest in Pythons
867 # <= 2.3 that got lost by accident in 2.4. It was repaired in
868 # 2.4.4 and 2.5.
869 tests.sort()
Tim Peters8485b562004-08-04 18:46:34 +0000870 return tests
871
Tim Peters8485b562004-08-04 18:46:34 +0000872 def _from_module(self, module, object):
873 """
874 Return true if the given object is defined in the given
875 module.
876 """
877 if module is None:
878 return True
Benjamin Peterson6cadba72008-11-19 22:38:29 +0000879 elif inspect.getmodule(object) is not None:
880 return module is inspect.getmodule(object)
Tim Peters8485b562004-08-04 18:46:34 +0000881 elif inspect.isfunction(object):
Neal Norwitz221085d2007-02-25 20:55:47 +0000882 return module.__dict__ is object.__globals__
Tim Peters8485b562004-08-04 18:46:34 +0000883 elif inspect.isclass(object):
884 return module.__name__ == object.__module__
Tim Peters8485b562004-08-04 18:46:34 +0000885 elif hasattr(object, '__module__'):
886 return module.__name__ == object.__module__
887 elif isinstance(object, property):
888 return True # [XX] no way not be sure.
889 else:
890 raise ValueError("object must be a class or function")
891
Tim Petersf3f57472004-08-08 06:11:48 +0000892 def _find(self, tests, obj, name, module, source_lines, globs, seen):
Tim Peters8485b562004-08-04 18:46:34 +0000893 """
894 Find tests for the given object and any contained objects, and
895 add them to `tests`.
896 """
897 if self._verbose:
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000898 print('Finding tests in %s' % name)
Tim Peters8485b562004-08-04 18:46:34 +0000899
900 # If we've already processed this object, then ignore it.
901 if id(obj) in seen:
902 return
903 seen[id(obj)] = 1
904
905 # Find a test for this object, and add it to the list of tests.
906 test = self._get_test(obj, name, module, globs, source_lines)
907 if test is not None:
908 tests.append(test)
909
910 # Look for tests in a module's contained objects.
911 if inspect.ismodule(obj) and self._recurse:
912 for valname, val in obj.__dict__.items():
Tim Peters8485b562004-08-04 18:46:34 +0000913 valname = '%s.%s' % (name, valname)
914 # Recurse to functions & classes.
915 if ((inspect.isfunction(val) or inspect.isclass(val)) and
Tim Petersf3f57472004-08-08 06:11:48 +0000916 self._from_module(module, val)):
Tim Peters8485b562004-08-04 18:46:34 +0000917 self._find(tests, val, valname, module, source_lines,
Tim Petersf3f57472004-08-08 06:11:48 +0000918 globs, seen)
Tim Peters8485b562004-08-04 18:46:34 +0000919
920 # Look for tests in a module's __test__ dictionary.
921 if inspect.ismodule(obj) and self._recurse:
922 for valname, val in getattr(obj, '__test__', {}).items():
Guido van Rossum3172c5d2007-10-16 18:12:55 +0000923 if not isinstance(valname, str):
Tim Peters8485b562004-08-04 18:46:34 +0000924 raise ValueError("DocTestFinder.find: __test__ keys "
925 "must be strings: %r" %
926 (type(valname),))
927 if not (inspect.isfunction(val) or inspect.isclass(val) or
928 inspect.ismethod(val) or inspect.ismodule(val) or
Guido van Rossum3172c5d2007-10-16 18:12:55 +0000929 isinstance(val, str)):
Tim Peters8485b562004-08-04 18:46:34 +0000930 raise ValueError("DocTestFinder.find: __test__ values "
931 "must be strings, functions, methods, "
932 "classes, or modules: %r" %
933 (type(val),))
Tim Petersc5684782004-09-13 01:07:12 +0000934 valname = '%s.__test__.%s' % (name, valname)
Tim Peters8485b562004-08-04 18:46:34 +0000935 self._find(tests, val, valname, module, source_lines,
Tim Petersf3f57472004-08-08 06:11:48 +0000936 globs, seen)
Tim Peters8485b562004-08-04 18:46:34 +0000937
938 # Look for tests in a class's contained objects.
939 if inspect.isclass(obj) and self._recurse:
940 for valname, val in obj.__dict__.items():
Tim Peters8485b562004-08-04 18:46:34 +0000941 # Special handling for staticmethod/classmethod.
942 if isinstance(val, staticmethod):
943 val = getattr(obj, valname)
944 if isinstance(val, classmethod):
Christian Heimesff737952007-11-27 10:40:20 +0000945 val = getattr(obj, valname).__func__
Tim Peters8485b562004-08-04 18:46:34 +0000946
947 # Recurse to methods, properties, and nested classes.
948 if ((inspect.isfunction(val) or inspect.isclass(val) or
Tim Petersf3f57472004-08-08 06:11:48 +0000949 isinstance(val, property)) and
950 self._from_module(module, val)):
Tim Peters8485b562004-08-04 18:46:34 +0000951 valname = '%s.%s' % (name, valname)
952 self._find(tests, val, valname, module, source_lines,
Tim Petersf3f57472004-08-08 06:11:48 +0000953 globs, seen)
Tim Peters8485b562004-08-04 18:46:34 +0000954
955 def _get_test(self, obj, name, module, globs, source_lines):
956 """
957 Return a DocTest for the given object, if it defines a docstring;
958 otherwise, return None.
959 """
960 # Extract the object's docstring. If it doesn't have one,
961 # then return None (no test for this object).
Guido van Rossum3172c5d2007-10-16 18:12:55 +0000962 if isinstance(obj, str):
Tim Peters8485b562004-08-04 18:46:34 +0000963 docstring = obj
964 else:
965 try:
966 if obj.__doc__ is None:
Edward Loper32ddbf72004-09-13 05:47:24 +0000967 docstring = ''
968 else:
Jim Fulton7d428782004-10-13 14:15:32 +0000969 docstring = obj.__doc__
Guido van Rossum3172c5d2007-10-16 18:12:55 +0000970 if not isinstance(docstring, str):
Jim Fulton7d428782004-10-13 14:15:32 +0000971 docstring = str(docstring)
Tim Peters8485b562004-08-04 18:46:34 +0000972 except (TypeError, AttributeError):
Edward Loper32ddbf72004-09-13 05:47:24 +0000973 docstring = ''
Tim Peters8485b562004-08-04 18:46:34 +0000974
975 # Find the docstring's location in the file.
976 lineno = self._find_lineno(obj, source_lines)
977
Edward Loper32ddbf72004-09-13 05:47:24 +0000978 # Don't bother if the docstring is empty.
979 if self._exclude_empty and not docstring:
980 return None
981
Tim Peters8485b562004-08-04 18:46:34 +0000982 # Return a DocTest for this object.
983 if module is None:
984 filename = None
985 else:
986 filename = getattr(module, '__file__', module.__name__)
Jim Fulton07a349c2004-08-22 14:10:00 +0000987 if filename[-4:] in (".pyc", ".pyo"):
988 filename = filename[:-1]
Edward Lopera1ef6112004-08-09 16:14:41 +0000989 return self._parser.get_doctest(docstring, globs, name,
990 filename, lineno)
Tim Peters8485b562004-08-04 18:46:34 +0000991
992 def _find_lineno(self, obj, source_lines):
993 """
994 Return a line number of the given object's docstring. Note:
995 this method assumes that the object has a docstring.
996 """
997 lineno = None
998
999 # Find the line number for modules.
1000 if inspect.ismodule(obj):
1001 lineno = 0
1002
1003 # Find the line number for classes.
1004 # Note: this could be fooled if a class is defined multiple
1005 # times in a single file.
1006 if inspect.isclass(obj):
1007 if source_lines is None:
1008 return None
1009 pat = re.compile(r'^\s*class\s*%s\b' %
1010 getattr(obj, '__name__', '-'))
1011 for i, line in enumerate(source_lines):
1012 if pat.match(line):
1013 lineno = i
1014 break
1015
1016 # Find the line number for functions & methods.
Christian Heimesff737952007-11-27 10:40:20 +00001017 if inspect.ismethod(obj): obj = obj.__func__
Neal Norwitz221085d2007-02-25 20:55:47 +00001018 if inspect.isfunction(obj): obj = obj.__code__
Tim Peters8485b562004-08-04 18:46:34 +00001019 if inspect.istraceback(obj): obj = obj.tb_frame
1020 if inspect.isframe(obj): obj = obj.f_code
1021 if inspect.iscode(obj):
1022 lineno = getattr(obj, 'co_firstlineno', None)-1
1023
1024 # Find the line number where the docstring starts. Assume
1025 # that it's the first line that begins with a quote mark.
1026 # Note: this could be fooled by a multiline function
1027 # signature, where a continuation line begins with a quote
1028 # mark.
1029 if lineno is not None:
1030 if source_lines is None:
1031 return lineno+1
1032 pat = re.compile('(^|.*:)\s*\w*("|\')')
1033 for lineno in range(lineno, len(source_lines)):
1034 if pat.match(source_lines[lineno]):
1035 return lineno
1036
1037 # We couldn't find the line number.
1038 return None
1039
1040######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00001041## 5. DocTest Runner
Tim Peters8485b562004-08-04 18:46:34 +00001042######################################################################
1043
Tim Peters8485b562004-08-04 18:46:34 +00001044class DocTestRunner:
1045 """
1046 A class used to run DocTest test cases, and accumulate statistics.
1047 The `run` method is used to process a single DocTest case. It
1048 returns a tuple `(f, t)`, where `t` is the number of test cases
1049 tried, and `f` is the number of test cases that failed.
1050
1051 >>> tests = DocTestFinder().find(_TestClass)
1052 >>> runner = DocTestRunner(verbose=False)
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00001053 >>> tests.sort(key = lambda test: test.name)
Tim Peters8485b562004-08-04 18:46:34 +00001054 >>> for test in tests:
Guido van Rossum7131f842007-02-09 20:13:25 +00001055 ... print(test.name, '->', runner.run(test))
Christian Heimes25bb7832008-01-11 16:17:00 +00001056 _TestClass -> TestResults(failed=0, attempted=2)
1057 _TestClass.__init__ -> TestResults(failed=0, attempted=2)
1058 _TestClass.get -> TestResults(failed=0, attempted=2)
1059 _TestClass.square -> TestResults(failed=0, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +00001060
1061 The `summarize` method prints a summary of all the test cases that
1062 have been run by the runner, and returns an aggregated `(f, t)`
1063 tuple:
1064
1065 >>> runner.summarize(verbose=1)
1066 4 items passed all tests:
1067 2 tests in _TestClass
1068 2 tests in _TestClass.__init__
1069 2 tests in _TestClass.get
1070 1 tests in _TestClass.square
1071 7 tests in 4 items.
1072 7 passed and 0 failed.
1073 Test passed.
Christian Heimes25bb7832008-01-11 16:17:00 +00001074 TestResults(failed=0, attempted=7)
Tim Peters8485b562004-08-04 18:46:34 +00001075
1076 The aggregated number of tried examples and failed examples is
1077 also available via the `tries` and `failures` attributes:
1078
1079 >>> runner.tries
1080 7
1081 >>> runner.failures
1082 0
1083
1084 The comparison between expected outputs and actual outputs is done
Edward Loper34fcb142004-08-09 02:45:41 +00001085 by an `OutputChecker`. This comparison may be customized with a
1086 number of option flags; see the documentation for `testmod` for
1087 more information. If the option flags are insufficient, then the
1088 comparison may also be customized by passing a subclass of
1089 `OutputChecker` to the constructor.
Tim Peters8485b562004-08-04 18:46:34 +00001090
1091 The test runner's display output can be controlled in two ways.
1092 First, an output function (`out) can be passed to
1093 `TestRunner.run`; this function will be called with strings that
1094 should be displayed. It defaults to `sys.stdout.write`. If
1095 capturing the output is not sufficient, then the display output
1096 can be also customized by subclassing DocTestRunner, and
1097 overriding the methods `report_start`, `report_success`,
1098 `report_unexpected_exception`, and `report_failure`.
1099 """
1100 # This divider string is used to separate failure messages, and to
1101 # separate sections of the summary.
1102 DIVIDER = "*" * 70
1103
Edward Loper34fcb142004-08-09 02:45:41 +00001104 def __init__(self, checker=None, verbose=None, optionflags=0):
Tim Peters8485b562004-08-04 18:46:34 +00001105 """
1106 Create a new test runner.
1107
Edward Loper34fcb142004-08-09 02:45:41 +00001108 Optional keyword arg `checker` is the `OutputChecker` that
1109 should be used to compare the expected outputs and actual
1110 outputs of doctest examples.
1111
Tim Peters8485b562004-08-04 18:46:34 +00001112 Optional keyword arg 'verbose' prints lots of stuff if true,
1113 only failures if false; by default, it's true iff '-v' is in
1114 sys.argv.
1115
1116 Optional argument `optionflags` can be used to control how the
1117 test runner compares expected output to actual output, and how
1118 it displays failures. See the documentation for `testmod` for
1119 more information.
1120 """
Edward Loper34fcb142004-08-09 02:45:41 +00001121 self._checker = checker or OutputChecker()
Tim Peters8a7d2d52001-01-16 07:10:57 +00001122 if verbose is None:
Tim Peters8485b562004-08-04 18:46:34 +00001123 verbose = '-v' in sys.argv
1124 self._verbose = verbose
Tim Peters6ebe61f2003-06-27 20:48:05 +00001125 self.optionflags = optionflags
Jim Fulton07a349c2004-08-22 14:10:00 +00001126 self.original_optionflags = optionflags
Tim Peters6ebe61f2003-06-27 20:48:05 +00001127
Tim Peters8485b562004-08-04 18:46:34 +00001128 # Keep track of the examples we've run.
1129 self.tries = 0
1130 self.failures = 0
1131 self._name2ft = {}
Tim Peters8a7d2d52001-01-16 07:10:57 +00001132
Tim Peters8485b562004-08-04 18:46:34 +00001133 # Create a fake output target for capturing doctest output.
1134 self._fakeout = _SpoofOut()
Tim Peters4fd9e2f2001-08-18 00:05:50 +00001135
Tim Peters8485b562004-08-04 18:46:34 +00001136 #/////////////////////////////////////////////////////////////////
Tim Peters8485b562004-08-04 18:46:34 +00001137 # Reporting methods
1138 #/////////////////////////////////////////////////////////////////
Tim Peters17111f32001-10-03 04:08:26 +00001139
Tim Peters8485b562004-08-04 18:46:34 +00001140 def report_start(self, out, test, example):
Tim Peters8a7d2d52001-01-16 07:10:57 +00001141 """
Tim Peters8485b562004-08-04 18:46:34 +00001142 Report that the test runner is about to process the given
1143 example. (Only displays a message if verbose=True)
1144 """
1145 if self._verbose:
Edward Loperaacf0832004-08-26 01:19:50 +00001146 if example.want:
1147 out('Trying:\n' + _indent(example.source) +
1148 'Expecting:\n' + _indent(example.want))
1149 else:
1150 out('Trying:\n' + _indent(example.source) +
1151 'Expecting nothing\n')
Tim Peters8a7d2d52001-01-16 07:10:57 +00001152
Tim Peters8485b562004-08-04 18:46:34 +00001153 def report_success(self, out, test, example, got):
1154 """
1155 Report that the given example ran successfully. (Only
1156 displays a message if verbose=True)
1157 """
1158 if self._verbose:
1159 out("ok\n")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001160
Tim Peters8485b562004-08-04 18:46:34 +00001161 def report_failure(self, out, test, example, got):
1162 """
1163 Report that the given example failed.
1164 """
Edward Loper8e4a34b2004-08-12 02:34:27 +00001165 out(self._failure_header(test, example) +
Edward Loperca9111e2004-08-26 03:00:24 +00001166 self._checker.output_difference(example, got, self.optionflags))
Tim Peters7402f792001-10-02 03:53:41 +00001167
Tim Peters8485b562004-08-04 18:46:34 +00001168 def report_unexpected_exception(self, out, test, example, exc_info):
1169 """
1170 Report that the given example raised an unexpected exception.
1171 """
Edward Loper8e4a34b2004-08-12 02:34:27 +00001172 out(self._failure_header(test, example) +
Edward Loperaacf0832004-08-26 01:19:50 +00001173 'Exception raised:\n' + _indent(_exception_traceback(exc_info)))
Tim Peters7402f792001-10-02 03:53:41 +00001174
Edward Loper8e4a34b2004-08-12 02:34:27 +00001175 def _failure_header(self, test, example):
Jim Fulton07a349c2004-08-22 14:10:00 +00001176 out = [self.DIVIDER]
1177 if test.filename:
1178 if test.lineno is not None and example.lineno is not None:
1179 lineno = test.lineno + example.lineno + 1
1180 else:
1181 lineno = '?'
1182 out.append('File "%s", line %s, in %s' %
1183 (test.filename, lineno, test.name))
Tim Peters8485b562004-08-04 18:46:34 +00001184 else:
Jim Fulton07a349c2004-08-22 14:10:00 +00001185 out.append('Line %s, in %s' % (example.lineno+1, test.name))
1186 out.append('Failed example:')
1187 source = example.source
Edward Loperaacf0832004-08-26 01:19:50 +00001188 out.append(_indent(source))
1189 return '\n'.join(out)
Tim Peters7402f792001-10-02 03:53:41 +00001190
Tim Peters8485b562004-08-04 18:46:34 +00001191 #/////////////////////////////////////////////////////////////////
1192 # DocTest Running
1193 #/////////////////////////////////////////////////////////////////
Tim Peters7402f792001-10-02 03:53:41 +00001194
Tim Peters8485b562004-08-04 18:46:34 +00001195 def __run(self, test, compileflags, out):
Tim Peters8a7d2d52001-01-16 07:10:57 +00001196 """
Tim Peters8485b562004-08-04 18:46:34 +00001197 Run the examples in `test`. Write the outcome of each example
1198 with one of the `DocTestRunner.report_*` methods, using the
1199 writer function `out`. `compileflags` is the set of compiler
1200 flags that should be used to execute examples. Return a tuple
1201 `(f, t)`, where `t` is the number of examples tried, and `f`
1202 is the number of examples that failed. The examples are run
1203 in the namespace `test.globs`.
1204 """
1205 # Keep track of the number of failures and tries.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001206 failures = tries = 0
Tim Peters8485b562004-08-04 18:46:34 +00001207
1208 # Save the option flags (since option directives can be used
1209 # to modify them).
1210 original_optionflags = self.optionflags
1211
Tim Peters1fbf9c52004-09-04 17:21:02 +00001212 SUCCESS, FAILURE, BOOM = range(3) # `outcome` state
1213
1214 check = self._checker.check_output
1215
Tim Peters8485b562004-08-04 18:46:34 +00001216 # Process each example.
Edward Loper2de91ba2004-08-27 02:07:46 +00001217 for examplenum, example in enumerate(test.examples):
1218
Ezio Melotti13925002011-03-16 11:05:33 +02001219 # If REPORT_ONLY_FIRST_FAILURE is set, then suppress
Edward Lopera89f88d2004-08-26 02:45:51 +00001220 # reporting after the first failure.
1221 quiet = (self.optionflags & REPORT_ONLY_FIRST_FAILURE and
1222 failures > 0)
1223
Edward Loper74bca7a2004-08-12 02:27:44 +00001224 # Merge in the example's options.
1225 self.optionflags = original_optionflags
1226 if example.options:
1227 for (optionflag, val) in example.options.items():
1228 if val:
1229 self.optionflags |= optionflag
1230 else:
1231 self.optionflags &= ~optionflag
Tim Peters8485b562004-08-04 18:46:34 +00001232
Thomas Wouters477c8d52006-05-27 19:21:47 +00001233 # If 'SKIP' is set, then skip this example.
1234 if self.optionflags & SKIP:
1235 continue
1236
Tim Peters8485b562004-08-04 18:46:34 +00001237 # Record that we started this example.
1238 tries += 1
Edward Lopera89f88d2004-08-26 02:45:51 +00001239 if not quiet:
1240 self.report_start(out, test, example)
Tim Peters8485b562004-08-04 18:46:34 +00001241
Edward Loper2de91ba2004-08-27 02:07:46 +00001242 # Use a special filename for compile(), so we can retrieve
1243 # the source code during interactive debugging (see
1244 # __patched_linecache_getlines).
1245 filename = '<doctest %s[%d]>' % (test.name, examplenum)
1246
Tim Peters8485b562004-08-04 18:46:34 +00001247 # Run the example in the given context (globs), and record
1248 # any exception that gets raised. (But don't intercept
1249 # keyboard interrupts.)
1250 try:
Tim Peters208ca702004-08-09 04:12:36 +00001251 # Don't blink! This is where the user's code gets run.
Georg Brandl7cae87c2006-09-06 06:51:57 +00001252 exec(compile(example.source, filename, "single",
1253 compileflags, 1), test.globs)
Edward Loper2de91ba2004-08-27 02:07:46 +00001254 self.debugger.set_continue() # ==== Example Finished ====
Tim Peters8485b562004-08-04 18:46:34 +00001255 exception = None
1256 except KeyboardInterrupt:
1257 raise
1258 except:
1259 exception = sys.exc_info()
Edward Loper2de91ba2004-08-27 02:07:46 +00001260 self.debugger.set_continue() # ==== Example Finished ====
Tim Peters8485b562004-08-04 18:46:34 +00001261
Tim Peters208ca702004-08-09 04:12:36 +00001262 got = self._fakeout.getvalue() # the actual output
Tim Peters8485b562004-08-04 18:46:34 +00001263 self._fakeout.truncate(0)
Tim Peters1fbf9c52004-09-04 17:21:02 +00001264 outcome = FAILURE # guilty until proved innocent or insane
Tim Peters8485b562004-08-04 18:46:34 +00001265
1266 # If the example executed without raising any exceptions,
Tim Peters1fbf9c52004-09-04 17:21:02 +00001267 # verify its output.
Tim Peters8485b562004-08-04 18:46:34 +00001268 if exception is None:
Tim Peters1fbf9c52004-09-04 17:21:02 +00001269 if check(example.want, got, self.optionflags):
1270 outcome = SUCCESS
Tim Peters8485b562004-08-04 18:46:34 +00001271
Tim Peters1fbf9c52004-09-04 17:21:02 +00001272 # The example raised an exception: check if it was expected.
Tim Peters8485b562004-08-04 18:46:34 +00001273 else:
Benjamin Petersoneec3d712008-06-11 15:59:43 +00001274 exc_msg = traceback.format_exception_only(*exception[:2])[-1]
Tim Peters1fbf9c52004-09-04 17:21:02 +00001275 if not quiet:
Benjamin Petersoneec3d712008-06-11 15:59:43 +00001276 got += _exception_traceback(exception)
Tim Peters8485b562004-08-04 18:46:34 +00001277
Tim Peters1fbf9c52004-09-04 17:21:02 +00001278 # If `example.exc_msg` is None, then we weren't expecting
1279 # an exception.
Edward Lopera6b68322004-08-26 00:05:43 +00001280 if example.exc_msg is None:
Tim Peters1fbf9c52004-09-04 17:21:02 +00001281 outcome = BOOM
1282
1283 # We expected an exception: see whether it matches.
1284 elif check(example.exc_msg, exc_msg, self.optionflags):
1285 outcome = SUCCESS
1286
1287 # Another chance if they didn't care about the detail.
1288 elif self.optionflags & IGNORE_EXCEPTION_DETAIL:
Nick Coghlan5e76e942010-06-12 13:42:46 +00001289 m1 = re.match(r'(?:[^:]*\.)?([^:]*:)', example.exc_msg)
1290 m2 = re.match(r'(?:[^:]*\.)?([^:]*:)', exc_msg)
1291 if m1 and m2 and check(m1.group(1), m2.group(1),
Tim Peters1fbf9c52004-09-04 17:21:02 +00001292 self.optionflags):
1293 outcome = SUCCESS
1294
1295 # Report the outcome.
1296 if outcome is SUCCESS:
1297 if not quiet:
1298 self.report_success(out, test, example, got)
1299 elif outcome is FAILURE:
1300 if not quiet:
1301 self.report_failure(out, test, example, got)
1302 failures += 1
1303 elif outcome is BOOM:
1304 if not quiet:
1305 self.report_unexpected_exception(out, test, example,
Benjamin Petersoneec3d712008-06-11 15:59:43 +00001306 exception)
Tim Peters1fbf9c52004-09-04 17:21:02 +00001307 failures += 1
1308 else:
1309 assert False, ("unknown outcome", outcome)
Tim Peters8485b562004-08-04 18:46:34 +00001310
1311 # Restore the option flags (in case they were modified)
1312 self.optionflags = original_optionflags
1313
1314 # Record and return the number of failures and tries.
1315 self.__record_outcome(test, failures, tries)
Christian Heimes25bb7832008-01-11 16:17:00 +00001316 return TestResults(failures, tries)
Tim Peters8a7d2d52001-01-16 07:10:57 +00001317
Tim Peters8485b562004-08-04 18:46:34 +00001318 def __record_outcome(self, test, f, t):
1319 """
1320 Record the fact that the given DocTest (`test`) generated `f`
1321 failures out of `t` tried examples.
1322 """
1323 f2, t2 = self._name2ft.get(test.name, (0,0))
1324 self._name2ft[test.name] = (f+f2, t+t2)
1325 self.failures += f
1326 self.tries += t
1327
Edward Loper2de91ba2004-08-27 02:07:46 +00001328 __LINECACHE_FILENAME_RE = re.compile(r'<doctest '
Florent Xiclunad9f57632010-10-14 20:56:20 +00001329 r'(?P<name>.+)'
Edward Loper2de91ba2004-08-27 02:07:46 +00001330 r'\[(?P<examplenum>\d+)\]>$')
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00001331 def __patched_linecache_getlines(self, filename, module_globals=None):
Edward Loper2de91ba2004-08-27 02:07:46 +00001332 m = self.__LINECACHE_FILENAME_RE.match(filename)
1333 if m and m.group('name') == self.test.name:
1334 example = self.test.examples[int(m.group('examplenum'))]
Benjamin Peterson04b50002010-04-11 21:39:55 +00001335 return example.source.splitlines(True)
Edward Loper2de91ba2004-08-27 02:07:46 +00001336 else:
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00001337 return self.save_linecache_getlines(filename, module_globals)
Edward Loper2de91ba2004-08-27 02:07:46 +00001338
Tim Peters8485b562004-08-04 18:46:34 +00001339 def run(self, test, compileflags=None, out=None, clear_globs=True):
1340 """
1341 Run the examples in `test`, and display the results using the
1342 writer function `out`.
1343
1344 The examples are run in the namespace `test.globs`. If
1345 `clear_globs` is true (the default), then this namespace will
1346 be cleared after the test runs, to help with garbage
1347 collection. If you would like to examine the namespace after
1348 the test completes, then use `clear_globs=False`.
1349
1350 `compileflags` gives the set of flags that should be used by
1351 the Python compiler when running the examples. If not
1352 specified, then it will default to the set of future-import
1353 flags that apply to `globs`.
1354
1355 The output of each example is checked using
1356 `DocTestRunner.check_output`, and the results are formatted by
1357 the `DocTestRunner.report_*` methods.
1358 """
Edward Loper2de91ba2004-08-27 02:07:46 +00001359 self.test = test
1360
Tim Peters8485b562004-08-04 18:46:34 +00001361 if compileflags is None:
1362 compileflags = _extract_future_flags(test.globs)
Jim Fulton356fd192004-08-09 11:34:47 +00001363
Tim Peters6c542b72004-08-09 16:43:36 +00001364 save_stdout = sys.stdout
Tim Peters8485b562004-08-04 18:46:34 +00001365 if out is None:
Florent Xicluna59250852010-02-27 14:21:57 +00001366 encoding = save_stdout.encoding
1367 if encoding is None or encoding.lower() == 'utf-8':
1368 out = save_stdout.write
1369 else:
1370 # Use backslashreplace error handling on write
1371 def out(s):
1372 s = str(s.encode(encoding, 'backslashreplace'), encoding)
1373 save_stdout.write(s)
Tim Peters6c542b72004-08-09 16:43:36 +00001374 sys.stdout = self._fakeout
Tim Peters8485b562004-08-04 18:46:34 +00001375
Edward Loper2de91ba2004-08-27 02:07:46 +00001376 # Patch pdb.set_trace to restore sys.stdout during interactive
1377 # debugging (so it's not still redirected to self._fakeout).
1378 # Note that the interactive output will go to *our*
1379 # save_stdout, even if that's not the real sys.stdout; this
1380 # allows us to write test cases for the set_trace behavior.
Tim Peters6c542b72004-08-09 16:43:36 +00001381 save_set_trace = pdb.set_trace
Edward Loper2de91ba2004-08-27 02:07:46 +00001382 self.debugger = _OutputRedirectingPdb(save_stdout)
1383 self.debugger.reset()
1384 pdb.set_trace = self.debugger.set_trace
1385
1386 # Patch linecache.getlines, so we can see the example's source
1387 # when we're inside the debugger.
1388 self.save_linecache_getlines = linecache.getlines
1389 linecache.getlines = self.__patched_linecache_getlines
1390
Georg Brandl25fbb892010-07-30 09:23:23 +00001391 # Make sure sys.displayhook just prints the value to stdout
1392 save_displayhook = sys.displayhook
1393 sys.displayhook = sys.__displayhook__
1394
Tim Peters8485b562004-08-04 18:46:34 +00001395 try:
Tim Peters8485b562004-08-04 18:46:34 +00001396 return self.__run(test, compileflags, out)
1397 finally:
Tim Peters6c542b72004-08-09 16:43:36 +00001398 sys.stdout = save_stdout
1399 pdb.set_trace = save_set_trace
Edward Loper2de91ba2004-08-27 02:07:46 +00001400 linecache.getlines = self.save_linecache_getlines
Georg Brandl25fbb892010-07-30 09:23:23 +00001401 sys.displayhook = save_displayhook
Tim Peters8485b562004-08-04 18:46:34 +00001402 if clear_globs:
1403 test.globs.clear()
Benjamin Petersonfbf66bd2008-07-29 15:55:50 +00001404 import builtins
1405 builtins._ = None
Tim Peters8485b562004-08-04 18:46:34 +00001406
1407 #/////////////////////////////////////////////////////////////////
1408 # Summarization
1409 #/////////////////////////////////////////////////////////////////
Tim Peters8a7d2d52001-01-16 07:10:57 +00001410 def summarize(self, verbose=None):
1411 """
Tim Peters8485b562004-08-04 18:46:34 +00001412 Print a summary of all the test cases that have been run by
1413 this DocTestRunner, and return a tuple `(f, t)`, where `f` is
1414 the total number of failed examples, and `t` is the total
1415 number of tried examples.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001416
Tim Peters8485b562004-08-04 18:46:34 +00001417 The optional `verbose` argument controls how detailed the
1418 summary is. If the verbosity is not specified, then the
1419 DocTestRunner's verbosity is used.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001420 """
Tim Peters8a7d2d52001-01-16 07:10:57 +00001421 if verbose is None:
Tim Peters8485b562004-08-04 18:46:34 +00001422 verbose = self._verbose
Tim Peters8a7d2d52001-01-16 07:10:57 +00001423 notests = []
1424 passed = []
1425 failed = []
1426 totalt = totalf = 0
Tim Peters8485b562004-08-04 18:46:34 +00001427 for x in self._name2ft.items():
Tim Peters8a7d2d52001-01-16 07:10:57 +00001428 name, (f, t) = x
1429 assert f <= t
Tim Peters8485b562004-08-04 18:46:34 +00001430 totalt += t
1431 totalf += f
Tim Peters8a7d2d52001-01-16 07:10:57 +00001432 if t == 0:
1433 notests.append(name)
1434 elif f == 0:
1435 passed.append( (name, t) )
1436 else:
1437 failed.append(x)
1438 if verbose:
1439 if notests:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001440 print(len(notests), "items had no tests:")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001441 notests.sort()
1442 for thing in notests:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001443 print(" ", thing)
Tim Peters8a7d2d52001-01-16 07:10:57 +00001444 if passed:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001445 print(len(passed), "items passed all tests:")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001446 passed.sort()
1447 for thing, count in passed:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001448 print(" %3d tests in %s" % (count, thing))
Tim Peters8a7d2d52001-01-16 07:10:57 +00001449 if failed:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001450 print(self.DIVIDER)
1451 print(len(failed), "items had failures:")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001452 failed.sort()
1453 for thing, (f, t) in failed:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001454 print(" %3d of %3d in %s" % (f, t, thing))
Tim Peters8a7d2d52001-01-16 07:10:57 +00001455 if verbose:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001456 print(totalt, "tests in", len(self._name2ft), "items.")
1457 print(totalt - totalf, "passed and", totalf, "failed.")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001458 if totalf:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001459 print("***Test Failed***", totalf, "failures.")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001460 elif verbose:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001461 print("Test passed.")
Christian Heimes25bb7832008-01-11 16:17:00 +00001462 return TestResults(totalf, totalt)
Tim Peters8a7d2d52001-01-16 07:10:57 +00001463
Tim Peters82076ef2004-09-13 00:52:51 +00001464 #/////////////////////////////////////////////////////////////////
1465 # Backward compatibility cruft to maintain doctest.master.
1466 #/////////////////////////////////////////////////////////////////
1467 def merge(self, other):
1468 d = self._name2ft
1469 for name, (f, t) in other._name2ft.items():
1470 if name in d:
Nick Coghlan38622002008-12-15 12:01:34 +00001471 # Don't print here by default, since doing
1472 # so breaks some of the buildbots
1473 #print("*** DocTestRunner.merge: '" + name + "' in both" \
1474 # " testers; summing outcomes.")
Tim Peters82076ef2004-09-13 00:52:51 +00001475 f2, t2 = d[name]
1476 f = f + f2
1477 t = t + t2
1478 d[name] = f, t
1479
Edward Loper34fcb142004-08-09 02:45:41 +00001480class OutputChecker:
1481 """
1482 A class used to check the whether the actual output from a doctest
1483 example matches the expected output. `OutputChecker` defines two
1484 methods: `check_output`, which compares a given pair of outputs,
1485 and returns true if they match; and `output_difference`, which
1486 returns a string describing the differences between two outputs.
1487 """
Georg Brandl559e5d72008-06-11 18:37:52 +00001488 def _toAscii(self, s):
1489 """
1490 Convert string to hex-escaped ASCII string.
1491 """
1492 return str(s.encode('ASCII', 'backslashreplace'), "ASCII")
1493
Edward Loper34fcb142004-08-09 02:45:41 +00001494 def check_output(self, want, got, optionflags):
1495 """
Edward Loper74bca7a2004-08-12 02:27:44 +00001496 Return True iff the actual output from an example (`got`)
1497 matches the expected output (`want`). These strings are
1498 always considered to match if they are identical; but
1499 depending on what option flags the test runner is using,
1500 several non-exact match types are also possible. See the
1501 documentation for `TestRunner` for more information about
1502 option flags.
Edward Loper34fcb142004-08-09 02:45:41 +00001503 """
Georg Brandl559e5d72008-06-11 18:37:52 +00001504
1505 # If `want` contains hex-escaped character such as "\u1234",
1506 # then `want` is a string of six characters(e.g. [\,u,1,2,3,4]).
1507 # On the other hand, `got` could be an another sequence of
1508 # characters such as [\u1234], so `want` and `got` should
1509 # be folded to hex-escaped ASCII string to compare.
1510 got = self._toAscii(got)
1511 want = self._toAscii(want)
1512
Edward Loper34fcb142004-08-09 02:45:41 +00001513 # Handle the common case first, for efficiency:
1514 # if they're string-identical, always return true.
1515 if got == want:
1516 return True
1517
1518 # The values True and False replaced 1 and 0 as the return
1519 # value for boolean comparisons in Python 2.3.
1520 if not (optionflags & DONT_ACCEPT_TRUE_FOR_1):
1521 if (got,want) == ("True\n", "1\n"):
1522 return True
1523 if (got,want) == ("False\n", "0\n"):
1524 return True
1525
1526 # <BLANKLINE> can be used as a special sequence to signify a
1527 # blank line, unless the DONT_ACCEPT_BLANKLINE flag is used.
1528 if not (optionflags & DONT_ACCEPT_BLANKLINE):
1529 # Replace <BLANKLINE> in want with a blank line.
1530 want = re.sub('(?m)^%s\s*?$' % re.escape(BLANKLINE_MARKER),
1531 '', want)
1532 # If a line in got contains only spaces, then remove the
1533 # spaces.
1534 got = re.sub('(?m)^\s*?$', '', got)
1535 if got == want:
1536 return True
1537
1538 # This flag causes doctest to ignore any differences in the
1539 # contents of whitespace strings. Note that this can be used
Tim Peters3fa8c202004-08-23 21:43:39 +00001540 # in conjunction with the ELLIPSIS flag.
Tim Peters1cf3aa62004-08-19 06:49:33 +00001541 if optionflags & NORMALIZE_WHITESPACE:
Edward Loper34fcb142004-08-09 02:45:41 +00001542 got = ' '.join(got.split())
1543 want = ' '.join(want.split())
1544 if got == want:
1545 return True
1546
1547 # The ELLIPSIS flag says to let the sequence "..." in `want`
Tim Peters26b3ebb2004-08-19 08:10:08 +00001548 # match any substring in `got`.
Tim Peters1cf3aa62004-08-19 06:49:33 +00001549 if optionflags & ELLIPSIS:
Tim Petersb0a04e12004-08-20 02:08:04 +00001550 if _ellipsis_match(want, got):
Edward Loper34fcb142004-08-09 02:45:41 +00001551 return True
1552
1553 # We didn't find any match; return false.
1554 return False
1555
Tim Petersc6cbab02004-08-22 19:43:28 +00001556 # Should we do a fancy diff?
1557 def _do_a_fancy_diff(self, want, got, optionflags):
1558 # Not unless they asked for a fancy diff.
Edward Loper71f55af2004-08-26 01:41:51 +00001559 if not optionflags & (REPORT_UDIFF |
1560 REPORT_CDIFF |
1561 REPORT_NDIFF):
Tim Petersc6cbab02004-08-22 19:43:28 +00001562 return False
Tim Peters5b799c12004-08-26 05:21:59 +00001563
Tim Petersc6cbab02004-08-22 19:43:28 +00001564 # If expected output uses ellipsis, a meaningful fancy diff is
Tim Peters5b799c12004-08-26 05:21:59 +00001565 # too hard ... or maybe not. In two real-life failures Tim saw,
1566 # a diff was a major help anyway, so this is commented out.
1567 # [todo] _ellipsis_match() knows which pieces do and don't match,
1568 # and could be the basis for a kick-ass diff in this case.
1569 ##if optionflags & ELLIPSIS and ELLIPSIS_MARKER in want:
1570 ## return False
1571
Tim Petersc6cbab02004-08-22 19:43:28 +00001572 # ndiff does intraline difference marking, so can be useful even
Tim Peters5b799c12004-08-26 05:21:59 +00001573 # for 1-line differences.
Edward Loper71f55af2004-08-26 01:41:51 +00001574 if optionflags & REPORT_NDIFF:
Tim Petersc6cbab02004-08-22 19:43:28 +00001575 return True
Tim Peters5b799c12004-08-26 05:21:59 +00001576
Tim Petersc6cbab02004-08-22 19:43:28 +00001577 # The other diff types need at least a few lines to be helpful.
1578 return want.count('\n') > 2 and got.count('\n') > 2
1579
Edward Loperca9111e2004-08-26 03:00:24 +00001580 def output_difference(self, example, got, optionflags):
Edward Loper34fcb142004-08-09 02:45:41 +00001581 """
1582 Return a string describing the differences between the
Edward Loperca9111e2004-08-26 03:00:24 +00001583 expected output for a given example (`example`) and the actual
1584 output (`got`). `optionflags` is the set of option flags used
1585 to compare `want` and `got`.
Edward Loper34fcb142004-08-09 02:45:41 +00001586 """
Edward Loperca9111e2004-08-26 03:00:24 +00001587 want = example.want
Edward Loper68ba9a62004-08-12 02:43:49 +00001588 # If <BLANKLINE>s are being used, then replace blank lines
1589 # with <BLANKLINE> in the actual output string.
Edward Loper34fcb142004-08-09 02:45:41 +00001590 if not (optionflags & DONT_ACCEPT_BLANKLINE):
Edward Loper68ba9a62004-08-12 02:43:49 +00001591 got = re.sub('(?m)^[ ]*(?=\n)', BLANKLINE_MARKER, got)
Edward Loper34fcb142004-08-09 02:45:41 +00001592
Tim Peters5b799c12004-08-26 05:21:59 +00001593 # Check if we should use diff.
Tim Petersc6cbab02004-08-22 19:43:28 +00001594 if self._do_a_fancy_diff(want, got, optionflags):
Edward Loper34fcb142004-08-09 02:45:41 +00001595 # Split want & got into lines.
Tim Peterse7edcb82004-08-26 05:44:27 +00001596 want_lines = want.splitlines(True) # True == keep line ends
1597 got_lines = got.splitlines(True)
Edward Loper34fcb142004-08-09 02:45:41 +00001598 # Use difflib to find their differences.
Edward Loper71f55af2004-08-26 01:41:51 +00001599 if optionflags & REPORT_UDIFF:
Edward Loper56629292004-08-26 01:31:56 +00001600 diff = difflib.unified_diff(want_lines, got_lines, n=2)
1601 diff = list(diff)[2:] # strip the diff header
1602 kind = 'unified diff with -expected +actual'
Edward Loper71f55af2004-08-26 01:41:51 +00001603 elif optionflags & REPORT_CDIFF:
Edward Loper56629292004-08-26 01:31:56 +00001604 diff = difflib.context_diff(want_lines, got_lines, n=2)
1605 diff = list(diff)[2:] # strip the diff header
1606 kind = 'context diff with expected followed by actual'
Edward Loper71f55af2004-08-26 01:41:51 +00001607 elif optionflags & REPORT_NDIFF:
Tim Petersc6cbab02004-08-22 19:43:28 +00001608 engine = difflib.Differ(charjunk=difflib.IS_CHARACTER_JUNK)
1609 diff = list(engine.compare(want_lines, got_lines))
1610 kind = 'ndiff with -expected +actual'
Edward Loper34fcb142004-08-09 02:45:41 +00001611 else:
1612 assert 0, 'Bad diff option'
1613 # Remove trailing whitespace on diff output.
1614 diff = [line.rstrip() + '\n' for line in diff]
Edward Loperaacf0832004-08-26 01:19:50 +00001615 return 'Differences (%s):\n' % kind + _indent(''.join(diff))
Edward Loper34fcb142004-08-09 02:45:41 +00001616
1617 # If we're not using diff, then simply list the expected
1618 # output followed by the actual output.
Edward Loperaacf0832004-08-26 01:19:50 +00001619 if want and got:
1620 return 'Expected:\n%sGot:\n%s' % (_indent(want), _indent(got))
1621 elif want:
1622 return 'Expected:\n%sGot nothing\n' % _indent(want)
1623 elif got:
1624 return 'Expected nothing\nGot:\n%s' % _indent(got)
1625 else:
1626 return 'Expected nothing\nGot nothing\n'
Edward Loper34fcb142004-08-09 02:45:41 +00001627
Tim Peters19397e52004-08-06 22:02:59 +00001628class DocTestFailure(Exception):
1629 """A DocTest example has failed in debugging mode.
1630
1631 The exception instance has variables:
1632
1633 - test: the DocTest object being run
1634
Neal Norwitzc082cb72006-08-29 05:40:08 +00001635 - example: the Example object that failed
Tim Peters19397e52004-08-06 22:02:59 +00001636
1637 - got: the actual output
1638 """
1639 def __init__(self, test, example, got):
1640 self.test = test
1641 self.example = example
1642 self.got = got
1643
1644 def __str__(self):
1645 return str(self.test)
1646
1647class UnexpectedException(Exception):
1648 """A DocTest example has encountered an unexpected exception
1649
1650 The exception instance has variables:
1651
1652 - test: the DocTest object being run
1653
Guido van Rossum6a2a2a02006-08-26 20:37:44 +00001654 - example: the Example object that failed
Tim Peters19397e52004-08-06 22:02:59 +00001655
1656 - exc_info: the exception info
1657 """
1658 def __init__(self, test, example, exc_info):
1659 self.test = test
1660 self.example = example
1661 self.exc_info = exc_info
1662
1663 def __str__(self):
1664 return str(self.test)
Tim Petersd1b78272004-08-07 06:03:09 +00001665
Tim Peters19397e52004-08-06 22:02:59 +00001666class DebugRunner(DocTestRunner):
1667 r"""Run doc tests but raise an exception as soon as there is a failure.
1668
1669 If an unexpected exception occurs, an UnexpectedException is raised.
1670 It contains the test, the example, and the original exception:
1671
1672 >>> runner = DebugRunner(verbose=False)
Edward Lopera1ef6112004-08-09 16:14:41 +00001673 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
1674 ... {}, 'foo', 'foo.py', 0)
Tim Peters19397e52004-08-06 22:02:59 +00001675 >>> try:
1676 ... runner.run(test)
Guido van Rossumb940e112007-01-10 16:19:56 +00001677 ... except UnexpectedException as f:
1678 ... failure = f
Tim Peters19397e52004-08-06 22:02:59 +00001679
1680 >>> failure.test is test
1681 True
1682
1683 >>> failure.example.want
1684 '42\n'
1685
1686 >>> exc_info = failure.exc_info
Collin Winter828f04a2007-08-31 00:04:24 +00001687 >>> raise exc_info[1] # Already has the traceback
Tim Peters19397e52004-08-06 22:02:59 +00001688 Traceback (most recent call last):
1689 ...
1690 KeyError
1691
1692 We wrap the original exception to give the calling application
1693 access to the test and example information.
1694
1695 If the output doesn't match, then a DocTestFailure is raised:
1696
Edward Lopera1ef6112004-08-09 16:14:41 +00001697 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00001698 ... >>> x = 1
1699 ... >>> x
1700 ... 2
1701 ... ''', {}, 'foo', 'foo.py', 0)
1702
1703 >>> try:
1704 ... runner.run(test)
Guido van Rossumb940e112007-01-10 16:19:56 +00001705 ... except DocTestFailure as f:
1706 ... failure = f
Tim Peters19397e52004-08-06 22:02:59 +00001707
1708 DocTestFailure objects provide access to the test:
1709
1710 >>> failure.test is test
1711 True
1712
1713 As well as to the example:
1714
1715 >>> failure.example.want
1716 '2\n'
1717
1718 and the actual output:
1719
1720 >>> failure.got
1721 '1\n'
1722
1723 If a failure or error occurs, the globals are left intact:
1724
1725 >>> del test.globs['__builtins__']
1726 >>> test.globs
1727 {'x': 1}
1728
Edward Lopera1ef6112004-08-09 16:14:41 +00001729 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00001730 ... >>> x = 2
1731 ... >>> raise KeyError
1732 ... ''', {}, 'foo', 'foo.py', 0)
1733
1734 >>> runner.run(test)
1735 Traceback (most recent call last):
1736 ...
Guido van Rossum6a2a2a02006-08-26 20:37:44 +00001737 doctest.UnexpectedException: <DocTest foo from foo.py:0 (2 examples)>
Tim Petersd1b78272004-08-07 06:03:09 +00001738
Tim Peters19397e52004-08-06 22:02:59 +00001739 >>> del test.globs['__builtins__']
1740 >>> test.globs
1741 {'x': 2}
1742
1743 But the globals are cleared if there is no error:
1744
Edward Lopera1ef6112004-08-09 16:14:41 +00001745 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00001746 ... >>> x = 2
1747 ... ''', {}, 'foo', 'foo.py', 0)
1748
1749 >>> runner.run(test)
Christian Heimes25bb7832008-01-11 16:17:00 +00001750 TestResults(failed=0, attempted=1)
Tim Peters19397e52004-08-06 22:02:59 +00001751
1752 >>> test.globs
1753 {}
1754
1755 """
1756
1757 def run(self, test, compileflags=None, out=None, clear_globs=True):
1758 r = DocTestRunner.run(self, test, compileflags, out, False)
1759 if clear_globs:
1760 test.globs.clear()
1761 return r
1762
1763 def report_unexpected_exception(self, out, test, example, exc_info):
1764 raise UnexpectedException(test, example, exc_info)
1765
1766 def report_failure(self, out, test, example, got):
1767 raise DocTestFailure(test, example, got)
1768
Tim Peters8485b562004-08-04 18:46:34 +00001769######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00001770## 6. Test Functions
Tim Peters8485b562004-08-04 18:46:34 +00001771######################################################################
1772# These should be backwards compatible.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001773
Tim Peters82076ef2004-09-13 00:52:51 +00001774# For backward compatibility, a global instance of a DocTestRunner
1775# class, updated by testmod.
1776master = None
1777
Thomas Wouters73e5a5b2006-06-08 15:35:45 +00001778def testmod(m=None, name=None, globs=None, verbose=None,
Tim Peters19397e52004-08-06 22:02:59 +00001779 report=True, optionflags=0, extraglobs=None,
Tim Peters958cc892004-09-13 14:53:28 +00001780 raise_on_error=False, exclude_empty=False):
Thomas Wouters73e5a5b2006-06-08 15:35:45 +00001781 """m=None, name=None, globs=None, verbose=None, report=True,
1782 optionflags=0, extraglobs=None, raise_on_error=False,
Tim Peters958cc892004-09-13 14:53:28 +00001783 exclude_empty=False
Tim Peters8a7d2d52001-01-16 07:10:57 +00001784
Martin v. Löwis4581cfa2002-11-22 08:23:09 +00001785 Test examples in docstrings in functions and classes reachable
1786 from module m (or the current module if m is not supplied), starting
Thomas Wouters73e5a5b2006-06-08 15:35:45 +00001787 with m.__doc__.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001788
1789 Also test examples reachable from dict m.__test__ if it exists and is
Tim Petersc2388a22004-08-10 01:41:28 +00001790 not None. m.__test__ maps names to functions, classes and strings;
Tim Peters8a7d2d52001-01-16 07:10:57 +00001791 function and class docstrings are tested even if the name is private;
1792 strings are tested directly, as if they were docstrings.
1793
1794 Return (#failures, #tests).
1795
Alexander Belopolsky977a6842010-08-16 20:17:07 +00001796 See help(doctest) for an overview.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001797
1798 Optional keyword arg "name" gives the name of the module; by default
1799 use m.__name__.
1800
1801 Optional keyword arg "globs" gives a dict to be used as the globals
1802 when executing examples; by default, use m.__dict__. A copy of this
1803 dict is actually used for each docstring, so that each docstring's
1804 examples start with a clean slate.
1805
Tim Peters8485b562004-08-04 18:46:34 +00001806 Optional keyword arg "extraglobs" gives a dictionary that should be
1807 merged into the globals that are used to execute examples. By
1808 default, no extra globals are used. This is new in 2.4.
1809
Tim Peters8a7d2d52001-01-16 07:10:57 +00001810 Optional keyword arg "verbose" prints lots of stuff if true, prints
1811 only failures if false; by default, it's true iff "-v" is in sys.argv.
1812
Tim Peters8a7d2d52001-01-16 07:10:57 +00001813 Optional keyword arg "report" prints a summary at the end when true,
1814 else prints nothing at the end. In verbose mode, the summary is
1815 detailed, else very brief (in fact, empty if all tests passed).
1816
Tim Peters6ebe61f2003-06-27 20:48:05 +00001817 Optional keyword arg "optionflags" or's together module constants,
Tim Petersf82a9de2004-08-22 20:51:53 +00001818 and defaults to 0. This is new in 2.3. Possible values (see the
1819 docs for details):
Tim Peters6ebe61f2003-06-27 20:48:05 +00001820
1821 DONT_ACCEPT_TRUE_FOR_1
Tim Peters8485b562004-08-04 18:46:34 +00001822 DONT_ACCEPT_BLANKLINE
Tim Peters8485b562004-08-04 18:46:34 +00001823 NORMALIZE_WHITESPACE
Tim Peters8485b562004-08-04 18:46:34 +00001824 ELLIPSIS
Thomas Wouters477c8d52006-05-27 19:21:47 +00001825 SKIP
Edward Loper052d0cd2004-09-19 17:19:33 +00001826 IGNORE_EXCEPTION_DETAIL
Edward Loper71f55af2004-08-26 01:41:51 +00001827 REPORT_UDIFF
1828 REPORT_CDIFF
1829 REPORT_NDIFF
Edward Lopera89f88d2004-08-26 02:45:51 +00001830 REPORT_ONLY_FIRST_FAILURE
Tim Peters19397e52004-08-06 22:02:59 +00001831
1832 Optional keyword arg "raise_on_error" raises an exception on the
1833 first unexpected exception or failure. This allows failures to be
1834 post-mortem debugged.
1835
Tim Peters8a7d2d52001-01-16 07:10:57 +00001836 Advanced tomfoolery: testmod runs methods of a local instance of
1837 class doctest.Tester, then merges the results into (or creates)
1838 global Tester instance doctest.master. Methods of doctest.master
1839 can be called directly too, if you want to do something unusual.
1840 Passing report=0 to testmod is especially useful then, to delay
1841 displaying a summary. Invoke doctest.master.summarize(verbose)
1842 when you're done fiddling.
1843 """
Tim Peters82076ef2004-09-13 00:52:51 +00001844 global master
1845
Tim Peters8485b562004-08-04 18:46:34 +00001846 # If no module was given, then use __main__.
Martin v. Löwis4581cfa2002-11-22 08:23:09 +00001847 if m is None:
Martin v. Löwis4581cfa2002-11-22 08:23:09 +00001848 # DWA - m will still be None if this wasn't invoked from the command
1849 # line, in which case the following TypeError is about as good an error
1850 # as we should expect
1851 m = sys.modules.get('__main__')
1852
Tim Peters8485b562004-08-04 18:46:34 +00001853 # Check that we were actually given a module.
1854 if not inspect.ismodule(m):
Walter Dörwald70a6b492004-02-12 17:35:32 +00001855 raise TypeError("testmod: module required; %r" % (m,))
Tim Peters8485b562004-08-04 18:46:34 +00001856
1857 # If no name was given, then use the module's name.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001858 if name is None:
1859 name = m.__name__
Tim Peters8485b562004-08-04 18:46:34 +00001860
1861 # Find, parse, and run all tests in the given module.
Thomas Wouters73e5a5b2006-06-08 15:35:45 +00001862 finder = DocTestFinder(exclude_empty=exclude_empty)
Tim Peters19397e52004-08-06 22:02:59 +00001863
1864 if raise_on_error:
1865 runner = DebugRunner(verbose=verbose, optionflags=optionflags)
1866 else:
1867 runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1868
Tim Peters8485b562004-08-04 18:46:34 +00001869 for test in finder.find(m, name, globs=globs, extraglobs=extraglobs):
1870 runner.run(test)
1871
Tim Peters8a7d2d52001-01-16 07:10:57 +00001872 if report:
Tim Peters8485b562004-08-04 18:46:34 +00001873 runner.summarize()
Tim Peters8a7d2d52001-01-16 07:10:57 +00001874
Tim Peters82076ef2004-09-13 00:52:51 +00001875 if master is None:
1876 master = runner
1877 else:
1878 master.merge(runner)
1879
Christian Heimes25bb7832008-01-11 16:17:00 +00001880 return TestResults(runner.failures, runner.tries)
Tim Petersdb3756d2003-06-29 05:30:48 +00001881
Edward Loper052d0cd2004-09-19 17:19:33 +00001882def testfile(filename, module_relative=True, name=None, package=None,
1883 globs=None, verbose=None, report=True, optionflags=0,
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00001884 extraglobs=None, raise_on_error=False, parser=DocTestParser(),
1885 encoding=None):
Edward Loper052d0cd2004-09-19 17:19:33 +00001886 """
1887 Test examples in the given file. Return (#failures, #tests).
1888
1889 Optional keyword arg "module_relative" specifies how filenames
1890 should be interpreted:
1891
1892 - If "module_relative" is True (the default), then "filename"
1893 specifies a module-relative path. By default, this path is
1894 relative to the calling module's directory; but if the
1895 "package" argument is specified, then it is relative to that
1896 package. To ensure os-independence, "filename" should use
1897 "/" characters to separate path segments, and should not
1898 be an absolute path (i.e., it may not begin with "/").
1899
1900 - If "module_relative" is False, then "filename" specifies an
1901 os-specific path. The path may be absolute or relative (to
1902 the current working directory).
1903
Edward Lopera2fc7ec2004-09-21 03:24:24 +00001904 Optional keyword arg "name" gives the name of the test; by default
1905 use the file's basename.
Edward Loper052d0cd2004-09-19 17:19:33 +00001906
1907 Optional keyword argument "package" is a Python package or the
1908 name of a Python package whose directory should be used as the
1909 base directory for a module relative filename. If no package is
1910 specified, then the calling module's directory is used as the base
1911 directory for module relative filenames. It is an error to
1912 specify "package" if "module_relative" is False.
1913
1914 Optional keyword arg "globs" gives a dict to be used as the globals
1915 when executing examples; by default, use {}. A copy of this dict
1916 is actually used for each docstring, so that each docstring's
1917 examples start with a clean slate.
1918
1919 Optional keyword arg "extraglobs" gives a dictionary that should be
1920 merged into the globals that are used to execute examples. By
1921 default, no extra globals are used.
1922
1923 Optional keyword arg "verbose" prints lots of stuff if true, prints
1924 only failures if false; by default, it's true iff "-v" is in sys.argv.
1925
1926 Optional keyword arg "report" prints a summary at the end when true,
1927 else prints nothing at the end. In verbose mode, the summary is
1928 detailed, else very brief (in fact, empty if all tests passed).
1929
1930 Optional keyword arg "optionflags" or's together module constants,
1931 and defaults to 0. Possible values (see the docs for details):
1932
1933 DONT_ACCEPT_TRUE_FOR_1
1934 DONT_ACCEPT_BLANKLINE
1935 NORMALIZE_WHITESPACE
1936 ELLIPSIS
Thomas Wouters477c8d52006-05-27 19:21:47 +00001937 SKIP
Edward Loper052d0cd2004-09-19 17:19:33 +00001938 IGNORE_EXCEPTION_DETAIL
1939 REPORT_UDIFF
1940 REPORT_CDIFF
1941 REPORT_NDIFF
1942 REPORT_ONLY_FIRST_FAILURE
1943
1944 Optional keyword arg "raise_on_error" raises an exception on the
1945 first unexpected exception or failure. This allows failures to be
1946 post-mortem debugged.
1947
Edward Loper498a1862004-09-27 03:42:58 +00001948 Optional keyword arg "parser" specifies a DocTestParser (or
1949 subclass) that should be used to extract tests from the files.
1950
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00001951 Optional keyword arg "encoding" specifies an encoding that should
1952 be used to convert the file to unicode.
1953
Edward Loper052d0cd2004-09-19 17:19:33 +00001954 Advanced tomfoolery: testmod runs methods of a local instance of
1955 class doctest.Tester, then merges the results into (or creates)
1956 global Tester instance doctest.master. Methods of doctest.master
1957 can be called directly too, if you want to do something unusual.
1958 Passing report=0 to testmod is especially useful then, to delay
1959 displaying a summary. Invoke doctest.master.summarize(verbose)
1960 when you're done fiddling.
1961 """
1962 global master
1963
1964 if package and not module_relative:
1965 raise ValueError("Package may only be specified for module-"
1966 "relative paths.")
Tim Petersbab3e992004-09-20 19:52:34 +00001967
Edward Loper052d0cd2004-09-19 17:19:33 +00001968 # Relativize the path
Guido van Rossum1b81e7b2007-08-29 03:53:53 +00001969 text, filename = _load_testfile(filename, package, module_relative,
1970 encoding or "utf-8")
Edward Loper052d0cd2004-09-19 17:19:33 +00001971
1972 # If no name was given, then use the file's name.
1973 if name is None:
Edward Lopera2fc7ec2004-09-21 03:24:24 +00001974 name = os.path.basename(filename)
Edward Loper052d0cd2004-09-19 17:19:33 +00001975
1976 # Assemble the globals.
1977 if globs is None:
1978 globs = {}
1979 else:
1980 globs = globs.copy()
1981 if extraglobs is not None:
1982 globs.update(extraglobs)
Raymond Hettinger0f055172009-01-27 10:06:09 +00001983 if '__name__' not in globs:
1984 globs['__name__'] = '__main__'
Edward Loper052d0cd2004-09-19 17:19:33 +00001985
1986 if raise_on_error:
1987 runner = DebugRunner(verbose=verbose, optionflags=optionflags)
1988 else:
1989 runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1990
1991 # Read the file, convert it to a test, and run it.
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00001992 test = parser.get_doctest(text, globs, name, filename, 0)
Edward Loper052d0cd2004-09-19 17:19:33 +00001993 runner.run(test)
1994
1995 if report:
1996 runner.summarize()
1997
1998 if master is None:
1999 master = runner
2000 else:
2001 master.merge(runner)
2002
Christian Heimes25bb7832008-01-11 16:17:00 +00002003 return TestResults(runner.failures, runner.tries)
Edward Loper052d0cd2004-09-19 17:19:33 +00002004
Tim Peters8485b562004-08-04 18:46:34 +00002005def run_docstring_examples(f, globs, verbose=False, name="NoName",
2006 compileflags=None, optionflags=0):
2007 """
2008 Test examples in the given object's docstring (`f`), using `globs`
2009 as globals. Optional argument `name` is used in failure messages.
2010 If the optional argument `verbose` is true, then generate output
2011 even if there are no failures.
Tim Petersdb3756d2003-06-29 05:30:48 +00002012
Tim Peters8485b562004-08-04 18:46:34 +00002013 `compileflags` gives the set of flags that should be used by the
2014 Python compiler when running the examples. If not specified, then
2015 it will default to the set of future-import flags that apply to
2016 `globs`.
Tim Petersdb3756d2003-06-29 05:30:48 +00002017
Tim Peters8485b562004-08-04 18:46:34 +00002018 Optional keyword arg `optionflags` specifies options for the
2019 testing and output. See the documentation for `testmod` for more
2020 information.
2021 """
2022 # Find, parse, and run all tests in the given module.
2023 finder = DocTestFinder(verbose=verbose, recurse=False)
2024 runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
2025 for test in finder.find(f, name, globs=globs):
2026 runner.run(test, compileflags=compileflags)
Tim Petersdb3756d2003-06-29 05:30:48 +00002027
Tim Peters8485b562004-08-04 18:46:34 +00002028######################################################################
Georg Brandl31835852008-05-12 17:38:56 +00002029## 7. Unittest Support
Tim Peters8485b562004-08-04 18:46:34 +00002030######################################################################
Tim Petersdb3756d2003-06-29 05:30:48 +00002031
Jim Fultonf54bad42004-08-28 14:57:56 +00002032_unittest_reportflags = 0
Tim Peters38330fe2004-08-30 16:19:24 +00002033
Jim Fultonf54bad42004-08-28 14:57:56 +00002034def set_unittest_reportflags(flags):
Tim Peters38330fe2004-08-30 16:19:24 +00002035 """Sets the unittest option flags.
Jim Fultonf54bad42004-08-28 14:57:56 +00002036
2037 The old flag is returned so that a runner could restore the old
2038 value if it wished to:
2039
Tim Petersb7e99b62005-03-28 23:50:54 +00002040 >>> import doctest
2041 >>> old = doctest._unittest_reportflags
2042 >>> doctest.set_unittest_reportflags(REPORT_NDIFF |
Jim Fultonf54bad42004-08-28 14:57:56 +00002043 ... REPORT_ONLY_FIRST_FAILURE) == old
2044 True
2045
Jim Fultonf54bad42004-08-28 14:57:56 +00002046 >>> doctest._unittest_reportflags == (REPORT_NDIFF |
2047 ... REPORT_ONLY_FIRST_FAILURE)
2048 True
Tim Petersdf7a2082004-08-29 00:38:17 +00002049
Jim Fultonf54bad42004-08-28 14:57:56 +00002050 Only reporting flags can be set:
2051
Tim Petersb7e99b62005-03-28 23:50:54 +00002052 >>> doctest.set_unittest_reportflags(ELLIPSIS)
Jim Fultonf54bad42004-08-28 14:57:56 +00002053 Traceback (most recent call last):
2054 ...
Tim Peters38330fe2004-08-30 16:19:24 +00002055 ValueError: ('Only reporting flags allowed', 8)
Jim Fultonf54bad42004-08-28 14:57:56 +00002056
Tim Petersb7e99b62005-03-28 23:50:54 +00002057 >>> doctest.set_unittest_reportflags(old) == (REPORT_NDIFF |
Jim Fultonf54bad42004-08-28 14:57:56 +00002058 ... REPORT_ONLY_FIRST_FAILURE)
2059 True
Jim Fultonf54bad42004-08-28 14:57:56 +00002060 """
Jim Fultonf54bad42004-08-28 14:57:56 +00002061 global _unittest_reportflags
Tim Peters38330fe2004-08-30 16:19:24 +00002062
2063 if (flags & REPORTING_FLAGS) != flags:
2064 raise ValueError("Only reporting flags allowed", flags)
Jim Fultonf54bad42004-08-28 14:57:56 +00002065 old = _unittest_reportflags
2066 _unittest_reportflags = flags
2067 return old
Tim Petersdf7a2082004-08-29 00:38:17 +00002068
Jim Fultonf54bad42004-08-28 14:57:56 +00002069
Tim Peters19397e52004-08-06 22:02:59 +00002070class DocTestCase(unittest.TestCase):
Tim Petersdb3756d2003-06-29 05:30:48 +00002071
Edward Loper34fcb142004-08-09 02:45:41 +00002072 def __init__(self, test, optionflags=0, setUp=None, tearDown=None,
2073 checker=None):
Jim Fulton07a349c2004-08-22 14:10:00 +00002074
Jim Fultona643b652004-07-14 19:06:50 +00002075 unittest.TestCase.__init__(self)
Tim Peters19397e52004-08-06 22:02:59 +00002076 self._dt_optionflags = optionflags
Edward Loper34fcb142004-08-09 02:45:41 +00002077 self._dt_checker = checker
Tim Peters19397e52004-08-06 22:02:59 +00002078 self._dt_test = test
2079 self._dt_setUp = setUp
2080 self._dt_tearDown = tearDown
Tim Petersdb3756d2003-06-29 05:30:48 +00002081
Jim Fultona643b652004-07-14 19:06:50 +00002082 def setUp(self):
Jim Fultonf54bad42004-08-28 14:57:56 +00002083 test = self._dt_test
Tim Petersdf7a2082004-08-29 00:38:17 +00002084
Tim Peters19397e52004-08-06 22:02:59 +00002085 if self._dt_setUp is not None:
Jim Fultonf54bad42004-08-28 14:57:56 +00002086 self._dt_setUp(test)
Jim Fultona643b652004-07-14 19:06:50 +00002087
2088 def tearDown(self):
Jim Fultonf54bad42004-08-28 14:57:56 +00002089 test = self._dt_test
2090
Tim Peters19397e52004-08-06 22:02:59 +00002091 if self._dt_tearDown is not None:
Jim Fultonf54bad42004-08-28 14:57:56 +00002092 self._dt_tearDown(test)
2093
2094 test.globs.clear()
Jim Fultona643b652004-07-14 19:06:50 +00002095
2096 def runTest(self):
Tim Peters19397e52004-08-06 22:02:59 +00002097 test = self._dt_test
Jim Fultona643b652004-07-14 19:06:50 +00002098 old = sys.stdout
2099 new = StringIO()
Jim Fultonf54bad42004-08-28 14:57:56 +00002100 optionflags = self._dt_optionflags
Tim Petersdf7a2082004-08-29 00:38:17 +00002101
Tim Peters38330fe2004-08-30 16:19:24 +00002102 if not (optionflags & REPORTING_FLAGS):
Jim Fultonf54bad42004-08-28 14:57:56 +00002103 # The option flags don't include any reporting flags,
2104 # so add the default reporting flags
2105 optionflags |= _unittest_reportflags
Tim Petersdf7a2082004-08-29 00:38:17 +00002106
Jim Fultonf54bad42004-08-28 14:57:56 +00002107 runner = DocTestRunner(optionflags=optionflags,
Edward Loper34fcb142004-08-09 02:45:41 +00002108 checker=self._dt_checker, verbose=False)
Tim Peters19397e52004-08-06 22:02:59 +00002109
Jim Fultona643b652004-07-14 19:06:50 +00002110 try:
Tim Peters19397e52004-08-06 22:02:59 +00002111 runner.DIVIDER = "-"*70
Jim Fultonf54bad42004-08-28 14:57:56 +00002112 failures, tries = runner.run(
2113 test, out=new.write, clear_globs=False)
Jim Fultona643b652004-07-14 19:06:50 +00002114 finally:
2115 sys.stdout = old
2116
2117 if failures:
Tim Peters19397e52004-08-06 22:02:59 +00002118 raise self.failureException(self.format_failure(new.getvalue()))
Tim Peters8485b562004-08-04 18:46:34 +00002119
Tim Peters19397e52004-08-06 22:02:59 +00002120 def format_failure(self, err):
2121 test = self._dt_test
2122 if test.lineno is None:
2123 lineno = 'unknown line number'
2124 else:
Jim Fulton07a349c2004-08-22 14:10:00 +00002125 lineno = '%s' % test.lineno
Tim Peters19397e52004-08-06 22:02:59 +00002126 lname = '.'.join(test.name.split('.')[-1:])
2127 return ('Failed doctest test for %s\n'
2128 ' File "%s", line %s, in %s\n\n%s'
2129 % (test.name, test.filename, lineno, lname, err)
2130 )
2131
2132 def debug(self):
2133 r"""Run the test case without results and without catching exceptions
2134
2135 The unit test framework includes a debug method on test cases
2136 and test suites to support post-mortem debugging. The test code
2137 is run in such a way that errors are not caught. This way a
2138 caller can catch the errors and initiate post-mortem debugging.
2139
2140 The DocTestCase provides a debug method that raises
Ezio Melotti13925002011-03-16 11:05:33 +02002141 UnexpectedException errors if there is an unexpected
Tim Peters19397e52004-08-06 22:02:59 +00002142 exception:
2143
Edward Lopera1ef6112004-08-09 16:14:41 +00002144 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
Tim Peters19397e52004-08-06 22:02:59 +00002145 ... {}, 'foo', 'foo.py', 0)
2146 >>> case = DocTestCase(test)
2147 >>> try:
2148 ... case.debug()
Guido van Rossumb940e112007-01-10 16:19:56 +00002149 ... except UnexpectedException as f:
2150 ... failure = f
Tim Peters19397e52004-08-06 22:02:59 +00002151
2152 The UnexpectedException contains the test, the example, and
2153 the original exception:
2154
2155 >>> failure.test is test
2156 True
2157
2158 >>> failure.example.want
2159 '42\n'
2160
2161 >>> exc_info = failure.exc_info
Collin Winter828f04a2007-08-31 00:04:24 +00002162 >>> raise exc_info[1] # Already has the traceback
Tim Peters19397e52004-08-06 22:02:59 +00002163 Traceback (most recent call last):
2164 ...
2165 KeyError
2166
2167 If the output doesn't match, then a DocTestFailure is raised:
2168
Edward Lopera1ef6112004-08-09 16:14:41 +00002169 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00002170 ... >>> x = 1
2171 ... >>> x
2172 ... 2
2173 ... ''', {}, 'foo', 'foo.py', 0)
2174 >>> case = DocTestCase(test)
2175
2176 >>> try:
2177 ... case.debug()
Guido van Rossumb940e112007-01-10 16:19:56 +00002178 ... except DocTestFailure as f:
2179 ... failure = f
Tim Peters19397e52004-08-06 22:02:59 +00002180
2181 DocTestFailure objects provide access to the test:
2182
2183 >>> failure.test is test
2184 True
2185
2186 As well as to the example:
2187
2188 >>> failure.example.want
2189 '2\n'
2190
2191 and the actual output:
2192
2193 >>> failure.got
2194 '1\n'
2195
2196 """
2197
Jim Fultonf54bad42004-08-28 14:57:56 +00002198 self.setUp()
Edward Loper34fcb142004-08-09 02:45:41 +00002199 runner = DebugRunner(optionflags=self._dt_optionflags,
2200 checker=self._dt_checker, verbose=False)
Alexandre Vassalottieca20b62008-05-16 02:54:33 +00002201 runner.run(self._dt_test, clear_globs=False)
Jim Fultonf54bad42004-08-28 14:57:56 +00002202 self.tearDown()
Jim Fultona643b652004-07-14 19:06:50 +00002203
2204 def id(self):
Tim Peters19397e52004-08-06 22:02:59 +00002205 return self._dt_test.name
Jim Fultona643b652004-07-14 19:06:50 +00002206
2207 def __repr__(self):
Tim Peters19397e52004-08-06 22:02:59 +00002208 name = self._dt_test.name.split('.')
Jim Fultona643b652004-07-14 19:06:50 +00002209 return "%s (%s)" % (name[-1], '.'.join(name[:-1]))
2210
2211 __str__ = __repr__
2212
2213 def shortDescription(self):
Tim Peters19397e52004-08-06 22:02:59 +00002214 return "Doctest: " + self._dt_test.name
Jim Fultona643b652004-07-14 19:06:50 +00002215
R. David Murray378c0cf2010-02-24 01:46:21 +00002216class SkipDocTestCase(DocTestCase):
2217 def __init__(self):
2218 DocTestCase.__init__(self, None)
2219
2220 def setUp(self):
2221 self.skipTest("DocTestSuite will not work with -O2 and above")
2222
2223 def test_skip(self):
2224 pass
2225
2226 def shortDescription(self):
2227 return "Skipping tests from %s" % module.__name__
2228
Jim Fultonf54bad42004-08-28 14:57:56 +00002229def DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None,
2230 **options):
Tim Peters8485b562004-08-04 18:46:34 +00002231 """
Tim Peters75dc5e12004-08-22 17:50:45 +00002232 Convert doctest tests for a module to a unittest test suite.
Jim Fultona643b652004-07-14 19:06:50 +00002233
Tim Peters19397e52004-08-06 22:02:59 +00002234 This converts each documentation string in a module that
2235 contains doctest tests to a unittest test case. If any of the
2236 tests in a doc string fail, then the test case fails. An exception
2237 is raised showing the name of the file containing the test and a
Jim Fultona643b652004-07-14 19:06:50 +00002238 (sometimes approximate) line number.
2239
Tim Peters19397e52004-08-06 22:02:59 +00002240 The `module` argument provides the module to be tested. The argument
Jim Fultona643b652004-07-14 19:06:50 +00002241 can be either a module or a module name.
2242
2243 If no argument is given, the calling module is used.
Jim Fultonf54bad42004-08-28 14:57:56 +00002244
2245 A number of options may be provided as keyword arguments:
2246
Jim Fultonf54bad42004-08-28 14:57:56 +00002247 setUp
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002248 A set-up function. This is called before running the
Jim Fultonf54bad42004-08-28 14:57:56 +00002249 tests in each file. The setUp function will be passed a DocTest
2250 object. The setUp function can access the test globals as the
2251 globs attribute of the test passed.
2252
2253 tearDown
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002254 A tear-down function. This is called after running the
Jim Fultonf54bad42004-08-28 14:57:56 +00002255 tests in each file. The tearDown function will be passed a DocTest
2256 object. The tearDown function can access the test globals as the
2257 globs attribute of the test passed.
2258
2259 globs
2260 A dictionary containing initial global variables for the tests.
2261
2262 optionflags
2263 A set of doctest option flags expressed as an integer.
Jim Fultona643b652004-07-14 19:06:50 +00002264 """
Jim Fultona643b652004-07-14 19:06:50 +00002265
Tim Peters8485b562004-08-04 18:46:34 +00002266 if test_finder is None:
2267 test_finder = DocTestFinder()
Tim Peters8485b562004-08-04 18:46:34 +00002268
Tim Peters19397e52004-08-06 22:02:59 +00002269 module = _normalize_module(module)
2270 tests = test_finder.find(module, globs=globs, extraglobs=extraglobs)
R. David Murray378c0cf2010-02-24 01:46:21 +00002271
2272 if not tests and sys.flags.optimize >=2:
2273 # Skip doctests when running with -O2
2274 suite = unittest.TestSuite()
2275 suite.addTest(SkipDocTestCase())
2276 return suite
2277 elif not tests:
Jim Fultonf54bad42004-08-28 14:57:56 +00002278 # Why do we want to do this? Because it reveals a bug that might
2279 # otherwise be hidden.
Tim Peters19397e52004-08-06 22:02:59 +00002280 raise ValueError(module, "has no tests")
Tim Petersdb3756d2003-06-29 05:30:48 +00002281
2282 tests.sort()
2283 suite = unittest.TestSuite()
R. David Murray378c0cf2010-02-24 01:46:21 +00002284
Tim Peters8485b562004-08-04 18:46:34 +00002285 for test in tests:
Tim Peters19397e52004-08-06 22:02:59 +00002286 if len(test.examples) == 0:
2287 continue
Tim Peters8485b562004-08-04 18:46:34 +00002288 if not test.filename:
Tim Petersdb3756d2003-06-29 05:30:48 +00002289 filename = module.__file__
Jim Fulton07a349c2004-08-22 14:10:00 +00002290 if filename[-4:] in (".pyc", ".pyo"):
Tim Petersdb3756d2003-06-29 05:30:48 +00002291 filename = filename[:-1]
Tim Peters8485b562004-08-04 18:46:34 +00002292 test.filename = filename
Jim Fultonf54bad42004-08-28 14:57:56 +00002293 suite.addTest(DocTestCase(test, **options))
Tim Peters19397e52004-08-06 22:02:59 +00002294
2295 return suite
2296
2297class DocFileCase(DocTestCase):
2298
2299 def id(self):
2300 return '_'.join(self._dt_test.name.split('.'))
2301
2302 def __repr__(self):
2303 return self._dt_test.filename
2304 __str__ = __repr__
2305
2306 def format_failure(self, err):
2307 return ('Failed doctest test for %s\n File "%s", line 0\n\n%s'
2308 % (self._dt_test.name, self._dt_test.filename, err)
2309 )
2310
Edward Loper052d0cd2004-09-19 17:19:33 +00002311def DocFileTest(path, module_relative=True, package=None,
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00002312 globs=None, parser=DocTestParser(),
2313 encoding=None, **options):
Tim Peters19397e52004-08-06 22:02:59 +00002314 if globs is None:
2315 globs = {}
Fred Drake7c404a42004-12-21 23:46:34 +00002316 else:
2317 globs = globs.copy()
Tim Peters19397e52004-08-06 22:02:59 +00002318
Edward Loper052d0cd2004-09-19 17:19:33 +00002319 if package and not module_relative:
2320 raise ValueError("Package may only be specified for module-"
2321 "relative paths.")
Tim Petersbab3e992004-09-20 19:52:34 +00002322
Edward Loper052d0cd2004-09-19 17:19:33 +00002323 # Relativize the path.
Guido van Rossum1b81e7b2007-08-29 03:53:53 +00002324 doc, path = _load_testfile(path, package, module_relative,
2325 encoding or "utf-8")
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00002326
Fred Drake7c404a42004-12-21 23:46:34 +00002327 if "__file__" not in globs:
2328 globs["__file__"] = path
Tim Peters19397e52004-08-06 22:02:59 +00002329
Edward Loper052d0cd2004-09-19 17:19:33 +00002330 # Find the file and read it.
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002331 name = os.path.basename(path)
Edward Loper052d0cd2004-09-19 17:19:33 +00002332
2333 # Convert it to a test, and wrap it in a DocFileCase.
Edward Loper498a1862004-09-27 03:42:58 +00002334 test = parser.get_doctest(doc, globs, name, path, 0)
Jim Fultonf54bad42004-08-28 14:57:56 +00002335 return DocFileCase(test, **options)
Tim Peters19397e52004-08-06 22:02:59 +00002336
2337def DocFileSuite(*paths, **kw):
Edward Loper052d0cd2004-09-19 17:19:33 +00002338 """A unittest suite for one or more doctest files.
Tim Petersbab3e992004-09-20 19:52:34 +00002339
Edward Loper052d0cd2004-09-19 17:19:33 +00002340 The path to each doctest file is given as a string; the
2341 interpretation of that string depends on the keyword argument
2342 "module_relative".
Tim Peters19397e52004-08-06 22:02:59 +00002343
2344 A number of options may be provided as keyword arguments:
2345
Edward Loper052d0cd2004-09-19 17:19:33 +00002346 module_relative
2347 If "module_relative" is True, then the given file paths are
2348 interpreted as os-independent module-relative paths. By
2349 default, these paths are relative to the calling module's
2350 directory; but if the "package" argument is specified, then
2351 they are relative to that package. To ensure os-independence,
2352 "filename" should use "/" characters to separate path
2353 segments, and may not be an absolute path (i.e., it may not
2354 begin with "/").
Tim Petersbab3e992004-09-20 19:52:34 +00002355
Edward Loper052d0cd2004-09-19 17:19:33 +00002356 If "module_relative" is False, then the given file paths are
2357 interpreted as os-specific paths. These paths may be absolute
2358 or relative (to the current working directory).
2359
Tim Peters19397e52004-08-06 22:02:59 +00002360 package
Edward Loper052d0cd2004-09-19 17:19:33 +00002361 A Python package or the name of a Python package whose directory
2362 should be used as the base directory for module relative paths.
2363 If "package" is not specified, then the calling module's
2364 directory is used as the base directory for module relative
2365 filenames. It is an error to specify "package" if
2366 "module_relative" is False.
Tim Peters19397e52004-08-06 22:02:59 +00002367
2368 setUp
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002369 A set-up function. This is called before running the
Jim Fultonf54bad42004-08-28 14:57:56 +00002370 tests in each file. The setUp function will be passed a DocTest
2371 object. The setUp function can access the test globals as the
2372 globs attribute of the test passed.
Tim Peters19397e52004-08-06 22:02:59 +00002373
2374 tearDown
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002375 A tear-down function. This is called after running the
Jim Fultonf54bad42004-08-28 14:57:56 +00002376 tests in each file. The tearDown function will be passed a DocTest
2377 object. The tearDown function can access the test globals as the
2378 globs attribute of the test passed.
Tim Peters19397e52004-08-06 22:02:59 +00002379
2380 globs
2381 A dictionary containing initial global variables for the tests.
Jim Fultonf54bad42004-08-28 14:57:56 +00002382
2383 optionflags
Edward Loper498a1862004-09-27 03:42:58 +00002384 A set of doctest option flags expressed as an integer.
2385
2386 parser
2387 A DocTestParser (or subclass) that should be used to extract
2388 tests from the files.
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00002389
2390 encoding
2391 An encoding that will be used to convert the files to unicode.
Tim Peters19397e52004-08-06 22:02:59 +00002392 """
2393 suite = unittest.TestSuite()
2394
2395 # We do this here so that _normalize_module is called at the right
2396 # level. If it were called in DocFileTest, then this function
2397 # would be the caller and we might guess the package incorrectly.
Edward Loper052d0cd2004-09-19 17:19:33 +00002398 if kw.get('module_relative', True):
2399 kw['package'] = _normalize_module(kw.get('package'))
Tim Peters19397e52004-08-06 22:02:59 +00002400
2401 for path in paths:
2402 suite.addTest(DocFileTest(path, **kw))
Jim Fultona643b652004-07-14 19:06:50 +00002403
Tim Petersdb3756d2003-06-29 05:30:48 +00002404 return suite
2405
Tim Peters8485b562004-08-04 18:46:34 +00002406######################################################################
Georg Brandl31835852008-05-12 17:38:56 +00002407## 8. Debugging Support
Tim Peters8485b562004-08-04 18:46:34 +00002408######################################################################
Jim Fultona643b652004-07-14 19:06:50 +00002409
Tim Peters19397e52004-08-06 22:02:59 +00002410def script_from_examples(s):
2411 r"""Extract script from text with examples.
2412
2413 Converts text with examples to a Python script. Example input is
2414 converted to regular code. Example output and all other words
2415 are converted to comments:
2416
2417 >>> text = '''
2418 ... Here are examples of simple math.
2419 ...
2420 ... Python has super accurate integer addition
2421 ...
2422 ... >>> 2 + 2
2423 ... 5
2424 ...
2425 ... And very friendly error messages:
2426 ...
2427 ... >>> 1/0
2428 ... To Infinity
2429 ... And
2430 ... Beyond
2431 ...
2432 ... You can use logic if you want:
2433 ...
2434 ... >>> if 0:
2435 ... ... blah
2436 ... ... blah
2437 ... ...
2438 ...
2439 ... Ho hum
2440 ... '''
2441
Guido van Rossum7131f842007-02-09 20:13:25 +00002442 >>> print(script_from_examples(text))
Edward Lopera5db6002004-08-12 02:41:30 +00002443 # Here are examples of simple math.
Tim Peters19397e52004-08-06 22:02:59 +00002444 #
Edward Lopera5db6002004-08-12 02:41:30 +00002445 # Python has super accurate integer addition
Tim Peters19397e52004-08-06 22:02:59 +00002446 #
2447 2 + 2
2448 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +00002449 ## 5
Tim Peters19397e52004-08-06 22:02:59 +00002450 #
Edward Lopera5db6002004-08-12 02:41:30 +00002451 # And very friendly error messages:
Tim Peters19397e52004-08-06 22:02:59 +00002452 #
2453 1/0
2454 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +00002455 ## To Infinity
2456 ## And
2457 ## Beyond
Tim Peters19397e52004-08-06 22:02:59 +00002458 #
Edward Lopera5db6002004-08-12 02:41:30 +00002459 # You can use logic if you want:
Tim Peters19397e52004-08-06 22:02:59 +00002460 #
2461 if 0:
2462 blah
2463 blah
Tim Peters19397e52004-08-06 22:02:59 +00002464 #
Edward Lopera5db6002004-08-12 02:41:30 +00002465 # Ho hum
Georg Brandlecf93c72005-06-26 23:09:51 +00002466 <BLANKLINE>
Tim Peters19397e52004-08-06 22:02:59 +00002467 """
Edward Loper00f8da72004-08-26 18:05:07 +00002468 output = []
2469 for piece in DocTestParser().parse(s):
2470 if isinstance(piece, Example):
2471 # Add the example's source code (strip trailing NL)
2472 output.append(piece.source[:-1])
2473 # Add the expected output:
2474 want = piece.want
2475 if want:
2476 output.append('# Expected:')
2477 output += ['## '+l for l in want.split('\n')[:-1]]
2478 else:
2479 # Add non-example text.
2480 output += [_comment_line(l)
2481 for l in piece.split('\n')[:-1]]
Tim Peters19397e52004-08-06 22:02:59 +00002482
Edward Loper00f8da72004-08-26 18:05:07 +00002483 # Trim junk on both ends.
2484 while output and output[-1] == '#':
2485 output.pop()
2486 while output and output[0] == '#':
2487 output.pop(0)
2488 # Combine the output, and return it.
Georg Brandl1f149642005-06-26 22:22:31 +00002489 # Add a courtesy newline to prevent exec from choking (see bug #1172785)
2490 return '\n'.join(output) + '\n'
Tim Petersdb3756d2003-06-29 05:30:48 +00002491
2492def testsource(module, name):
Tim Peters19397e52004-08-06 22:02:59 +00002493 """Extract the test sources from a doctest docstring as a script.
Tim Petersdb3756d2003-06-29 05:30:48 +00002494
2495 Provide the module (or dotted name of the module) containing the
Jim Fultona643b652004-07-14 19:06:50 +00002496 test to be debugged and the name (within the module) of the object
2497 with the doc string with tests to be debugged.
Tim Petersdb3756d2003-06-29 05:30:48 +00002498 """
Tim Peters8485b562004-08-04 18:46:34 +00002499 module = _normalize_module(module)
2500 tests = DocTestFinder().find(module)
2501 test = [t for t in tests if t.name == name]
Tim Petersdb3756d2003-06-29 05:30:48 +00002502 if not test:
2503 raise ValueError(name, "not found in tests")
2504 test = test[0]
Tim Peters19397e52004-08-06 22:02:59 +00002505 testsrc = script_from_examples(test.docstring)
Jim Fultona643b652004-07-14 19:06:50 +00002506 return testsrc
Tim Petersdb3756d2003-06-29 05:30:48 +00002507
Jim Fultona643b652004-07-14 19:06:50 +00002508def debug_src(src, pm=False, globs=None):
Tim Peters19397e52004-08-06 22:02:59 +00002509 """Debug a single doctest docstring, in argument `src`'"""
2510 testsrc = script_from_examples(src)
Tim Peters8485b562004-08-04 18:46:34 +00002511 debug_script(testsrc, pm, globs)
Tim Petersdb3756d2003-06-29 05:30:48 +00002512
Jim Fultona643b652004-07-14 19:06:50 +00002513def debug_script(src, pm=False, globs=None):
Tim Peters19397e52004-08-06 22:02:59 +00002514 "Debug a test script. `src` is the script, as a string."
Tim Petersdb3756d2003-06-29 05:30:48 +00002515 import pdb
Tim Petersdb3756d2003-06-29 05:30:48 +00002516
Victor Stinner12b8d142011-06-30 17:35:55 +02002517 if globs:
2518 globs = globs.copy()
2519 else:
2520 globs = {}
Tim Peters8485b562004-08-04 18:46:34 +00002521
Victor Stinner12b8d142011-06-30 17:35:55 +02002522 if pm:
2523 try:
2524 exec(src, globs, globs)
2525 except:
2526 print(sys.exc_info()[1])
2527 p = pdb.Pdb(nosigint=True)
2528 p.reset()
2529 p.interaction(None, sys.exc_info()[2])
2530 else:
2531 pdb.Pdb(nosigint=True).run("exec(%r)" % src, globs, globs)
Tim Petersdb3756d2003-06-29 05:30:48 +00002532
Jim Fultona643b652004-07-14 19:06:50 +00002533def debug(module, name, pm=False):
Tim Peters19397e52004-08-06 22:02:59 +00002534 """Debug a single doctest docstring.
Jim Fultona643b652004-07-14 19:06:50 +00002535
2536 Provide the module (or dotted name of the module) containing the
2537 test to be debugged and the name (within the module) of the object
Tim Peters19397e52004-08-06 22:02:59 +00002538 with the docstring with tests to be debugged.
Jim Fultona643b652004-07-14 19:06:50 +00002539 """
Tim Peters8485b562004-08-04 18:46:34 +00002540 module = _normalize_module(module)
Jim Fultona643b652004-07-14 19:06:50 +00002541 testsrc = testsource(module, name)
2542 debug_script(testsrc, pm, module.__dict__)
2543
Tim Peters8485b562004-08-04 18:46:34 +00002544######################################################################
Georg Brandl31835852008-05-12 17:38:56 +00002545## 9. Example Usage
Tim Peters8485b562004-08-04 18:46:34 +00002546######################################################################
Tim Peters8a7d2d52001-01-16 07:10:57 +00002547class _TestClass:
2548 """
2549 A pointless class, for sanity-checking of docstring testing.
2550
2551 Methods:
2552 square()
2553 get()
2554
2555 >>> _TestClass(13).get() + _TestClass(-12).get()
2556 1
2557 >>> hex(_TestClass(13).square().get())
2558 '0xa9'
2559 """
2560
2561 def __init__(self, val):
2562 """val -> _TestClass object with associated value val.
2563
2564 >>> t = _TestClass(123)
Guido van Rossum7131f842007-02-09 20:13:25 +00002565 >>> print(t.get())
Tim Peters8a7d2d52001-01-16 07:10:57 +00002566 123
2567 """
2568
2569 self.val = val
2570
2571 def square(self):
2572 """square() -> square TestClass's associated value
2573
2574 >>> _TestClass(13).square().get()
2575 169
2576 """
2577
2578 self.val = self.val ** 2
2579 return self
2580
2581 def get(self):
2582 """get() -> return TestClass's associated value.
2583
2584 >>> x = _TestClass(-42)
Guido van Rossum7131f842007-02-09 20:13:25 +00002585 >>> print(x.get())
Tim Peters8a7d2d52001-01-16 07:10:57 +00002586 -42
2587 """
2588
2589 return self.val
2590
2591__test__ = {"_TestClass": _TestClass,
2592 "string": r"""
2593 Example of a string object, searched as-is.
2594 >>> x = 1; y = 2
2595 >>> x + y, x * y
2596 (3, 2)
Tim Peters6ebe61f2003-06-27 20:48:05 +00002597 """,
Tim Peters3fa8c202004-08-23 21:43:39 +00002598
Tim Peters6ebe61f2003-06-27 20:48:05 +00002599 "bool-int equivalence": r"""
2600 In 2.2, boolean expressions displayed
2601 0 or 1. By default, we still accept
2602 them. This can be disabled by passing
2603 DONT_ACCEPT_TRUE_FOR_1 to the new
2604 optionflags argument.
2605 >>> 4 == 4
2606 1
2607 >>> 4 == 4
2608 True
2609 >>> 4 > 4
2610 0
2611 >>> 4 > 4
2612 False
2613 """,
Tim Peters3fa8c202004-08-23 21:43:39 +00002614
Tim Peters8485b562004-08-04 18:46:34 +00002615 "blank lines": r"""
Tim Peters3fa8c202004-08-23 21:43:39 +00002616 Blank lines can be marked with <BLANKLINE>:
Guido van Rossum7131f842007-02-09 20:13:25 +00002617 >>> print('foo\n\nbar\n')
Tim Peters3fa8c202004-08-23 21:43:39 +00002618 foo
2619 <BLANKLINE>
2620 bar
2621 <BLANKLINE>
Tim Peters8485b562004-08-04 18:46:34 +00002622 """,
Tim Peters3fa8c202004-08-23 21:43:39 +00002623
2624 "ellipsis": r"""
2625 If the ellipsis flag is used, then '...' can be used to
2626 elide substrings in the desired output:
Guido van Rossum805365e2007-05-07 22:24:25 +00002627 >>> print(list(range(1000))) #doctest: +ELLIPSIS
Tim Peters3fa8c202004-08-23 21:43:39 +00002628 [0, 1, 2, ..., 999]
2629 """,
2630
2631 "whitespace normalization": r"""
2632 If the whitespace normalization flag is used, then
2633 differences in whitespace are ignored.
Guido van Rossum805365e2007-05-07 22:24:25 +00002634 >>> print(list(range(30))) #doctest: +NORMALIZE_WHITESPACE
Tim Peters3fa8c202004-08-23 21:43:39 +00002635 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
2636 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,
2637 27, 28, 29]
2638 """,
2639 }
Tim Peters8485b562004-08-04 18:46:34 +00002640
R. David Murray445448c2009-12-20 17:28:31 +00002641
Tim Peters8a7d2d52001-01-16 07:10:57 +00002642def _test():
Guido van Rossumd8faa362007-04-27 19:54:29 +00002643 testfiles = [arg for arg in sys.argv[1:] if arg and arg[0] != '-']
R. David Murray445448c2009-12-20 17:28:31 +00002644 if not testfiles:
2645 name = os.path.basename(sys.argv[0])
R. David Murray0f72d6c2009-12-21 12:50:02 +00002646 if '__loader__' in globals(): # python -m
R. David Murray445448c2009-12-20 17:28:31 +00002647 name, _ = os.path.splitext(name)
2648 print("usage: {0} [-v] file ...".format(name))
2649 return 2
2650 for filename in testfiles:
2651 if filename.endswith(".py"):
2652 # It is a module -- insert its dir into sys.path and try to
2653 # import it. If it is part of a package, that possibly
2654 # won't work because of package imports.
2655 dirname, filename = os.path.split(filename)
2656 sys.path.insert(0, dirname)
2657 m = __import__(filename[:-3])
2658 del sys.path[0]
2659 failures, _ = testmod(m)
2660 else:
2661 failures, _ = testfile(filename, module_relative=False)
2662 if failures:
2663 return 1
Christian Heimes895627f2007-12-08 17:28:33 +00002664 return 0
Tim Peters8a7d2d52001-01-16 07:10:57 +00002665
R. David Murray445448c2009-12-20 17:28:31 +00002666
Tim Peters8a7d2d52001-01-16 07:10:57 +00002667if __name__ == "__main__":
Christian Heimes895627f2007-12-08 17:28:33 +00002668 sys.exit(_test())