blob: b5fa574a3ed27e2b659861290c6453ef91cdbef7 [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',
Edward Loperb7503ff2004-08-19 19:19:03 +000083 # 7. Tester
Tim Peters4fd9e2f2001-08-18 00:05:50 +000084 'Tester',
Edward Loperb7503ff2004-08-19 19:19:03 +000085 # 8. Unittest Support
Tim Petersdb3756d2003-06-29 05:30:48 +000086 'DocTestSuite',
Edward Loperb7503ff2004-08-19 19:19:03 +000087 'DocFileSuite',
Tim Peters9d02a7c2004-09-26 01:50:24 +000088 'set_unittest_reportflags',
Edward Loperb7503ff2004-08-19 19:19:03 +000089 # 9. Debugging Support
90 'script_from_examples',
Tim Petersdb3756d2003-06-29 05:30:48 +000091 'testsource',
Edward Loperb7503ff2004-08-19 19:19:03 +000092 'debug_src',
Tim Petersdb3756d2003-06-29 05:30:48 +000093 'debug',
Tim Peters4fd9e2f2001-08-18 00:05:50 +000094]
Tim Peters8a7d2d52001-01-16 07:10:57 +000095
Tim Peters4fd9e2f2001-08-18 00:05:50 +000096import __future__
Tim Peters8a7d2d52001-01-16 07:10:57 +000097
Thomas Wouters0e3f5912006-08-11 14:57:12 +000098import sys, traceback, inspect, linecache, os, re
Jim Fulton356fd192004-08-09 11:34:47 +000099import unittest, difflib, pdb, tempfile
Tim Petersf727c6c2004-08-08 01:48:59 +0000100import warnings
Guido van Rossum34d19282007-08-09 01:03:29 +0000101from io import StringIO
Christian Heimes25bb7832008-01-11 16:17:00 +0000102from collections import namedtuple
103
104TestResults = namedtuple('TestResults', 'failed attempted')
Tim Peters7402f792001-10-02 03:53:41 +0000105
Tim Peters19397e52004-08-06 22:02:59 +0000106# There are 4 basic classes:
107# - Example: a <source, want> pair, plus an intra-docstring line number.
108# - DocTest: a collection of examples, parsed from a docstring, plus
109# info about where the docstring came from (name, filename, lineno).
110# - DocTestFinder: extracts DocTests from a given object's docstring and
111# its contained objects' docstrings.
112# - DocTestRunner: runs DocTest cases, and accumulates statistics.
113#
114# So the basic picture is:
115#
116# list of:
117# +------+ +---------+ +-------+
118# |object| --DocTestFinder-> | DocTest | --DocTestRunner-> |results|
119# +------+ +---------+ +-------+
120# | Example |
121# | ... |
122# | Example |
123# +---------+
124
Edward Loperac20f572004-08-12 02:02:24 +0000125# Option constants.
Tim Peters38330fe2004-08-30 16:19:24 +0000126
Edward Loperac20f572004-08-12 02:02:24 +0000127OPTIONFLAGS_BY_NAME = {}
128def register_optionflag(name):
Thomas Wouters477c8d52006-05-27 19:21:47 +0000129 # Create a new flag unless `name` is already known.
130 return OPTIONFLAGS_BY_NAME.setdefault(name, 1 << len(OPTIONFLAGS_BY_NAME))
Edward Loperac20f572004-08-12 02:02:24 +0000131
132DONT_ACCEPT_TRUE_FOR_1 = register_optionflag('DONT_ACCEPT_TRUE_FOR_1')
133DONT_ACCEPT_BLANKLINE = register_optionflag('DONT_ACCEPT_BLANKLINE')
134NORMALIZE_WHITESPACE = register_optionflag('NORMALIZE_WHITESPACE')
135ELLIPSIS = register_optionflag('ELLIPSIS')
Thomas Wouters477c8d52006-05-27 19:21:47 +0000136SKIP = register_optionflag('SKIP')
Tim Peters1fbf9c52004-09-04 17:21:02 +0000137IGNORE_EXCEPTION_DETAIL = register_optionflag('IGNORE_EXCEPTION_DETAIL')
Tim Peters38330fe2004-08-30 16:19:24 +0000138
139COMPARISON_FLAGS = (DONT_ACCEPT_TRUE_FOR_1 |
140 DONT_ACCEPT_BLANKLINE |
141 NORMALIZE_WHITESPACE |
Tim Peters1fbf9c52004-09-04 17:21:02 +0000142 ELLIPSIS |
Thomas Wouters477c8d52006-05-27 19:21:47 +0000143 SKIP |
Edward Loper7d88a582004-09-28 05:50:57 +0000144 IGNORE_EXCEPTION_DETAIL)
Tim Peters38330fe2004-08-30 16:19:24 +0000145
Edward Loper71f55af2004-08-26 01:41:51 +0000146REPORT_UDIFF = register_optionflag('REPORT_UDIFF')
147REPORT_CDIFF = register_optionflag('REPORT_CDIFF')
148REPORT_NDIFF = register_optionflag('REPORT_NDIFF')
Edward Lopera89f88d2004-08-26 02:45:51 +0000149REPORT_ONLY_FIRST_FAILURE = register_optionflag('REPORT_ONLY_FIRST_FAILURE')
Edward Loperac20f572004-08-12 02:02:24 +0000150
Tim Peters38330fe2004-08-30 16:19:24 +0000151REPORTING_FLAGS = (REPORT_UDIFF |
152 REPORT_CDIFF |
153 REPORT_NDIFF |
154 REPORT_ONLY_FIRST_FAILURE)
155
Edward Loperac20f572004-08-12 02:02:24 +0000156# Special string markers for use in `want` strings:
157BLANKLINE_MARKER = '<BLANKLINE>'
158ELLIPSIS_MARKER = '...'
159
Tim Peters8485b562004-08-04 18:46:34 +0000160######################################################################
161## Table of Contents
162######################################################################
Edward Loper7c748462004-08-09 02:06:06 +0000163# 1. Utility Functions
164# 2. Example & DocTest -- store test cases
165# 3. DocTest Parser -- extracts examples from strings
166# 4. DocTest Finder -- extracts test cases from objects
167# 5. DocTest Runner -- runs test cases
168# 6. Test Functions -- convenient wrappers for testing
169# 7. Tester Class -- for backwards compatibility
170# 8. Unittest Support
171# 9. Debugging Support
172# 10. Example Usage
Tim Peters8a7d2d52001-01-16 07:10:57 +0000173
Tim Peters8485b562004-08-04 18:46:34 +0000174######################################################################
175## 1. Utility Functions
176######################################################################
Tim Peters8a7d2d52001-01-16 07:10:57 +0000177
Tim Peters8485b562004-08-04 18:46:34 +0000178def _extract_future_flags(globs):
179 """
180 Return the compiler-flags associated with the future features that
181 have been imported into the given namespace (globs).
182 """
183 flags = 0
184 for fname in __future__.all_feature_names:
185 feature = globs.get(fname, None)
186 if feature is getattr(__future__, fname):
187 flags |= feature.compiler_flag
188 return flags
Tim Peters7402f792001-10-02 03:53:41 +0000189
Tim Peters8485b562004-08-04 18:46:34 +0000190def _normalize_module(module, depth=2):
191 """
192 Return the module specified by `module`. In particular:
193 - If `module` is a module, then return module.
194 - If `module` is a string, then import and return the
195 module with that name.
196 - If `module` is None, then return the calling module.
197 The calling module is assumed to be the module of
198 the stack frame at the given depth in the call stack.
199 """
200 if inspect.ismodule(module):
201 return module
Walter Dörwaldaa97f042007-05-03 21:05:51 +0000202 elif isinstance(module, str):
Tim Peters8485b562004-08-04 18:46:34 +0000203 return __import__(module, globals(), locals(), ["*"])
204 elif module is None:
205 return sys.modules[sys._getframe(depth).f_globals['__name__']]
206 else:
207 raise TypeError("Expected a module, string, or None")
Tim Peters7402f792001-10-02 03:53:41 +0000208
Guido van Rossum1b81e7b2007-08-29 03:53:53 +0000209def _load_testfile(filename, package, module_relative, encoding):
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000210 if module_relative:
211 package = _normalize_module(package, 3)
212 filename = _module_relative_path(package, filename)
213 if hasattr(package, '__loader__'):
214 if hasattr(package.__loader__, 'get_data'):
Guido van Rossumcd4d4522007-11-22 00:30:02 +0000215 file_contents = package.__loader__.get_data(filename)
216 file_contents = file_contents.decode(encoding)
217 # get_data() opens files as 'rb', so one must do the equivalent
218 # conversion as universal newlines would do.
219 return file_contents.replace(os.linesep, '\n'), filename
Guido van Rossum1b81e7b2007-08-29 03:53:53 +0000220 return open(filename, encoding=encoding).read(), filename
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000221
Edward Loperaacf0832004-08-26 01:19:50 +0000222def _indent(s, indent=4):
Tim Peters8485b562004-08-04 18:46:34 +0000223 """
Edward Loperaacf0832004-08-26 01:19:50 +0000224 Add the given number of space characters to the beginning every
225 non-blank line in `s`, and return the result.
Tim Peters8485b562004-08-04 18:46:34 +0000226 """
Edward Loperaacf0832004-08-26 01:19:50 +0000227 # This regexp matches the start of non-blank lines:
228 return re.sub('(?m)^(?!$)', indent*' ', s)
Tim Peters8a7d2d52001-01-16 07:10:57 +0000229
Edward Loper8e4a34b2004-08-12 02:34:27 +0000230def _exception_traceback(exc_info):
231 """
232 Return a string containing a traceback message for the given
233 exc_info tuple (as returned by sys.exc_info()).
234 """
235 # Get a traceback message.
236 excout = StringIO()
237 exc_type, exc_val, exc_tb = exc_info
238 traceback.print_exception(exc_type, exc_val, exc_tb, file=excout)
239 return excout.getvalue()
240
Tim Peters8485b562004-08-04 18:46:34 +0000241# Override some StringIO methods.
242class _SpoofOut(StringIO):
243 def getvalue(self):
244 result = StringIO.getvalue(self)
245 # If anything at all was written, make sure there's a trailing
246 # newline. There's no way for the expected output to indicate
247 # that a trailing newline is missing.
248 if result and not result.endswith("\n"):
249 result += "\n"
Tim Peters8485b562004-08-04 18:46:34 +0000250 return result
Tim Peters8a7d2d52001-01-16 07:10:57 +0000251
Guido van Rossum79139b22007-02-09 23:20:19 +0000252 def truncate(self, size=None):
Tim Peters8485b562004-08-04 18:46:34 +0000253 StringIO.truncate(self, size)
Tim Peters8a7d2d52001-01-16 07:10:57 +0000254
Tim Peters26b3ebb2004-08-19 08:10:08 +0000255# Worst-case linear-time ellipsis matching.
Tim Petersb0a04e12004-08-20 02:08:04 +0000256def _ellipsis_match(want, got):
Tim Petersdc5de3b2004-08-19 14:06:20 +0000257 """
258 Essentially the only subtle case:
Tim Petersb0a04e12004-08-20 02:08:04 +0000259 >>> _ellipsis_match('aa...aa', 'aaa')
Tim Petersdc5de3b2004-08-19 14:06:20 +0000260 False
261 """
Tim Peters26b3ebb2004-08-19 08:10:08 +0000262 if ELLIPSIS_MARKER not in want:
263 return want == got
Tim Petersdc5de3b2004-08-19 14:06:20 +0000264
Tim Peters26b3ebb2004-08-19 08:10:08 +0000265 # Find "the real" strings.
266 ws = want.split(ELLIPSIS_MARKER)
267 assert len(ws) >= 2
Tim Peters26b3ebb2004-08-19 08:10:08 +0000268
Tim Petersdc5de3b2004-08-19 14:06:20 +0000269 # Deal with exact matches possibly needed at one or both ends.
270 startpos, endpos = 0, len(got)
271 w = ws[0]
272 if w: # starts with exact match
273 if got.startswith(w):
274 startpos = len(w)
275 del ws[0]
276 else:
277 return False
278 w = ws[-1]
279 if w: # ends with exact match
280 if got.endswith(w):
281 endpos -= len(w)
282 del ws[-1]
283 else:
284 return False
285
286 if startpos > endpos:
287 # Exact end matches required more characters than we have, as in
Tim Petersb0a04e12004-08-20 02:08:04 +0000288 # _ellipsis_match('aa...aa', 'aaa')
Tim Petersdc5de3b2004-08-19 14:06:20 +0000289 return False
290
291 # For the rest, we only need to find the leftmost non-overlapping
292 # match for each piece. If there's no overall match that way alone,
293 # there's no overall match period.
Tim Peters26b3ebb2004-08-19 08:10:08 +0000294 for w in ws:
295 # w may be '' at times, if there are consecutive ellipses, or
296 # due to an ellipsis at the start or end of `want`. That's OK.
Tim Petersdc5de3b2004-08-19 14:06:20 +0000297 # Search for an empty string succeeds, and doesn't change startpos.
298 startpos = got.find(w, startpos, endpos)
299 if startpos < 0:
Tim Peters26b3ebb2004-08-19 08:10:08 +0000300 return False
Tim Petersdc5de3b2004-08-19 14:06:20 +0000301 startpos += len(w)
Tim Peters26b3ebb2004-08-19 08:10:08 +0000302
Tim Petersdc5de3b2004-08-19 14:06:20 +0000303 return True
Tim Peters26b3ebb2004-08-19 08:10:08 +0000304
Edward Loper00f8da72004-08-26 18:05:07 +0000305def _comment_line(line):
306 "Return a commented form of the given line"
307 line = line.rstrip()
308 if line:
309 return '# '+line
310 else:
311 return '#'
312
Edward Loper2de91ba2004-08-27 02:07:46 +0000313class _OutputRedirectingPdb(pdb.Pdb):
314 """
315 A specialized version of the python debugger that redirects stdout
316 to a given stream when interacting with the user. Stdout is *not*
317 redirected when traced code is executed.
318 """
319 def __init__(self, out):
320 self.__out = out
Guido van Rossum0d3fb8a2007-11-26 23:23:18 +0000321 self.__debugger_used = False
Thomas Wouters477c8d52006-05-27 19:21:47 +0000322 pdb.Pdb.__init__(self, stdout=out)
Edward Loper2de91ba2004-08-27 02:07:46 +0000323
Guido van Rossum0d3fb8a2007-11-26 23:23:18 +0000324 def set_trace(self, frame=None):
325 self.__debugger_used = True
326 if frame is None:
327 frame = sys._getframe().f_back
328 pdb.Pdb.set_trace(self, frame)
329
330 def set_continue(self):
331 # Calling set_continue unconditionally would break unit test
332 # coverage reporting, as Bdb.set_continue calls sys.settrace(None).
333 if self.__debugger_used:
334 pdb.Pdb.set_continue(self)
335
Edward Loper2de91ba2004-08-27 02:07:46 +0000336 def trace_dispatch(self, *args):
337 # Redirect stdout to the given stream.
338 save_stdout = sys.stdout
339 sys.stdout = self.__out
340 # Call Pdb's trace dispatch method.
Tim Petersd7bbbbc2004-11-08 22:30:28 +0000341 try:
342 return pdb.Pdb.trace_dispatch(self, *args)
343 finally:
Tim Petersd7bbbbc2004-11-08 22:30:28 +0000344 sys.stdout = save_stdout
Edward Loper2de91ba2004-08-27 02:07:46 +0000345
Edward Lopera2fc7ec2004-09-21 03:24:24 +0000346# [XX] Normalize with respect to os.path.pardir?
Edward Loper052d0cd2004-09-19 17:19:33 +0000347def _module_relative_path(module, path):
348 if not inspect.ismodule(module):
Collin Winterce36ad82007-08-30 01:19:48 +0000349 raise TypeError('Expected a module: %r' % module)
Edward Loper052d0cd2004-09-19 17:19:33 +0000350 if path.startswith('/'):
Collin Winterce36ad82007-08-30 01:19:48 +0000351 raise ValueError('Module-relative files may not have absolute paths')
Edward Loper052d0cd2004-09-19 17:19:33 +0000352
353 # Find the base directory for the path.
354 if hasattr(module, '__file__'):
355 # A normal module/package
356 basedir = os.path.split(module.__file__)[0]
357 elif module.__name__ == '__main__':
358 # An interactive session.
359 if len(sys.argv)>0 and sys.argv[0] != '':
360 basedir = os.path.split(sys.argv[0])[0]
361 else:
362 basedir = os.curdir
363 else:
364 # A module w/o __file__ (this includes builtins)
365 raise ValueError("Can't resolve paths relative to the module " +
366 module + " (it has no __file__)")
367
368 # Combine the base directory and the path.
369 return os.path.join(basedir, *(path.split('/')))
370
Tim Peters8485b562004-08-04 18:46:34 +0000371######################################################################
372## 2. Example & DocTest
373######################################################################
374## - An "example" is a <source, want> pair, where "source" is a
375## fragment of source code, and "want" is the expected output for
376## "source." The Example class also includes information about
377## where the example was extracted from.
378##
Edward Lopera1ef6112004-08-09 16:14:41 +0000379## - A "doctest" is a collection of examples, typically extracted from
380## a string (such as an object's docstring). The DocTest class also
381## includes information about where the string was extracted from.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000382
Tim Peters8485b562004-08-04 18:46:34 +0000383class Example:
384 """
385 A single doctest example, consisting of source code and expected
Edward Lopera1ef6112004-08-09 16:14:41 +0000386 output. `Example` defines the following attributes:
Tim Peters8a7d2d52001-01-16 07:10:57 +0000387
Edward Loper74bca7a2004-08-12 02:27:44 +0000388 - source: A single Python statement, always ending with a newline.
Tim Petersbb431472004-08-09 03:51:46 +0000389 The constructor adds a newline if needed.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000390
Edward Loper74bca7a2004-08-12 02:27:44 +0000391 - want: The expected output from running the source code (either
Tim Petersbb431472004-08-09 03:51:46 +0000392 from stdout, or a traceback in case of exception). `want` ends
393 with a newline unless it's empty, in which case it's an empty
394 string. The constructor adds a newline if needed.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000395
Edward Lopera6b68322004-08-26 00:05:43 +0000396 - exc_msg: The exception message generated by the example, if
397 the example is expected to generate an exception; or `None` if
398 it is not expected to generate an exception. This exception
399 message is compared against the return value of
400 `traceback.format_exception_only()`. `exc_msg` ends with a
401 newline unless it's `None`. The constructor adds a newline
402 if needed.
403
Edward Loper74bca7a2004-08-12 02:27:44 +0000404 - lineno: The line number within the DocTest string containing
Tim Peters8485b562004-08-04 18:46:34 +0000405 this Example where the Example begins. This line number is
406 zero-based, with respect to the beginning of the DocTest.
Edward Loper74bca7a2004-08-12 02:27:44 +0000407
408 - indent: The example's indentation in the DocTest string.
409 I.e., the number of space characters that preceed the
410 example's first prompt.
411
412 - options: A dictionary mapping from option flags to True or
413 False, which is used to override default options for this
414 example. Any option flags not contained in this dictionary
415 are left at their default value (as specified by the
416 DocTestRunner's optionflags). By default, no options are set.
Tim Peters8485b562004-08-04 18:46:34 +0000417 """
Edward Lopera6b68322004-08-26 00:05:43 +0000418 def __init__(self, source, want, exc_msg=None, lineno=0, indent=0,
419 options=None):
Tim Petersbb431472004-08-09 03:51:46 +0000420 # Normalize inputs.
421 if not source.endswith('\n'):
422 source += '\n'
423 if want and not want.endswith('\n'):
424 want += '\n'
Edward Lopera6b68322004-08-26 00:05:43 +0000425 if exc_msg is not None and not exc_msg.endswith('\n'):
426 exc_msg += '\n'
Tim Peters8485b562004-08-04 18:46:34 +0000427 # Store properties.
428 self.source = source
429 self.want = want
430 self.lineno = lineno
Edward Loper74bca7a2004-08-12 02:27:44 +0000431 self.indent = indent
432 if options is None: options = {}
433 self.options = options
Edward Lopera6b68322004-08-26 00:05:43 +0000434 self.exc_msg = exc_msg
Tim Peters8a7d2d52001-01-16 07:10:57 +0000435
Tim Peters8485b562004-08-04 18:46:34 +0000436class DocTest:
437 """
438 A collection of doctest examples that should be run in a single
Edward Lopera1ef6112004-08-09 16:14:41 +0000439 namespace. Each `DocTest` defines the following attributes:
Tim Peters8a7d2d52001-01-16 07:10:57 +0000440
Tim Peters8485b562004-08-04 18:46:34 +0000441 - examples: the list of examples.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000442
Tim Peters8485b562004-08-04 18:46:34 +0000443 - globs: The namespace (aka globals) that the examples should
444 be run in.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000445
Tim Peters8485b562004-08-04 18:46:34 +0000446 - name: A name identifying the DocTest (typically, the name of
447 the object whose docstring this DocTest was extracted from).
Tim Peters8a7d2d52001-01-16 07:10:57 +0000448
Tim Peters8485b562004-08-04 18:46:34 +0000449 - filename: The name of the file that this DocTest was extracted
Edward Lopera1ef6112004-08-09 16:14:41 +0000450 from, or `None` if the filename is unknown.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000451
Tim Peters8485b562004-08-04 18:46:34 +0000452 - lineno: The line number within filename where this DocTest
Edward Lopera1ef6112004-08-09 16:14:41 +0000453 begins, or `None` if the line number is unavailable. This
454 line number is zero-based, with respect to the beginning of
455 the file.
456
457 - docstring: The string that the examples were extracted from,
458 or `None` if the string is unavailable.
Tim Peters8485b562004-08-04 18:46:34 +0000459 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000460 def __init__(self, examples, globs, name, filename, lineno, docstring):
Tim Peters8485b562004-08-04 18:46:34 +0000461 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000462 Create a new DocTest containing the given examples. The
463 DocTest's globals are initialized with a copy of `globs`.
Tim Peters8485b562004-08-04 18:46:34 +0000464 """
Guido van Rossum3172c5d2007-10-16 18:12:55 +0000465 assert not isinstance(examples, str), \
Edward Lopera1ef6112004-08-09 16:14:41 +0000466 "DocTest no longer accepts str; use DocTestParser instead"
467 self.examples = examples
468 self.docstring = docstring
Tim Peters8485b562004-08-04 18:46:34 +0000469 self.globs = globs.copy()
Tim Peters8485b562004-08-04 18:46:34 +0000470 self.name = name
471 self.filename = filename
472 self.lineno = lineno
Tim Peters8485b562004-08-04 18:46:34 +0000473
474 def __repr__(self):
475 if len(self.examples) == 0:
476 examples = 'no examples'
477 elif len(self.examples) == 1:
478 examples = '1 example'
479 else:
480 examples = '%d examples' % len(self.examples)
481 return ('<DocTest %s from %s:%s (%s)>' %
482 (self.name, self.filename, self.lineno, examples))
483
484
485 # This lets us sort tests by name:
Guido van Rossum47b9ff62006-08-24 00:41:19 +0000486 def __lt__(self, other):
Tim Peters8485b562004-08-04 18:46:34 +0000487 if not isinstance(other, DocTest):
Guido van Rossum47b9ff62006-08-24 00:41:19 +0000488 return NotImplemented
489 return ((self.name, self.filename, self.lineno, id(self))
490 <
491 (other.name, other.filename, other.lineno, id(other)))
Tim Peters8485b562004-08-04 18:46:34 +0000492
493######################################################################
Edward Loperb7503ff2004-08-19 19:19:03 +0000494## 3. DocTestParser
Edward Loper7c748462004-08-09 02:06:06 +0000495######################################################################
496
Edward Lopera1ef6112004-08-09 16:14:41 +0000497class DocTestParser:
Edward Loper7c748462004-08-09 02:06:06 +0000498 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000499 A class used to parse strings containing doctest examples.
Edward Loper7c748462004-08-09 02:06:06 +0000500 """
Edward Loper8e4a34b2004-08-12 02:34:27 +0000501 # This regular expression is used to find doctest examples in a
502 # string. It defines three groups: `source` is the source code
503 # (including leading indentation and prompts); `indent` is the
504 # indentation of the first (PS1) line of the source code; and
505 # `want` is the expected output (including leading indentation).
Edward Loper7c748462004-08-09 02:06:06 +0000506 _EXAMPLE_RE = re.compile(r'''
Tim Petersd40a92b2004-08-09 03:28:45 +0000507 # Source consists of a PS1 line followed by zero or more PS2 lines.
508 (?P<source>
509 (?:^(?P<indent> [ ]*) >>> .*) # PS1 line
510 (?:\n [ ]* \.\.\. .*)*) # PS2 lines
511 \n?
512 # Want consists of any non-blank lines that do not start with PS1.
513 (?P<want> (?:(?![ ]*$) # Not a blank line
514 (?![ ]*>>>) # Not a line starting with PS1
515 .*$\n? # But any other line
516 )*)
517 ''', re.MULTILINE | re.VERBOSE)
Edward Loper8e4a34b2004-08-12 02:34:27 +0000518
Edward Lopera6b68322004-08-26 00:05:43 +0000519 # A regular expression for handling `want` strings that contain
520 # expected exceptions. It divides `want` into three pieces:
521 # - the traceback header line (`hdr`)
522 # - the traceback stack (`stack`)
523 # - the exception message (`msg`), as generated by
524 # traceback.format_exception_only()
525 # `msg` may have multiple lines. We assume/require that the
526 # exception message is the first non-indented line starting with a word
527 # character following the traceback header line.
528 _EXCEPTION_RE = re.compile(r"""
529 # Grab the traceback header. Different versions of Python have
530 # said different things on the first traceback line.
531 ^(?P<hdr> Traceback\ \(
532 (?: most\ recent\ call\ last
533 | innermost\ last
534 ) \) :
535 )
536 \s* $ # toss trailing whitespace on the header.
537 (?P<stack> .*?) # don't blink: absorb stuff until...
538 ^ (?P<msg> \w+ .*) # a line *starts* with alphanum.
539 """, re.VERBOSE | re.MULTILINE | re.DOTALL)
540
Tim Peters7ea48dd2004-08-13 01:52:59 +0000541 # A callable returning a true value iff its argument is a blank line
542 # or contains a single comment.
Edward Loper8e4a34b2004-08-12 02:34:27 +0000543 _IS_BLANK_OR_COMMENT = re.compile(r'^[ ]*(#.*)?$').match
Edward Loper7c748462004-08-09 02:06:06 +0000544
Edward Loper00f8da72004-08-26 18:05:07 +0000545 def parse(self, string, name='<string>'):
546 """
547 Divide the given string into examples and intervening text,
548 and return them as a list of alternating Examples and strings.
549 Line numbers for the Examples are 0-based. The optional
550 argument `name` is a name identifying this string, and is only
551 used for error messages.
552 """
553 string = string.expandtabs()
554 # If all lines begin with the same indentation, then strip it.
555 min_indent = self._min_indent(string)
556 if min_indent > 0:
557 string = '\n'.join([l[min_indent:] for l in string.split('\n')])
558
559 output = []
560 charno, lineno = 0, 0
561 # Find all doctest examples in the string:
Edward Loper2de91ba2004-08-27 02:07:46 +0000562 for m in self._EXAMPLE_RE.finditer(string):
Edward Loper00f8da72004-08-26 18:05:07 +0000563 # Add the pre-example text to `output`.
564 output.append(string[charno:m.start()])
565 # Update lineno (lines before this example)
566 lineno += string.count('\n', charno, m.start())
567 # Extract info from the regexp match.
568 (source, options, want, exc_msg) = \
569 self._parse_example(m, name, lineno)
570 # Create an Example, and add it to the list.
571 if not self._IS_BLANK_OR_COMMENT(source):
572 output.append( Example(source, want, exc_msg,
573 lineno=lineno,
574 indent=min_indent+len(m.group('indent')),
575 options=options) )
576 # Update lineno (lines inside this example)
577 lineno += string.count('\n', m.start(), m.end())
578 # Update charno.
579 charno = m.end()
580 # Add any remaining post-example text to `output`.
581 output.append(string[charno:])
582 return output
583
Edward Lopera1ef6112004-08-09 16:14:41 +0000584 def get_doctest(self, string, globs, name, filename, lineno):
Edward Loper7c748462004-08-09 02:06:06 +0000585 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000586 Extract all doctest examples from the given string, and
587 collect them into a `DocTest` object.
588
589 `globs`, `name`, `filename`, and `lineno` are attributes for
590 the new `DocTest` object. See the documentation for `DocTest`
591 for more information.
592 """
593 return DocTest(self.get_examples(string, name), globs,
594 name, filename, lineno, string)
595
596 def get_examples(self, string, name='<string>'):
597 """
598 Extract all doctest examples from the given string, and return
599 them as a list of `Example` objects. Line numbers are
600 0-based, because it's most common in doctests that nothing
601 interesting appears on the same line as opening triple-quote,
602 and so the first interesting line is called \"line 1\" then.
603
604 The optional argument `name` is a name identifying this
605 string, and is only used for error messages.
Edward Loper7c748462004-08-09 02:06:06 +0000606 """
Edward Loper00f8da72004-08-26 18:05:07 +0000607 return [x for x in self.parse(string, name)
608 if isinstance(x, Example)]
Edward Loper7c748462004-08-09 02:06:06 +0000609
Edward Loper74bca7a2004-08-12 02:27:44 +0000610 def _parse_example(self, m, name, lineno):
611 """
612 Given a regular expression match from `_EXAMPLE_RE` (`m`),
613 return a pair `(source, want)`, where `source` is the matched
614 example's source code (with prompts and indentation stripped);
615 and `want` is the example's expected output (with indentation
616 stripped).
617
618 `name` is the string's name, and `lineno` is the line number
619 where the example starts; both are used for error messages.
620 """
Edward Loper7c748462004-08-09 02:06:06 +0000621 # Get the example's indentation level.
622 indent = len(m.group('indent'))
623
624 # Divide source into lines; check that they're properly
625 # indented; and then strip their indentation & prompts.
626 source_lines = m.group('source').split('\n')
Edward Lopera1ef6112004-08-09 16:14:41 +0000627 self._check_prompt_blank(source_lines, indent, name, lineno)
Tim Petersc5049152004-08-22 17:34:58 +0000628 self._check_prefix(source_lines[1:], ' '*indent + '.', name, lineno)
Edward Loper7c748462004-08-09 02:06:06 +0000629 source = '\n'.join([sl[indent+4:] for sl in source_lines])
Edward Loper7c748462004-08-09 02:06:06 +0000630
Tim Petersc5049152004-08-22 17:34:58 +0000631 # Divide want into lines; check that it's properly indented; and
632 # then strip the indentation. Spaces before the last newline should
633 # be preserved, so plain rstrip() isn't good enough.
Jim Fulton07a349c2004-08-22 14:10:00 +0000634 want = m.group('want')
Jim Fulton07a349c2004-08-22 14:10:00 +0000635 want_lines = want.split('\n')
Tim Petersc5049152004-08-22 17:34:58 +0000636 if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]):
637 del want_lines[-1] # forget final newline & spaces after it
Edward Lopera1ef6112004-08-09 16:14:41 +0000638 self._check_prefix(want_lines, ' '*indent, name,
Tim Petersc5049152004-08-22 17:34:58 +0000639 lineno + len(source_lines))
Edward Loper7c748462004-08-09 02:06:06 +0000640 want = '\n'.join([wl[indent:] for wl in want_lines])
Edward Loper7c748462004-08-09 02:06:06 +0000641
Edward Lopera6b68322004-08-26 00:05:43 +0000642 # If `want` contains a traceback message, then extract it.
643 m = self._EXCEPTION_RE.match(want)
644 if m:
645 exc_msg = m.group('msg')
646 else:
647 exc_msg = None
648
Edward Loper00f8da72004-08-26 18:05:07 +0000649 # Extract options from the source.
650 options = self._find_options(source, name, lineno)
651
652 return source, options, want, exc_msg
Edward Loper7c748462004-08-09 02:06:06 +0000653
Edward Loper74bca7a2004-08-12 02:27:44 +0000654 # This regular expression looks for option directives in the
655 # source code of an example. Option directives are comments
656 # starting with "doctest:". Warning: this may give false
657 # positives for string-literals that contain the string
658 # "#doctest:". Eliminating these false positives would require
659 # actually parsing the string; but we limit them by ignoring any
660 # line containing "#doctest:" that is *followed* by a quote mark.
661 _OPTION_DIRECTIVE_RE = re.compile(r'#\s*doctest:\s*([^\n\'"]*)$',
662 re.MULTILINE)
663
664 def _find_options(self, source, name, lineno):
665 """
666 Return a dictionary containing option overrides extracted from
667 option directives in the given source string.
668
669 `name` is the string's name, and `lineno` is the line number
670 where the example starts; both are used for error messages.
671 """
672 options = {}
673 # (note: with the current regexp, this will match at most once:)
674 for m in self._OPTION_DIRECTIVE_RE.finditer(source):
675 option_strings = m.group(1).replace(',', ' ').split()
676 for option in option_strings:
677 if (option[0] not in '+-' or
678 option[1:] not in OPTIONFLAGS_BY_NAME):
679 raise ValueError('line %r of the doctest for %s '
680 'has an invalid option: %r' %
681 (lineno+1, name, option))
682 flag = OPTIONFLAGS_BY_NAME[option[1:]]
683 options[flag] = (option[0] == '+')
684 if options and self._IS_BLANK_OR_COMMENT(source):
685 raise ValueError('line %r of the doctest for %s has an option '
686 'directive on a line with no example: %r' %
687 (lineno, name, source))
688 return options
689
Edward Lopera5db6002004-08-12 02:41:30 +0000690 # This regular expression finds the indentation of every non-blank
691 # line in a string.
Edward Loper00f8da72004-08-26 18:05:07 +0000692 _INDENT_RE = re.compile('^([ ]*)(?=\S)', re.MULTILINE)
Edward Lopera5db6002004-08-12 02:41:30 +0000693
694 def _min_indent(self, s):
695 "Return the minimum indentation of any non-blank line in `s`"
Edward Loper00f8da72004-08-26 18:05:07 +0000696 indents = [len(indent) for indent in self._INDENT_RE.findall(s)]
697 if len(indents) > 0:
698 return min(indents)
Tim Petersdd0e4752004-08-09 03:31:56 +0000699 else:
Edward Loper00f8da72004-08-26 18:05:07 +0000700 return 0
Edward Loper7c748462004-08-09 02:06:06 +0000701
Edward Lopera1ef6112004-08-09 16:14:41 +0000702 def _check_prompt_blank(self, lines, indent, name, lineno):
Edward Loper74bca7a2004-08-12 02:27:44 +0000703 """
704 Given the lines of a source string (including prompts and
705 leading indentation), check to make sure that every prompt is
706 followed by a space character. If any line is not followed by
707 a space character, then raise ValueError.
708 """
Edward Loper7c748462004-08-09 02:06:06 +0000709 for i, line in enumerate(lines):
710 if len(line) >= indent+4 and line[indent+3] != ' ':
711 raise ValueError('line %r of the docstring for %s '
712 'lacks blank after %s: %r' %
Edward Lopera1ef6112004-08-09 16:14:41 +0000713 (lineno+i+1, name,
Edward Loper7c748462004-08-09 02:06:06 +0000714 line[indent:indent+3], line))
715
Edward Lopera1ef6112004-08-09 16:14:41 +0000716 def _check_prefix(self, lines, prefix, name, lineno):
Edward Loper74bca7a2004-08-12 02:27:44 +0000717 """
718 Check that every line in the given list starts with the given
719 prefix; if any line does not, then raise a ValueError.
720 """
Edward Loper7c748462004-08-09 02:06:06 +0000721 for i, line in enumerate(lines):
722 if line and not line.startswith(prefix):
723 raise ValueError('line %r of the docstring for %s has '
724 'inconsistent leading whitespace: %r' %
Edward Lopera1ef6112004-08-09 16:14:41 +0000725 (lineno+i+1, name, line))
Edward Loper7c748462004-08-09 02:06:06 +0000726
727
728######################################################################
729## 4. DocTest Finder
Tim Peters8485b562004-08-04 18:46:34 +0000730######################################################################
731
732class DocTestFinder:
733 """
734 A class used to extract the DocTests that are relevant to a given
735 object, from its docstring and the docstrings of its contained
736 objects. Doctests can currently be extracted from the following
737 object types: modules, functions, classes, methods, staticmethods,
738 classmethods, and properties.
Tim Peters8485b562004-08-04 18:46:34 +0000739 """
740
Edward Lopera1ef6112004-08-09 16:14:41 +0000741 def __init__(self, verbose=False, parser=DocTestParser(),
Thomas Wouters73e5a5b2006-06-08 15:35:45 +0000742 recurse=True, exclude_empty=True):
Tim Peters8485b562004-08-04 18:46:34 +0000743 """
744 Create a new doctest finder.
745
Edward Lopera1ef6112004-08-09 16:14:41 +0000746 The optional argument `parser` specifies a class or
Tim Peters19397e52004-08-06 22:02:59 +0000747 function that should be used to create new DocTest objects (or
Tim Peters161c9632004-08-08 03:38:33 +0000748 objects that implement the same interface as DocTest). The
Tim Peters19397e52004-08-06 22:02:59 +0000749 signature for this factory function should match the signature
750 of the DocTest constructor.
751
Tim Peters8485b562004-08-04 18:46:34 +0000752 If the optional argument `recurse` is false, then `find` will
753 only examine the given object, and not any contained objects.
Edward Loper32ddbf72004-09-13 05:47:24 +0000754
Tim Peters958cc892004-09-13 14:53:28 +0000755 If the optional argument `exclude_empty` is false, then `find`
756 will include tests for objects with empty docstrings.
Tim Peters8485b562004-08-04 18:46:34 +0000757 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000758 self._parser = parser
Tim Peters8485b562004-08-04 18:46:34 +0000759 self._verbose = verbose
Tim Peters8485b562004-08-04 18:46:34 +0000760 self._recurse = recurse
Edward Loper32ddbf72004-09-13 05:47:24 +0000761 self._exclude_empty = exclude_empty
Tim Peters8485b562004-08-04 18:46:34 +0000762
Thomas Wouters73e5a5b2006-06-08 15:35:45 +0000763 def find(self, obj, name=None, module=None, globs=None, extraglobs=None):
Tim Peters8485b562004-08-04 18:46:34 +0000764 """
765 Return a list of the DocTests that are defined by the given
766 object's docstring, or by any of its contained objects'
767 docstrings.
768
769 The optional parameter `module` is the module that contains
Tim Petersf3f57472004-08-08 06:11:48 +0000770 the given object. If the module is not specified or is None, then
771 the test finder will attempt to automatically determine the
Tim Peters8485b562004-08-04 18:46:34 +0000772 correct module. The object's module is used:
773
774 - As a default namespace, if `globs` is not specified.
775 - To prevent the DocTestFinder from extracting DocTests
Tim Petersf3f57472004-08-08 06:11:48 +0000776 from objects that are imported from other modules.
Tim Peters8485b562004-08-04 18:46:34 +0000777 - To find the name of the file containing the object.
778 - To help find the line number of the object within its
779 file.
780
Tim Petersf3f57472004-08-08 06:11:48 +0000781 Contained objects whose module does not match `module` are ignored.
782
783 If `module` is False, no attempt to find the module will be made.
784 This is obscure, of use mostly in tests: if `module` is False, or
785 is None but cannot be found automatically, then all objects are
786 considered to belong to the (non-existent) module, so all contained
787 objects will (recursively) be searched for doctests.
788
Tim Peters8485b562004-08-04 18:46:34 +0000789 The globals for each DocTest is formed by combining `globs`
790 and `extraglobs` (bindings in `extraglobs` override bindings
791 in `globs`). A new copy of the globals dictionary is created
792 for each DocTest. If `globs` is not specified, then it
793 defaults to the module's `__dict__`, if specified, or {}
794 otherwise. If `extraglobs` is not specified, then it defaults
795 to {}.
796
Tim Peters8485b562004-08-04 18:46:34 +0000797 """
798 # If name was not specified, then extract it from the object.
799 if name is None:
800 name = getattr(obj, '__name__', None)
801 if name is None:
802 raise ValueError("DocTestFinder.find: name must be given "
803 "when obj.__name__ doesn't exist: %r" %
804 (type(obj),))
805
806 # Find the module that contains the given object (if obj is
807 # a module, then module=obj.). Note: this may fail, in which
808 # case module will be None.
Tim Petersf3f57472004-08-08 06:11:48 +0000809 if module is False:
810 module = None
811 elif module is None:
Tim Peters8485b562004-08-04 18:46:34 +0000812 module = inspect.getmodule(obj)
813
814 # Read the module's source code. This is used by
815 # DocTestFinder._find_lineno to find the line number for a
816 # given object's docstring.
817 try:
818 file = inspect.getsourcefile(obj) or inspect.getfile(obj)
819 source_lines = linecache.getlines(file)
820 if not source_lines:
821 source_lines = None
822 except TypeError:
823 source_lines = None
824
825 # Initialize globals, and merge in extraglobs.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000826 if globs is None:
Tim Peters8485b562004-08-04 18:46:34 +0000827 if module is None:
828 globs = {}
829 else:
830 globs = module.__dict__.copy()
831 else:
832 globs = globs.copy()
833 if extraglobs is not None:
834 globs.update(extraglobs)
Tim Peters8a7d2d52001-01-16 07:10:57 +0000835
Tim Peters8485b562004-08-04 18:46:34 +0000836 # Recursively expore `obj`, extracting DocTests.
837 tests = []
Tim Petersf3f57472004-08-08 06:11:48 +0000838 self._find(tests, obj, name, module, source_lines, globs, {})
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000839 # Sort the tests by alpha order of names, for consistency in
840 # verbose-mode output. This was a feature of doctest in Pythons
841 # <= 2.3 that got lost by accident in 2.4. It was repaired in
842 # 2.4.4 and 2.5.
843 tests.sort()
Tim Peters8485b562004-08-04 18:46:34 +0000844 return tests
845
Tim Peters8485b562004-08-04 18:46:34 +0000846 def _from_module(self, module, object):
847 """
848 Return true if the given object is defined in the given
849 module.
850 """
851 if module is None:
852 return True
853 elif inspect.isfunction(object):
Neal Norwitz221085d2007-02-25 20:55:47 +0000854 return module.__dict__ is object.__globals__
Tim Peters8485b562004-08-04 18:46:34 +0000855 elif inspect.isclass(object):
856 return module.__name__ == object.__module__
857 elif inspect.getmodule(object) is not None:
858 return module is inspect.getmodule(object)
859 elif hasattr(object, '__module__'):
860 return module.__name__ == object.__module__
861 elif isinstance(object, property):
862 return True # [XX] no way not be sure.
863 else:
864 raise ValueError("object must be a class or function")
865
Tim Petersf3f57472004-08-08 06:11:48 +0000866 def _find(self, tests, obj, name, module, source_lines, globs, seen):
Tim Peters8485b562004-08-04 18:46:34 +0000867 """
868 Find tests for the given object and any contained objects, and
869 add them to `tests`.
870 """
871 if self._verbose:
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000872 print('Finding tests in %s' % name)
Tim Peters8485b562004-08-04 18:46:34 +0000873
874 # If we've already processed this object, then ignore it.
875 if id(obj) in seen:
876 return
877 seen[id(obj)] = 1
878
879 # Find a test for this object, and add it to the list of tests.
880 test = self._get_test(obj, name, module, globs, source_lines)
881 if test is not None:
882 tests.append(test)
883
884 # Look for tests in a module's contained objects.
885 if inspect.ismodule(obj) and self._recurse:
886 for valname, val in obj.__dict__.items():
Tim Peters8485b562004-08-04 18:46:34 +0000887 valname = '%s.%s' % (name, valname)
888 # Recurse to functions & classes.
889 if ((inspect.isfunction(val) or inspect.isclass(val)) and
Tim Petersf3f57472004-08-08 06:11:48 +0000890 self._from_module(module, val)):
Tim Peters8485b562004-08-04 18:46:34 +0000891 self._find(tests, val, valname, module, source_lines,
Tim Petersf3f57472004-08-08 06:11:48 +0000892 globs, seen)
Tim Peters8485b562004-08-04 18:46:34 +0000893
894 # Look for tests in a module's __test__ dictionary.
895 if inspect.ismodule(obj) and self._recurse:
896 for valname, val in getattr(obj, '__test__', {}).items():
Guido van Rossum3172c5d2007-10-16 18:12:55 +0000897 if not isinstance(valname, str):
Tim Peters8485b562004-08-04 18:46:34 +0000898 raise ValueError("DocTestFinder.find: __test__ keys "
899 "must be strings: %r" %
900 (type(valname),))
901 if not (inspect.isfunction(val) or inspect.isclass(val) or
902 inspect.ismethod(val) or inspect.ismodule(val) or
Guido van Rossum3172c5d2007-10-16 18:12:55 +0000903 isinstance(val, str)):
Tim Peters8485b562004-08-04 18:46:34 +0000904 raise ValueError("DocTestFinder.find: __test__ values "
905 "must be strings, functions, methods, "
906 "classes, or modules: %r" %
907 (type(val),))
Tim Petersc5684782004-09-13 01:07:12 +0000908 valname = '%s.__test__.%s' % (name, valname)
Tim Peters8485b562004-08-04 18:46:34 +0000909 self._find(tests, val, valname, module, source_lines,
Tim Petersf3f57472004-08-08 06:11:48 +0000910 globs, seen)
Tim Peters8485b562004-08-04 18:46:34 +0000911
912 # Look for tests in a class's contained objects.
913 if inspect.isclass(obj) and self._recurse:
914 for valname, val in obj.__dict__.items():
Tim Peters8485b562004-08-04 18:46:34 +0000915 # Special handling for staticmethod/classmethod.
916 if isinstance(val, staticmethod):
917 val = getattr(obj, valname)
918 if isinstance(val, classmethod):
Christian Heimesff737952007-11-27 10:40:20 +0000919 val = getattr(obj, valname).__func__
Tim Peters8485b562004-08-04 18:46:34 +0000920
921 # Recurse to methods, properties, and nested classes.
922 if ((inspect.isfunction(val) or inspect.isclass(val) or
Tim Petersf3f57472004-08-08 06:11:48 +0000923 isinstance(val, property)) and
924 self._from_module(module, val)):
Tim Peters8485b562004-08-04 18:46:34 +0000925 valname = '%s.%s' % (name, valname)
926 self._find(tests, val, valname, module, source_lines,
Tim Petersf3f57472004-08-08 06:11:48 +0000927 globs, seen)
Tim Peters8485b562004-08-04 18:46:34 +0000928
929 def _get_test(self, obj, name, module, globs, source_lines):
930 """
931 Return a DocTest for the given object, if it defines a docstring;
932 otherwise, return None.
933 """
934 # Extract the object's docstring. If it doesn't have one,
935 # then return None (no test for this object).
Guido van Rossum3172c5d2007-10-16 18:12:55 +0000936 if isinstance(obj, str):
Tim Peters8485b562004-08-04 18:46:34 +0000937 docstring = obj
938 else:
939 try:
940 if obj.__doc__ is None:
Edward Loper32ddbf72004-09-13 05:47:24 +0000941 docstring = ''
942 else:
Jim Fulton7d428782004-10-13 14:15:32 +0000943 docstring = obj.__doc__
Guido van Rossum3172c5d2007-10-16 18:12:55 +0000944 if not isinstance(docstring, str):
Jim Fulton7d428782004-10-13 14:15:32 +0000945 docstring = str(docstring)
Tim Peters8485b562004-08-04 18:46:34 +0000946 except (TypeError, AttributeError):
Edward Loper32ddbf72004-09-13 05:47:24 +0000947 docstring = ''
Tim Peters8485b562004-08-04 18:46:34 +0000948
949 # Find the docstring's location in the file.
950 lineno = self._find_lineno(obj, source_lines)
951
Edward Loper32ddbf72004-09-13 05:47:24 +0000952 # Don't bother if the docstring is empty.
953 if self._exclude_empty and not docstring:
954 return None
955
Tim Peters8485b562004-08-04 18:46:34 +0000956 # Return a DocTest for this object.
957 if module is None:
958 filename = None
959 else:
960 filename = getattr(module, '__file__', module.__name__)
Jim Fulton07a349c2004-08-22 14:10:00 +0000961 if filename[-4:] in (".pyc", ".pyo"):
962 filename = filename[:-1]
Edward Lopera1ef6112004-08-09 16:14:41 +0000963 return self._parser.get_doctest(docstring, globs, name,
964 filename, lineno)
Tim Peters8485b562004-08-04 18:46:34 +0000965
966 def _find_lineno(self, obj, source_lines):
967 """
968 Return a line number of the given object's docstring. Note:
969 this method assumes that the object has a docstring.
970 """
971 lineno = None
972
973 # Find the line number for modules.
974 if inspect.ismodule(obj):
975 lineno = 0
976
977 # Find the line number for classes.
978 # Note: this could be fooled if a class is defined multiple
979 # times in a single file.
980 if inspect.isclass(obj):
981 if source_lines is None:
982 return None
983 pat = re.compile(r'^\s*class\s*%s\b' %
984 getattr(obj, '__name__', '-'))
985 for i, line in enumerate(source_lines):
986 if pat.match(line):
987 lineno = i
988 break
989
990 # Find the line number for functions & methods.
Christian Heimesff737952007-11-27 10:40:20 +0000991 if inspect.ismethod(obj): obj = obj.__func__
Neal Norwitz221085d2007-02-25 20:55:47 +0000992 if inspect.isfunction(obj): obj = obj.__code__
Tim Peters8485b562004-08-04 18:46:34 +0000993 if inspect.istraceback(obj): obj = obj.tb_frame
994 if inspect.isframe(obj): obj = obj.f_code
995 if inspect.iscode(obj):
996 lineno = getattr(obj, 'co_firstlineno', None)-1
997
998 # Find the line number where the docstring starts. Assume
999 # that it's the first line that begins with a quote mark.
1000 # Note: this could be fooled by a multiline function
1001 # signature, where a continuation line begins with a quote
1002 # mark.
1003 if lineno is not None:
1004 if source_lines is None:
1005 return lineno+1
1006 pat = re.compile('(^|.*:)\s*\w*("|\')')
1007 for lineno in range(lineno, len(source_lines)):
1008 if pat.match(source_lines[lineno]):
1009 return lineno
1010
1011 # We couldn't find the line number.
1012 return None
1013
1014######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00001015## 5. DocTest Runner
Tim Peters8485b562004-08-04 18:46:34 +00001016######################################################################
1017
Tim Peters8485b562004-08-04 18:46:34 +00001018class DocTestRunner:
1019 """
1020 A class used to run DocTest test cases, and accumulate statistics.
1021 The `run` method is used to process a single DocTest case. It
1022 returns a tuple `(f, t)`, where `t` is the number of test cases
1023 tried, and `f` is the number of test cases that failed.
1024
1025 >>> tests = DocTestFinder().find(_TestClass)
1026 >>> runner = DocTestRunner(verbose=False)
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00001027 >>> tests.sort(key = lambda test: test.name)
Tim Peters8485b562004-08-04 18:46:34 +00001028 >>> for test in tests:
Guido van Rossum7131f842007-02-09 20:13:25 +00001029 ... print(test.name, '->', runner.run(test))
Christian Heimes25bb7832008-01-11 16:17:00 +00001030 _TestClass -> TestResults(failed=0, attempted=2)
1031 _TestClass.__init__ -> TestResults(failed=0, attempted=2)
1032 _TestClass.get -> TestResults(failed=0, attempted=2)
1033 _TestClass.square -> TestResults(failed=0, attempted=1)
Tim Peters8485b562004-08-04 18:46:34 +00001034
1035 The `summarize` method prints a summary of all the test cases that
1036 have been run by the runner, and returns an aggregated `(f, t)`
1037 tuple:
1038
1039 >>> runner.summarize(verbose=1)
1040 4 items passed all tests:
1041 2 tests in _TestClass
1042 2 tests in _TestClass.__init__
1043 2 tests in _TestClass.get
1044 1 tests in _TestClass.square
1045 7 tests in 4 items.
1046 7 passed and 0 failed.
1047 Test passed.
Christian Heimes25bb7832008-01-11 16:17:00 +00001048 TestResults(failed=0, attempted=7)
Tim Peters8485b562004-08-04 18:46:34 +00001049
1050 The aggregated number of tried examples and failed examples is
1051 also available via the `tries` and `failures` attributes:
1052
1053 >>> runner.tries
1054 7
1055 >>> runner.failures
1056 0
1057
1058 The comparison between expected outputs and actual outputs is done
Edward Loper34fcb142004-08-09 02:45:41 +00001059 by an `OutputChecker`. This comparison may be customized with a
1060 number of option flags; see the documentation for `testmod` for
1061 more information. If the option flags are insufficient, then the
1062 comparison may also be customized by passing a subclass of
1063 `OutputChecker` to the constructor.
Tim Peters8485b562004-08-04 18:46:34 +00001064
1065 The test runner's display output can be controlled in two ways.
1066 First, an output function (`out) can be passed to
1067 `TestRunner.run`; this function will be called with strings that
1068 should be displayed. It defaults to `sys.stdout.write`. If
1069 capturing the output is not sufficient, then the display output
1070 can be also customized by subclassing DocTestRunner, and
1071 overriding the methods `report_start`, `report_success`,
1072 `report_unexpected_exception`, and `report_failure`.
1073 """
1074 # This divider string is used to separate failure messages, and to
1075 # separate sections of the summary.
1076 DIVIDER = "*" * 70
1077
Edward Loper34fcb142004-08-09 02:45:41 +00001078 def __init__(self, checker=None, verbose=None, optionflags=0):
Tim Peters8485b562004-08-04 18:46:34 +00001079 """
1080 Create a new test runner.
1081
Edward Loper34fcb142004-08-09 02:45:41 +00001082 Optional keyword arg `checker` is the `OutputChecker` that
1083 should be used to compare the expected outputs and actual
1084 outputs of doctest examples.
1085
Tim Peters8485b562004-08-04 18:46:34 +00001086 Optional keyword arg 'verbose' prints lots of stuff if true,
1087 only failures if false; by default, it's true iff '-v' is in
1088 sys.argv.
1089
1090 Optional argument `optionflags` can be used to control how the
1091 test runner compares expected output to actual output, and how
1092 it displays failures. See the documentation for `testmod` for
1093 more information.
1094 """
Edward Loper34fcb142004-08-09 02:45:41 +00001095 self._checker = checker or OutputChecker()
Tim Peters8a7d2d52001-01-16 07:10:57 +00001096 if verbose is None:
Tim Peters8485b562004-08-04 18:46:34 +00001097 verbose = '-v' in sys.argv
1098 self._verbose = verbose
Tim Peters6ebe61f2003-06-27 20:48:05 +00001099 self.optionflags = optionflags
Jim Fulton07a349c2004-08-22 14:10:00 +00001100 self.original_optionflags = optionflags
Tim Peters6ebe61f2003-06-27 20:48:05 +00001101
Tim Peters8485b562004-08-04 18:46:34 +00001102 # Keep track of the examples we've run.
1103 self.tries = 0
1104 self.failures = 0
1105 self._name2ft = {}
Tim Peters8a7d2d52001-01-16 07:10:57 +00001106
Tim Peters8485b562004-08-04 18:46:34 +00001107 # Create a fake output target for capturing doctest output.
1108 self._fakeout = _SpoofOut()
Tim Peters4fd9e2f2001-08-18 00:05:50 +00001109
Tim Peters8485b562004-08-04 18:46:34 +00001110 #/////////////////////////////////////////////////////////////////
Tim Peters8485b562004-08-04 18:46:34 +00001111 # Reporting methods
1112 #/////////////////////////////////////////////////////////////////
Tim Peters17111f32001-10-03 04:08:26 +00001113
Tim Peters8485b562004-08-04 18:46:34 +00001114 def report_start(self, out, test, example):
Tim Peters8a7d2d52001-01-16 07:10:57 +00001115 """
Tim Peters8485b562004-08-04 18:46:34 +00001116 Report that the test runner is about to process the given
1117 example. (Only displays a message if verbose=True)
1118 """
1119 if self._verbose:
Edward Loperaacf0832004-08-26 01:19:50 +00001120 if example.want:
1121 out('Trying:\n' + _indent(example.source) +
1122 'Expecting:\n' + _indent(example.want))
1123 else:
1124 out('Trying:\n' + _indent(example.source) +
1125 'Expecting nothing\n')
Tim Peters8a7d2d52001-01-16 07:10:57 +00001126
Tim Peters8485b562004-08-04 18:46:34 +00001127 def report_success(self, out, test, example, got):
1128 """
1129 Report that the given example ran successfully. (Only
1130 displays a message if verbose=True)
1131 """
1132 if self._verbose:
1133 out("ok\n")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001134
Tim Peters8485b562004-08-04 18:46:34 +00001135 def report_failure(self, out, test, example, got):
1136 """
1137 Report that the given example failed.
1138 """
Edward Loper8e4a34b2004-08-12 02:34:27 +00001139 out(self._failure_header(test, example) +
Edward Loperca9111e2004-08-26 03:00:24 +00001140 self._checker.output_difference(example, got, self.optionflags))
Tim Peters7402f792001-10-02 03:53:41 +00001141
Tim Peters8485b562004-08-04 18:46:34 +00001142 def report_unexpected_exception(self, out, test, example, exc_info):
1143 """
1144 Report that the given example raised an unexpected exception.
1145 """
Edward Loper8e4a34b2004-08-12 02:34:27 +00001146 out(self._failure_header(test, example) +
Edward Loperaacf0832004-08-26 01:19:50 +00001147 'Exception raised:\n' + _indent(_exception_traceback(exc_info)))
Tim Peters7402f792001-10-02 03:53:41 +00001148
Edward Loper8e4a34b2004-08-12 02:34:27 +00001149 def _failure_header(self, test, example):
Jim Fulton07a349c2004-08-22 14:10:00 +00001150 out = [self.DIVIDER]
1151 if test.filename:
1152 if test.lineno is not None and example.lineno is not None:
1153 lineno = test.lineno + example.lineno + 1
1154 else:
1155 lineno = '?'
1156 out.append('File "%s", line %s, in %s' %
1157 (test.filename, lineno, test.name))
Tim Peters8485b562004-08-04 18:46:34 +00001158 else:
Jim Fulton07a349c2004-08-22 14:10:00 +00001159 out.append('Line %s, in %s' % (example.lineno+1, test.name))
1160 out.append('Failed example:')
1161 source = example.source
Edward Loperaacf0832004-08-26 01:19:50 +00001162 out.append(_indent(source))
1163 return '\n'.join(out)
Tim Peters7402f792001-10-02 03:53:41 +00001164
Tim Peters8485b562004-08-04 18:46:34 +00001165 #/////////////////////////////////////////////////////////////////
1166 # DocTest Running
1167 #/////////////////////////////////////////////////////////////////
Tim Peters7402f792001-10-02 03:53:41 +00001168
Tim Peters8485b562004-08-04 18:46:34 +00001169 def __run(self, test, compileflags, out):
Tim Peters8a7d2d52001-01-16 07:10:57 +00001170 """
Tim Peters8485b562004-08-04 18:46:34 +00001171 Run the examples in `test`. Write the outcome of each example
1172 with one of the `DocTestRunner.report_*` methods, using the
1173 writer function `out`. `compileflags` is the set of compiler
1174 flags that should be used to execute examples. Return a tuple
1175 `(f, t)`, where `t` is the number of examples tried, and `f`
1176 is the number of examples that failed. The examples are run
1177 in the namespace `test.globs`.
1178 """
1179 # Keep track of the number of failures and tries.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001180 failures = tries = 0
Tim Peters8485b562004-08-04 18:46:34 +00001181
1182 # Save the option flags (since option directives can be used
1183 # to modify them).
1184 original_optionflags = self.optionflags
1185
Tim Peters1fbf9c52004-09-04 17:21:02 +00001186 SUCCESS, FAILURE, BOOM = range(3) # `outcome` state
1187
1188 check = self._checker.check_output
1189
Tim Peters8485b562004-08-04 18:46:34 +00001190 # Process each example.
Edward Loper2de91ba2004-08-27 02:07:46 +00001191 for examplenum, example in enumerate(test.examples):
1192
Edward Lopera89f88d2004-08-26 02:45:51 +00001193 # If REPORT_ONLY_FIRST_FAILURE is set, then supress
1194 # reporting after the first failure.
1195 quiet = (self.optionflags & REPORT_ONLY_FIRST_FAILURE and
1196 failures > 0)
1197
Edward Loper74bca7a2004-08-12 02:27:44 +00001198 # Merge in the example's options.
1199 self.optionflags = original_optionflags
1200 if example.options:
1201 for (optionflag, val) in example.options.items():
1202 if val:
1203 self.optionflags |= optionflag
1204 else:
1205 self.optionflags &= ~optionflag
Tim Peters8485b562004-08-04 18:46:34 +00001206
Thomas Wouters477c8d52006-05-27 19:21:47 +00001207 # If 'SKIP' is set, then skip this example.
1208 if self.optionflags & SKIP:
1209 continue
1210
Tim Peters8485b562004-08-04 18:46:34 +00001211 # Record that we started this example.
1212 tries += 1
Edward Lopera89f88d2004-08-26 02:45:51 +00001213 if not quiet:
1214 self.report_start(out, test, example)
Tim Peters8485b562004-08-04 18:46:34 +00001215
Edward Loper2de91ba2004-08-27 02:07:46 +00001216 # Use a special filename for compile(), so we can retrieve
1217 # the source code during interactive debugging (see
1218 # __patched_linecache_getlines).
1219 filename = '<doctest %s[%d]>' % (test.name, examplenum)
1220
Tim Peters8485b562004-08-04 18:46:34 +00001221 # Run the example in the given context (globs), and record
1222 # any exception that gets raised. (But don't intercept
1223 # keyboard interrupts.)
1224 try:
Tim Peters208ca702004-08-09 04:12:36 +00001225 # Don't blink! This is where the user's code gets run.
Georg Brandl7cae87c2006-09-06 06:51:57 +00001226 exec(compile(example.source, filename, "single",
1227 compileflags, 1), test.globs)
Edward Loper2de91ba2004-08-27 02:07:46 +00001228 self.debugger.set_continue() # ==== Example Finished ====
Tim Peters8485b562004-08-04 18:46:34 +00001229 exception = None
1230 except KeyboardInterrupt:
1231 raise
1232 except:
1233 exception = sys.exc_info()
Edward Loper2de91ba2004-08-27 02:07:46 +00001234 self.debugger.set_continue() # ==== Example Finished ====
Tim Peters8485b562004-08-04 18:46:34 +00001235
Tim Peters208ca702004-08-09 04:12:36 +00001236 got = self._fakeout.getvalue() # the actual output
Tim Peters8485b562004-08-04 18:46:34 +00001237 self._fakeout.truncate(0)
Tim Peters1fbf9c52004-09-04 17:21:02 +00001238 outcome = FAILURE # guilty until proved innocent or insane
Tim Peters8485b562004-08-04 18:46:34 +00001239
1240 # If the example executed without raising any exceptions,
Tim Peters1fbf9c52004-09-04 17:21:02 +00001241 # verify its output.
Tim Peters8485b562004-08-04 18:46:34 +00001242 if exception is None:
Tim Peters1fbf9c52004-09-04 17:21:02 +00001243 if check(example.want, got, self.optionflags):
1244 outcome = SUCCESS
Tim Peters8485b562004-08-04 18:46:34 +00001245
Tim Peters1fbf9c52004-09-04 17:21:02 +00001246 # The example raised an exception: check if it was expected.
Tim Peters8485b562004-08-04 18:46:34 +00001247 else:
1248 exc_info = sys.exc_info()
1249 exc_msg = traceback.format_exception_only(*exc_info[:2])[-1]
Tim Peters1fbf9c52004-09-04 17:21:02 +00001250 if not quiet:
1251 got += _exception_traceback(exc_info)
Tim Peters8485b562004-08-04 18:46:34 +00001252
Tim Peters1fbf9c52004-09-04 17:21:02 +00001253 # If `example.exc_msg` is None, then we weren't expecting
1254 # an exception.
Edward Lopera6b68322004-08-26 00:05:43 +00001255 if example.exc_msg is None:
Tim Peters1fbf9c52004-09-04 17:21:02 +00001256 outcome = BOOM
1257
1258 # We expected an exception: see whether it matches.
1259 elif check(example.exc_msg, exc_msg, self.optionflags):
1260 outcome = SUCCESS
1261
1262 # Another chance if they didn't care about the detail.
1263 elif self.optionflags & IGNORE_EXCEPTION_DETAIL:
1264 m1 = re.match(r'[^:]*:', example.exc_msg)
1265 m2 = re.match(r'[^:]*:', exc_msg)
1266 if m1 and m2 and check(m1.group(0), m2.group(0),
1267 self.optionflags):
1268 outcome = SUCCESS
1269
1270 # Report the outcome.
1271 if outcome is SUCCESS:
1272 if not quiet:
1273 self.report_success(out, test, example, got)
1274 elif outcome is FAILURE:
1275 if not quiet:
1276 self.report_failure(out, test, example, got)
1277 failures += 1
1278 elif outcome is BOOM:
1279 if not quiet:
1280 self.report_unexpected_exception(out, test, example,
1281 exc_info)
1282 failures += 1
1283 else:
1284 assert False, ("unknown outcome", outcome)
Tim Peters8485b562004-08-04 18:46:34 +00001285
1286 # Restore the option flags (in case they were modified)
1287 self.optionflags = original_optionflags
1288
1289 # Record and return the number of failures and tries.
1290 self.__record_outcome(test, failures, tries)
Christian Heimes25bb7832008-01-11 16:17:00 +00001291 return TestResults(failures, tries)
Tim Peters8a7d2d52001-01-16 07:10:57 +00001292
Tim Peters8485b562004-08-04 18:46:34 +00001293 def __record_outcome(self, test, f, t):
1294 """
1295 Record the fact that the given DocTest (`test`) generated `f`
1296 failures out of `t` tried examples.
1297 """
1298 f2, t2 = self._name2ft.get(test.name, (0,0))
1299 self._name2ft[test.name] = (f+f2, t+t2)
1300 self.failures += f
1301 self.tries += t
1302
Edward Loper2de91ba2004-08-27 02:07:46 +00001303 __LINECACHE_FILENAME_RE = re.compile(r'<doctest '
1304 r'(?P<name>[\w\.]+)'
1305 r'\[(?P<examplenum>\d+)\]>$')
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00001306 def __patched_linecache_getlines(self, filename, module_globals=None):
Edward Loper2de91ba2004-08-27 02:07:46 +00001307 m = self.__LINECACHE_FILENAME_RE.match(filename)
1308 if m and m.group('name') == self.test.name:
1309 example = self.test.examples[int(m.group('examplenum'))]
1310 return example.source.splitlines(True)
1311 else:
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00001312 return self.save_linecache_getlines(filename, module_globals)
Edward Loper2de91ba2004-08-27 02:07:46 +00001313
Tim Peters8485b562004-08-04 18:46:34 +00001314 def run(self, test, compileflags=None, out=None, clear_globs=True):
1315 """
1316 Run the examples in `test`, and display the results using the
1317 writer function `out`.
1318
1319 The examples are run in the namespace `test.globs`. If
1320 `clear_globs` is true (the default), then this namespace will
1321 be cleared after the test runs, to help with garbage
1322 collection. If you would like to examine the namespace after
1323 the test completes, then use `clear_globs=False`.
1324
1325 `compileflags` gives the set of flags that should be used by
1326 the Python compiler when running the examples. If not
1327 specified, then it will default to the set of future-import
1328 flags that apply to `globs`.
1329
1330 The output of each example is checked using
1331 `DocTestRunner.check_output`, and the results are formatted by
1332 the `DocTestRunner.report_*` methods.
1333 """
Edward Loper2de91ba2004-08-27 02:07:46 +00001334 self.test = test
1335
Tim Peters8485b562004-08-04 18:46:34 +00001336 if compileflags is None:
1337 compileflags = _extract_future_flags(test.globs)
Jim Fulton356fd192004-08-09 11:34:47 +00001338
Tim Peters6c542b72004-08-09 16:43:36 +00001339 save_stdout = sys.stdout
Tim Peters8485b562004-08-04 18:46:34 +00001340 if out is None:
Tim Peters6c542b72004-08-09 16:43:36 +00001341 out = save_stdout.write
1342 sys.stdout = self._fakeout
Tim Peters8485b562004-08-04 18:46:34 +00001343
Edward Loper2de91ba2004-08-27 02:07:46 +00001344 # Patch pdb.set_trace to restore sys.stdout during interactive
1345 # debugging (so it's not still redirected to self._fakeout).
1346 # Note that the interactive output will go to *our*
1347 # save_stdout, even if that's not the real sys.stdout; this
1348 # allows us to write test cases for the set_trace behavior.
Tim Peters6c542b72004-08-09 16:43:36 +00001349 save_set_trace = pdb.set_trace
Edward Loper2de91ba2004-08-27 02:07:46 +00001350 self.debugger = _OutputRedirectingPdb(save_stdout)
1351 self.debugger.reset()
1352 pdb.set_trace = self.debugger.set_trace
1353
1354 # Patch linecache.getlines, so we can see the example's source
1355 # when we're inside the debugger.
1356 self.save_linecache_getlines = linecache.getlines
1357 linecache.getlines = self.__patched_linecache_getlines
1358
Tim Peters8485b562004-08-04 18:46:34 +00001359 try:
Tim Peters8485b562004-08-04 18:46:34 +00001360 return self.__run(test, compileflags, out)
1361 finally:
Tim Peters6c542b72004-08-09 16:43:36 +00001362 sys.stdout = save_stdout
1363 pdb.set_trace = save_set_trace
Edward Loper2de91ba2004-08-27 02:07:46 +00001364 linecache.getlines = self.save_linecache_getlines
Tim Peters8485b562004-08-04 18:46:34 +00001365 if clear_globs:
1366 test.globs.clear()
1367
1368 #/////////////////////////////////////////////////////////////////
1369 # Summarization
1370 #/////////////////////////////////////////////////////////////////
Tim Peters8a7d2d52001-01-16 07:10:57 +00001371 def summarize(self, verbose=None):
1372 """
Tim Peters8485b562004-08-04 18:46:34 +00001373 Print a summary of all the test cases that have been run by
1374 this DocTestRunner, and return a tuple `(f, t)`, where `f` is
1375 the total number of failed examples, and `t` is the total
1376 number of tried examples.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001377
Tim Peters8485b562004-08-04 18:46:34 +00001378 The optional `verbose` argument controls how detailed the
1379 summary is. If the verbosity is not specified, then the
1380 DocTestRunner's verbosity is used.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001381 """
Tim Peters8a7d2d52001-01-16 07:10:57 +00001382 if verbose is None:
Tim Peters8485b562004-08-04 18:46:34 +00001383 verbose = self._verbose
Tim Peters8a7d2d52001-01-16 07:10:57 +00001384 notests = []
1385 passed = []
1386 failed = []
1387 totalt = totalf = 0
Tim Peters8485b562004-08-04 18:46:34 +00001388 for x in self._name2ft.items():
Tim Peters8a7d2d52001-01-16 07:10:57 +00001389 name, (f, t) = x
1390 assert f <= t
Tim Peters8485b562004-08-04 18:46:34 +00001391 totalt += t
1392 totalf += f
Tim Peters8a7d2d52001-01-16 07:10:57 +00001393 if t == 0:
1394 notests.append(name)
1395 elif f == 0:
1396 passed.append( (name, t) )
1397 else:
1398 failed.append(x)
1399 if verbose:
1400 if notests:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001401 print(len(notests), "items had no tests:")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001402 notests.sort()
1403 for thing in notests:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001404 print(" ", thing)
Tim Peters8a7d2d52001-01-16 07:10:57 +00001405 if passed:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001406 print(len(passed), "items passed all tests:")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001407 passed.sort()
1408 for thing, count in passed:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001409 print(" %3d tests in %s" % (count, thing))
Tim Peters8a7d2d52001-01-16 07:10:57 +00001410 if failed:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001411 print(self.DIVIDER)
1412 print(len(failed), "items had failures:")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001413 failed.sort()
1414 for thing, (f, t) in failed:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001415 print(" %3d of %3d in %s" % (f, t, thing))
Tim Peters8a7d2d52001-01-16 07:10:57 +00001416 if verbose:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001417 print(totalt, "tests in", len(self._name2ft), "items.")
1418 print(totalt - totalf, "passed and", totalf, "failed.")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001419 if totalf:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001420 print("***Test Failed***", totalf, "failures.")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001421 elif verbose:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001422 print("Test passed.")
Christian Heimes25bb7832008-01-11 16:17:00 +00001423 return TestResults(totalf, totalt)
Tim Peters8a7d2d52001-01-16 07:10:57 +00001424
Tim Peters82076ef2004-09-13 00:52:51 +00001425 #/////////////////////////////////////////////////////////////////
1426 # Backward compatibility cruft to maintain doctest.master.
1427 #/////////////////////////////////////////////////////////////////
1428 def merge(self, other):
1429 d = self._name2ft
1430 for name, (f, t) in other._name2ft.items():
1431 if name in d:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001432 print("*** DocTestRunner.merge: '" + name + "' in both" \
1433 " testers; summing outcomes.")
Tim Peters82076ef2004-09-13 00:52:51 +00001434 f2, t2 = d[name]
1435 f = f + f2
1436 t = t + t2
1437 d[name] = f, t
1438
Edward Loper34fcb142004-08-09 02:45:41 +00001439class OutputChecker:
1440 """
1441 A class used to check the whether the actual output from a doctest
1442 example matches the expected output. `OutputChecker` defines two
1443 methods: `check_output`, which compares a given pair of outputs,
1444 and returns true if they match; and `output_difference`, which
1445 returns a string describing the differences between two outputs.
1446 """
1447 def check_output(self, want, got, optionflags):
1448 """
Edward Loper74bca7a2004-08-12 02:27:44 +00001449 Return True iff the actual output from an example (`got`)
1450 matches the expected output (`want`). These strings are
1451 always considered to match if they are identical; but
1452 depending on what option flags the test runner is using,
1453 several non-exact match types are also possible. See the
1454 documentation for `TestRunner` for more information about
1455 option flags.
Edward Loper34fcb142004-08-09 02:45:41 +00001456 """
1457 # Handle the common case first, for efficiency:
1458 # if they're string-identical, always return true.
1459 if got == want:
1460 return True
1461
1462 # The values True and False replaced 1 and 0 as the return
1463 # value for boolean comparisons in Python 2.3.
1464 if not (optionflags & DONT_ACCEPT_TRUE_FOR_1):
1465 if (got,want) == ("True\n", "1\n"):
1466 return True
1467 if (got,want) == ("False\n", "0\n"):
1468 return True
1469
1470 # <BLANKLINE> can be used as a special sequence to signify a
1471 # blank line, unless the DONT_ACCEPT_BLANKLINE flag is used.
1472 if not (optionflags & DONT_ACCEPT_BLANKLINE):
1473 # Replace <BLANKLINE> in want with a blank line.
1474 want = re.sub('(?m)^%s\s*?$' % re.escape(BLANKLINE_MARKER),
1475 '', want)
1476 # If a line in got contains only spaces, then remove the
1477 # spaces.
1478 got = re.sub('(?m)^\s*?$', '', got)
1479 if got == want:
1480 return True
1481
1482 # This flag causes doctest to ignore any differences in the
1483 # contents of whitespace strings. Note that this can be used
Tim Peters3fa8c202004-08-23 21:43:39 +00001484 # in conjunction with the ELLIPSIS flag.
Tim Peters1cf3aa62004-08-19 06:49:33 +00001485 if optionflags & NORMALIZE_WHITESPACE:
Edward Loper34fcb142004-08-09 02:45:41 +00001486 got = ' '.join(got.split())
1487 want = ' '.join(want.split())
1488 if got == want:
1489 return True
1490
1491 # The ELLIPSIS flag says to let the sequence "..." in `want`
Tim Peters26b3ebb2004-08-19 08:10:08 +00001492 # match any substring in `got`.
Tim Peters1cf3aa62004-08-19 06:49:33 +00001493 if optionflags & ELLIPSIS:
Tim Petersb0a04e12004-08-20 02:08:04 +00001494 if _ellipsis_match(want, got):
Edward Loper34fcb142004-08-09 02:45:41 +00001495 return True
1496
1497 # We didn't find any match; return false.
1498 return False
1499
Tim Petersc6cbab02004-08-22 19:43:28 +00001500 # Should we do a fancy diff?
1501 def _do_a_fancy_diff(self, want, got, optionflags):
1502 # Not unless they asked for a fancy diff.
Edward Loper71f55af2004-08-26 01:41:51 +00001503 if not optionflags & (REPORT_UDIFF |
1504 REPORT_CDIFF |
1505 REPORT_NDIFF):
Tim Petersc6cbab02004-08-22 19:43:28 +00001506 return False
Tim Peters5b799c12004-08-26 05:21:59 +00001507
Tim Petersc6cbab02004-08-22 19:43:28 +00001508 # If expected output uses ellipsis, a meaningful fancy diff is
Tim Peters5b799c12004-08-26 05:21:59 +00001509 # too hard ... or maybe not. In two real-life failures Tim saw,
1510 # a diff was a major help anyway, so this is commented out.
1511 # [todo] _ellipsis_match() knows which pieces do and don't match,
1512 # and could be the basis for a kick-ass diff in this case.
1513 ##if optionflags & ELLIPSIS and ELLIPSIS_MARKER in want:
1514 ## return False
1515
Tim Petersc6cbab02004-08-22 19:43:28 +00001516 # ndiff does intraline difference marking, so can be useful even
Tim Peters5b799c12004-08-26 05:21:59 +00001517 # for 1-line differences.
Edward Loper71f55af2004-08-26 01:41:51 +00001518 if optionflags & REPORT_NDIFF:
Tim Petersc6cbab02004-08-22 19:43:28 +00001519 return True
Tim Peters5b799c12004-08-26 05:21:59 +00001520
Tim Petersc6cbab02004-08-22 19:43:28 +00001521 # The other diff types need at least a few lines to be helpful.
1522 return want.count('\n') > 2 and got.count('\n') > 2
1523
Edward Loperca9111e2004-08-26 03:00:24 +00001524 def output_difference(self, example, got, optionflags):
Edward Loper34fcb142004-08-09 02:45:41 +00001525 """
1526 Return a string describing the differences between the
Edward Loperca9111e2004-08-26 03:00:24 +00001527 expected output for a given example (`example`) and the actual
1528 output (`got`). `optionflags` is the set of option flags used
1529 to compare `want` and `got`.
Edward Loper34fcb142004-08-09 02:45:41 +00001530 """
Edward Loperca9111e2004-08-26 03:00:24 +00001531 want = example.want
Edward Loper68ba9a62004-08-12 02:43:49 +00001532 # If <BLANKLINE>s are being used, then replace blank lines
1533 # with <BLANKLINE> in the actual output string.
Edward Loper34fcb142004-08-09 02:45:41 +00001534 if not (optionflags & DONT_ACCEPT_BLANKLINE):
Edward Loper68ba9a62004-08-12 02:43:49 +00001535 got = re.sub('(?m)^[ ]*(?=\n)', BLANKLINE_MARKER, got)
Edward Loper34fcb142004-08-09 02:45:41 +00001536
Tim Peters5b799c12004-08-26 05:21:59 +00001537 # Check if we should use diff.
Tim Petersc6cbab02004-08-22 19:43:28 +00001538 if self._do_a_fancy_diff(want, got, optionflags):
Edward Loper34fcb142004-08-09 02:45:41 +00001539 # Split want & got into lines.
Tim Peterse7edcb82004-08-26 05:44:27 +00001540 want_lines = want.splitlines(True) # True == keep line ends
1541 got_lines = got.splitlines(True)
Edward Loper34fcb142004-08-09 02:45:41 +00001542 # Use difflib to find their differences.
Edward Loper71f55af2004-08-26 01:41:51 +00001543 if optionflags & REPORT_UDIFF:
Edward Loper56629292004-08-26 01:31:56 +00001544 diff = difflib.unified_diff(want_lines, got_lines, n=2)
1545 diff = list(diff)[2:] # strip the diff header
1546 kind = 'unified diff with -expected +actual'
Edward Loper71f55af2004-08-26 01:41:51 +00001547 elif optionflags & REPORT_CDIFF:
Edward Loper56629292004-08-26 01:31:56 +00001548 diff = difflib.context_diff(want_lines, got_lines, n=2)
1549 diff = list(diff)[2:] # strip the diff header
1550 kind = 'context diff with expected followed by actual'
Edward Loper71f55af2004-08-26 01:41:51 +00001551 elif optionflags & REPORT_NDIFF:
Tim Petersc6cbab02004-08-22 19:43:28 +00001552 engine = difflib.Differ(charjunk=difflib.IS_CHARACTER_JUNK)
1553 diff = list(engine.compare(want_lines, got_lines))
1554 kind = 'ndiff with -expected +actual'
Edward Loper34fcb142004-08-09 02:45:41 +00001555 else:
1556 assert 0, 'Bad diff option'
1557 # Remove trailing whitespace on diff output.
1558 diff = [line.rstrip() + '\n' for line in diff]
Edward Loperaacf0832004-08-26 01:19:50 +00001559 return 'Differences (%s):\n' % kind + _indent(''.join(diff))
Edward Loper34fcb142004-08-09 02:45:41 +00001560
1561 # If we're not using diff, then simply list the expected
1562 # output followed by the actual output.
Edward Loperaacf0832004-08-26 01:19:50 +00001563 if want and got:
1564 return 'Expected:\n%sGot:\n%s' % (_indent(want), _indent(got))
1565 elif want:
1566 return 'Expected:\n%sGot nothing\n' % _indent(want)
1567 elif got:
1568 return 'Expected nothing\nGot:\n%s' % _indent(got)
1569 else:
1570 return 'Expected nothing\nGot nothing\n'
Edward Loper34fcb142004-08-09 02:45:41 +00001571
Tim Peters19397e52004-08-06 22:02:59 +00001572class DocTestFailure(Exception):
1573 """A DocTest example has failed in debugging mode.
1574
1575 The exception instance has variables:
1576
1577 - test: the DocTest object being run
1578
Neal Norwitzc082cb72006-08-29 05:40:08 +00001579 - example: the Example object that failed
Tim Peters19397e52004-08-06 22:02:59 +00001580
1581 - got: the actual output
1582 """
1583 def __init__(self, test, example, got):
1584 self.test = test
1585 self.example = example
1586 self.got = got
1587
1588 def __str__(self):
1589 return str(self.test)
1590
1591class UnexpectedException(Exception):
1592 """A DocTest example has encountered an unexpected exception
1593
1594 The exception instance has variables:
1595
1596 - test: the DocTest object being run
1597
Guido van Rossum6a2a2a02006-08-26 20:37:44 +00001598 - example: the Example object that failed
Tim Peters19397e52004-08-06 22:02:59 +00001599
1600 - exc_info: the exception info
1601 """
1602 def __init__(self, test, example, exc_info):
1603 self.test = test
1604 self.example = example
1605 self.exc_info = exc_info
1606
1607 def __str__(self):
1608 return str(self.test)
Tim Petersd1b78272004-08-07 06:03:09 +00001609
Tim Peters19397e52004-08-06 22:02:59 +00001610class DebugRunner(DocTestRunner):
1611 r"""Run doc tests but raise an exception as soon as there is a failure.
1612
1613 If an unexpected exception occurs, an UnexpectedException is raised.
1614 It contains the test, the example, and the original exception:
1615
1616 >>> runner = DebugRunner(verbose=False)
Edward Lopera1ef6112004-08-09 16:14:41 +00001617 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
1618 ... {}, 'foo', 'foo.py', 0)
Tim Peters19397e52004-08-06 22:02:59 +00001619 >>> try:
1620 ... runner.run(test)
Guido van Rossumb940e112007-01-10 16:19:56 +00001621 ... except UnexpectedException as f:
1622 ... failure = f
Tim Peters19397e52004-08-06 22:02:59 +00001623
1624 >>> failure.test is test
1625 True
1626
1627 >>> failure.example.want
1628 '42\n'
1629
1630 >>> exc_info = failure.exc_info
Collin Winter828f04a2007-08-31 00:04:24 +00001631 >>> raise exc_info[1] # Already has the traceback
Tim Peters19397e52004-08-06 22:02:59 +00001632 Traceback (most recent call last):
1633 ...
1634 KeyError
1635
1636 We wrap the original exception to give the calling application
1637 access to the test and example information.
1638
1639 If the output doesn't match, then a DocTestFailure is raised:
1640
Edward Lopera1ef6112004-08-09 16:14:41 +00001641 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00001642 ... >>> x = 1
1643 ... >>> x
1644 ... 2
1645 ... ''', {}, 'foo', 'foo.py', 0)
1646
1647 >>> try:
1648 ... runner.run(test)
Guido van Rossumb940e112007-01-10 16:19:56 +00001649 ... except DocTestFailure as f:
1650 ... failure = f
Tim Peters19397e52004-08-06 22:02:59 +00001651
1652 DocTestFailure objects provide access to the test:
1653
1654 >>> failure.test is test
1655 True
1656
1657 As well as to the example:
1658
1659 >>> failure.example.want
1660 '2\n'
1661
1662 and the actual output:
1663
1664 >>> failure.got
1665 '1\n'
1666
1667 If a failure or error occurs, the globals are left intact:
1668
1669 >>> del test.globs['__builtins__']
1670 >>> test.globs
1671 {'x': 1}
1672
Edward Lopera1ef6112004-08-09 16:14:41 +00001673 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00001674 ... >>> x = 2
1675 ... >>> raise KeyError
1676 ... ''', {}, 'foo', 'foo.py', 0)
1677
1678 >>> runner.run(test)
1679 Traceback (most recent call last):
1680 ...
Guido van Rossum6a2a2a02006-08-26 20:37:44 +00001681 doctest.UnexpectedException: <DocTest foo from foo.py:0 (2 examples)>
Tim Petersd1b78272004-08-07 06:03:09 +00001682
Tim Peters19397e52004-08-06 22:02:59 +00001683 >>> del test.globs['__builtins__']
1684 >>> test.globs
1685 {'x': 2}
1686
1687 But the globals are cleared if there is no error:
1688
Edward Lopera1ef6112004-08-09 16:14:41 +00001689 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00001690 ... >>> x = 2
1691 ... ''', {}, 'foo', 'foo.py', 0)
1692
1693 >>> runner.run(test)
Christian Heimes25bb7832008-01-11 16:17:00 +00001694 TestResults(failed=0, attempted=1)
Tim Peters19397e52004-08-06 22:02:59 +00001695
1696 >>> test.globs
1697 {}
1698
1699 """
1700
1701 def run(self, test, compileflags=None, out=None, clear_globs=True):
1702 r = DocTestRunner.run(self, test, compileflags, out, False)
1703 if clear_globs:
1704 test.globs.clear()
1705 return r
1706
1707 def report_unexpected_exception(self, out, test, example, exc_info):
1708 raise UnexpectedException(test, example, exc_info)
1709
1710 def report_failure(self, out, test, example, got):
1711 raise DocTestFailure(test, example, got)
1712
Tim Peters8485b562004-08-04 18:46:34 +00001713######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00001714## 6. Test Functions
Tim Peters8485b562004-08-04 18:46:34 +00001715######################################################################
1716# These should be backwards compatible.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001717
Tim Peters82076ef2004-09-13 00:52:51 +00001718# For backward compatibility, a global instance of a DocTestRunner
1719# class, updated by testmod.
1720master = None
1721
Thomas Wouters73e5a5b2006-06-08 15:35:45 +00001722def testmod(m=None, name=None, globs=None, verbose=None,
Tim Peters19397e52004-08-06 22:02:59 +00001723 report=True, optionflags=0, extraglobs=None,
Tim Peters958cc892004-09-13 14:53:28 +00001724 raise_on_error=False, exclude_empty=False):
Thomas Wouters73e5a5b2006-06-08 15:35:45 +00001725 """m=None, name=None, globs=None, verbose=None, report=True,
1726 optionflags=0, extraglobs=None, raise_on_error=False,
Tim Peters958cc892004-09-13 14:53:28 +00001727 exclude_empty=False
Tim Peters8a7d2d52001-01-16 07:10:57 +00001728
Martin v. Löwis4581cfa2002-11-22 08:23:09 +00001729 Test examples in docstrings in functions and classes reachable
1730 from module m (or the current module if m is not supplied), starting
Thomas Wouters73e5a5b2006-06-08 15:35:45 +00001731 with m.__doc__.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001732
1733 Also test examples reachable from dict m.__test__ if it exists and is
Tim Petersc2388a22004-08-10 01:41:28 +00001734 not None. m.__test__ maps names to functions, classes and strings;
Tim Peters8a7d2d52001-01-16 07:10:57 +00001735 function and class docstrings are tested even if the name is private;
1736 strings are tested directly, as if they were docstrings.
1737
1738 Return (#failures, #tests).
1739
1740 See doctest.__doc__ for an overview.
1741
1742 Optional keyword arg "name" gives the name of the module; by default
1743 use m.__name__.
1744
1745 Optional keyword arg "globs" gives a dict to be used as the globals
1746 when executing examples; by default, use m.__dict__. A copy of this
1747 dict is actually used for each docstring, so that each docstring's
1748 examples start with a clean slate.
1749
Tim Peters8485b562004-08-04 18:46:34 +00001750 Optional keyword arg "extraglobs" gives a dictionary that should be
1751 merged into the globals that are used to execute examples. By
1752 default, no extra globals are used. This is new in 2.4.
1753
Tim Peters8a7d2d52001-01-16 07:10:57 +00001754 Optional keyword arg "verbose" prints lots of stuff if true, prints
1755 only failures if false; by default, it's true iff "-v" is in sys.argv.
1756
Tim Peters8a7d2d52001-01-16 07:10:57 +00001757 Optional keyword arg "report" prints a summary at the end when true,
1758 else prints nothing at the end. In verbose mode, the summary is
1759 detailed, else very brief (in fact, empty if all tests passed).
1760
Tim Peters6ebe61f2003-06-27 20:48:05 +00001761 Optional keyword arg "optionflags" or's together module constants,
Tim Petersf82a9de2004-08-22 20:51:53 +00001762 and defaults to 0. This is new in 2.3. Possible values (see the
1763 docs for details):
Tim Peters6ebe61f2003-06-27 20:48:05 +00001764
1765 DONT_ACCEPT_TRUE_FOR_1
Tim Peters8485b562004-08-04 18:46:34 +00001766 DONT_ACCEPT_BLANKLINE
Tim Peters8485b562004-08-04 18:46:34 +00001767 NORMALIZE_WHITESPACE
Tim Peters8485b562004-08-04 18:46:34 +00001768 ELLIPSIS
Thomas Wouters477c8d52006-05-27 19:21:47 +00001769 SKIP
Edward Loper052d0cd2004-09-19 17:19:33 +00001770 IGNORE_EXCEPTION_DETAIL
Edward Loper71f55af2004-08-26 01:41:51 +00001771 REPORT_UDIFF
1772 REPORT_CDIFF
1773 REPORT_NDIFF
Edward Lopera89f88d2004-08-26 02:45:51 +00001774 REPORT_ONLY_FIRST_FAILURE
Tim Peters19397e52004-08-06 22:02:59 +00001775
1776 Optional keyword arg "raise_on_error" raises an exception on the
1777 first unexpected exception or failure. This allows failures to be
1778 post-mortem debugged.
1779
Tim Peters8a7d2d52001-01-16 07:10:57 +00001780 Advanced tomfoolery: testmod runs methods of a local instance of
1781 class doctest.Tester, then merges the results into (or creates)
1782 global Tester instance doctest.master. Methods of doctest.master
1783 can be called directly too, if you want to do something unusual.
1784 Passing report=0 to testmod is especially useful then, to delay
1785 displaying a summary. Invoke doctest.master.summarize(verbose)
1786 when you're done fiddling.
1787 """
Tim Peters82076ef2004-09-13 00:52:51 +00001788 global master
1789
Tim Peters8485b562004-08-04 18:46:34 +00001790 # If no module was given, then use __main__.
Martin v. Löwis4581cfa2002-11-22 08:23:09 +00001791 if m is None:
Martin v. Löwis4581cfa2002-11-22 08:23:09 +00001792 # DWA - m will still be None if this wasn't invoked from the command
1793 # line, in which case the following TypeError is about as good an error
1794 # as we should expect
1795 m = sys.modules.get('__main__')
1796
Tim Peters8485b562004-08-04 18:46:34 +00001797 # Check that we were actually given a module.
1798 if not inspect.ismodule(m):
Walter Dörwald70a6b492004-02-12 17:35:32 +00001799 raise TypeError("testmod: module required; %r" % (m,))
Tim Peters8485b562004-08-04 18:46:34 +00001800
1801 # If no name was given, then use the module's name.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001802 if name is None:
1803 name = m.__name__
Tim Peters8485b562004-08-04 18:46:34 +00001804
1805 # Find, parse, and run all tests in the given module.
Thomas Wouters73e5a5b2006-06-08 15:35:45 +00001806 finder = DocTestFinder(exclude_empty=exclude_empty)
Tim Peters19397e52004-08-06 22:02:59 +00001807
1808 if raise_on_error:
1809 runner = DebugRunner(verbose=verbose, optionflags=optionflags)
1810 else:
1811 runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1812
Tim Peters8485b562004-08-04 18:46:34 +00001813 for test in finder.find(m, name, globs=globs, extraglobs=extraglobs):
1814 runner.run(test)
1815
Tim Peters8a7d2d52001-01-16 07:10:57 +00001816 if report:
Tim Peters8485b562004-08-04 18:46:34 +00001817 runner.summarize()
Tim Peters8a7d2d52001-01-16 07:10:57 +00001818
Tim Peters82076ef2004-09-13 00:52:51 +00001819 if master is None:
1820 master = runner
1821 else:
1822 master.merge(runner)
1823
Christian Heimes25bb7832008-01-11 16:17:00 +00001824 return TestResults(runner.failures, runner.tries)
Tim Petersdb3756d2003-06-29 05:30:48 +00001825
Edward Loper052d0cd2004-09-19 17:19:33 +00001826def testfile(filename, module_relative=True, name=None, package=None,
1827 globs=None, verbose=None, report=True, optionflags=0,
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00001828 extraglobs=None, raise_on_error=False, parser=DocTestParser(),
1829 encoding=None):
Edward Loper052d0cd2004-09-19 17:19:33 +00001830 """
1831 Test examples in the given file. Return (#failures, #tests).
1832
1833 Optional keyword arg "module_relative" specifies how filenames
1834 should be interpreted:
1835
1836 - If "module_relative" is True (the default), then "filename"
1837 specifies a module-relative path. By default, this path is
1838 relative to the calling module's directory; but if the
1839 "package" argument is specified, then it is relative to that
1840 package. To ensure os-independence, "filename" should use
1841 "/" characters to separate path segments, and should not
1842 be an absolute path (i.e., it may not begin with "/").
1843
1844 - If "module_relative" is False, then "filename" specifies an
1845 os-specific path. The path may be absolute or relative (to
1846 the current working directory).
1847
Edward Lopera2fc7ec2004-09-21 03:24:24 +00001848 Optional keyword arg "name" gives the name of the test; by default
1849 use the file's basename.
Edward Loper052d0cd2004-09-19 17:19:33 +00001850
1851 Optional keyword argument "package" is a Python package or the
1852 name of a Python package whose directory should be used as the
1853 base directory for a module relative filename. If no package is
1854 specified, then the calling module's directory is used as the base
1855 directory for module relative filenames. It is an error to
1856 specify "package" if "module_relative" is False.
1857
1858 Optional keyword arg "globs" gives a dict to be used as the globals
1859 when executing examples; by default, use {}. A copy of this dict
1860 is actually used for each docstring, so that each docstring's
1861 examples start with a clean slate.
1862
1863 Optional keyword arg "extraglobs" gives a dictionary that should be
1864 merged into the globals that are used to execute examples. By
1865 default, no extra globals are used.
1866
1867 Optional keyword arg "verbose" prints lots of stuff if true, prints
1868 only failures if false; by default, it's true iff "-v" is in sys.argv.
1869
1870 Optional keyword arg "report" prints a summary at the end when true,
1871 else prints nothing at the end. In verbose mode, the summary is
1872 detailed, else very brief (in fact, empty if all tests passed).
1873
1874 Optional keyword arg "optionflags" or's together module constants,
1875 and defaults to 0. Possible values (see the docs for details):
1876
1877 DONT_ACCEPT_TRUE_FOR_1
1878 DONT_ACCEPT_BLANKLINE
1879 NORMALIZE_WHITESPACE
1880 ELLIPSIS
Thomas Wouters477c8d52006-05-27 19:21:47 +00001881 SKIP
Edward Loper052d0cd2004-09-19 17:19:33 +00001882 IGNORE_EXCEPTION_DETAIL
1883 REPORT_UDIFF
1884 REPORT_CDIFF
1885 REPORT_NDIFF
1886 REPORT_ONLY_FIRST_FAILURE
1887
1888 Optional keyword arg "raise_on_error" raises an exception on the
1889 first unexpected exception or failure. This allows failures to be
1890 post-mortem debugged.
1891
Edward Loper498a1862004-09-27 03:42:58 +00001892 Optional keyword arg "parser" specifies a DocTestParser (or
1893 subclass) that should be used to extract tests from the files.
1894
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00001895 Optional keyword arg "encoding" specifies an encoding that should
1896 be used to convert the file to unicode.
1897
Edward Loper052d0cd2004-09-19 17:19:33 +00001898 Advanced tomfoolery: testmod runs methods of a local instance of
1899 class doctest.Tester, then merges the results into (or creates)
1900 global Tester instance doctest.master. Methods of doctest.master
1901 can be called directly too, if you want to do something unusual.
1902 Passing report=0 to testmod is especially useful then, to delay
1903 displaying a summary. Invoke doctest.master.summarize(verbose)
1904 when you're done fiddling.
1905 """
1906 global master
1907
1908 if package and not module_relative:
1909 raise ValueError("Package may only be specified for module-"
1910 "relative paths.")
Tim Petersbab3e992004-09-20 19:52:34 +00001911
Edward Loper052d0cd2004-09-19 17:19:33 +00001912 # Relativize the path
Guido van Rossum1b81e7b2007-08-29 03:53:53 +00001913 text, filename = _load_testfile(filename, package, module_relative,
1914 encoding or "utf-8")
Edward Loper052d0cd2004-09-19 17:19:33 +00001915
1916 # If no name was given, then use the file's name.
1917 if name is None:
Edward Lopera2fc7ec2004-09-21 03:24:24 +00001918 name = os.path.basename(filename)
Edward Loper052d0cd2004-09-19 17:19:33 +00001919
1920 # Assemble the globals.
1921 if globs is None:
1922 globs = {}
1923 else:
1924 globs = globs.copy()
1925 if extraglobs is not None:
1926 globs.update(extraglobs)
1927
1928 if raise_on_error:
1929 runner = DebugRunner(verbose=verbose, optionflags=optionflags)
1930 else:
1931 runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1932
1933 # Read the file, convert it to a test, and run it.
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00001934 test = parser.get_doctest(text, globs, name, filename, 0)
Edward Loper052d0cd2004-09-19 17:19:33 +00001935 runner.run(test)
1936
1937 if report:
1938 runner.summarize()
1939
1940 if master is None:
1941 master = runner
1942 else:
1943 master.merge(runner)
1944
Christian Heimes25bb7832008-01-11 16:17:00 +00001945 return TestResults(runner.failures, runner.tries)
Edward Loper052d0cd2004-09-19 17:19:33 +00001946
Tim Peters8485b562004-08-04 18:46:34 +00001947def run_docstring_examples(f, globs, verbose=False, name="NoName",
1948 compileflags=None, optionflags=0):
1949 """
1950 Test examples in the given object's docstring (`f`), using `globs`
1951 as globals. Optional argument `name` is used in failure messages.
1952 If the optional argument `verbose` is true, then generate output
1953 even if there are no failures.
Tim Petersdb3756d2003-06-29 05:30:48 +00001954
Tim Peters8485b562004-08-04 18:46:34 +00001955 `compileflags` gives the set of flags that should be used by the
1956 Python compiler when running the examples. If not specified, then
1957 it will default to the set of future-import flags that apply to
1958 `globs`.
Tim Petersdb3756d2003-06-29 05:30:48 +00001959
Tim Peters8485b562004-08-04 18:46:34 +00001960 Optional keyword arg `optionflags` specifies options for the
1961 testing and output. See the documentation for `testmod` for more
1962 information.
1963 """
1964 # Find, parse, and run all tests in the given module.
1965 finder = DocTestFinder(verbose=verbose, recurse=False)
1966 runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1967 for test in finder.find(f, name, globs=globs):
1968 runner.run(test, compileflags=compileflags)
Tim Petersdb3756d2003-06-29 05:30:48 +00001969
Tim Peters8485b562004-08-04 18:46:34 +00001970######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00001971## 7. Tester
Tim Peters8485b562004-08-04 18:46:34 +00001972######################################################################
1973# This is provided only for backwards compatibility. It's not
1974# actually used in any way.
Tim Petersdb3756d2003-06-29 05:30:48 +00001975
Tim Peters8485b562004-08-04 18:46:34 +00001976class Tester:
Thomas Wouters73e5a5b2006-06-08 15:35:45 +00001977 def __init__(self, mod=None, globs=None, verbose=None, optionflags=0):
Tim Peters3ddd60a2004-08-08 02:43:33 +00001978
1979 warnings.warn("class Tester is deprecated; "
1980 "use class doctest.DocTestRunner instead",
1981 DeprecationWarning, stacklevel=2)
Tim Peters8485b562004-08-04 18:46:34 +00001982 if mod is None and globs is None:
1983 raise TypeError("Tester.__init__: must specify mod or globs")
Tim Peters4be7a922004-09-12 22:39:46 +00001984 if mod is not None and not inspect.ismodule(mod):
Tim Peters8485b562004-08-04 18:46:34 +00001985 raise TypeError("Tester.__init__: mod must be a module; %r" %
1986 (mod,))
1987 if globs is None:
1988 globs = mod.__dict__
1989 self.globs = globs
Tim Petersdb3756d2003-06-29 05:30:48 +00001990
Tim Peters8485b562004-08-04 18:46:34 +00001991 self.verbose = verbose
Tim Peters8485b562004-08-04 18:46:34 +00001992 self.optionflags = optionflags
Thomas Wouters73e5a5b2006-06-08 15:35:45 +00001993 self.testfinder = DocTestFinder()
Tim Peters8485b562004-08-04 18:46:34 +00001994 self.testrunner = DocTestRunner(verbose=verbose,
1995 optionflags=optionflags)
Tim Petersdb3756d2003-06-29 05:30:48 +00001996
Tim Peters8485b562004-08-04 18:46:34 +00001997 def runstring(self, s, name):
Edward Lopera1ef6112004-08-09 16:14:41 +00001998 test = DocTestParser().get_doctest(s, self.globs, name, None, None)
Tim Peters8485b562004-08-04 18:46:34 +00001999 if self.verbose:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00002000 print("Running string", name)
Tim Peters8485b562004-08-04 18:46:34 +00002001 (f,t) = self.testrunner.run(test)
2002 if self.verbose:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00002003 print(f, "of", t, "examples failed in string", name)
Christian Heimes25bb7832008-01-11 16:17:00 +00002004 return TestResults(f,t)
Tim Petersdb3756d2003-06-29 05:30:48 +00002005
Tim Petersf3f57472004-08-08 06:11:48 +00002006 def rundoc(self, object, name=None, module=None):
Tim Peters8485b562004-08-04 18:46:34 +00002007 f = t = 0
2008 tests = self.testfinder.find(object, name, module=module,
Tim Petersf3f57472004-08-08 06:11:48 +00002009 globs=self.globs)
Tim Peters8485b562004-08-04 18:46:34 +00002010 for test in tests:
2011 (f2, t2) = self.testrunner.run(test)
2012 (f,t) = (f+f2, t+t2)
Christian Heimes25bb7832008-01-11 16:17:00 +00002013 return TestResults(f,t)
Tim Petersdb3756d2003-06-29 05:30:48 +00002014
Tim Peters8485b562004-08-04 18:46:34 +00002015 def rundict(self, d, name, module=None):
Christian Heimes45f9af32007-11-27 21:50:00 +00002016 import types
2017 m = types.ModuleType(name)
Tim Peters8485b562004-08-04 18:46:34 +00002018 m.__dict__.update(d)
Tim Petersf3f57472004-08-08 06:11:48 +00002019 if module is None:
2020 module = False
2021 return self.rundoc(m, name, module)
Tim Petersdb3756d2003-06-29 05:30:48 +00002022
Tim Peters8485b562004-08-04 18:46:34 +00002023 def run__test__(self, d, name):
Christian Heimes45f9af32007-11-27 21:50:00 +00002024 import types
2025 m = types.ModuleType(name)
Tim Peters8485b562004-08-04 18:46:34 +00002026 m.__test__ = d
Tim Peters9661f9a2004-09-12 22:45:17 +00002027 return self.rundoc(m, name)
Tim Petersdb3756d2003-06-29 05:30:48 +00002028
Tim Peters8485b562004-08-04 18:46:34 +00002029 def summarize(self, verbose=None):
2030 return self.testrunner.summarize(verbose)
Tim Petersdb3756d2003-06-29 05:30:48 +00002031
Tim Peters8485b562004-08-04 18:46:34 +00002032 def merge(self, other):
Tim Peters82076ef2004-09-13 00:52:51 +00002033 self.testrunner.merge(other.testrunner)
Tim Petersdb3756d2003-06-29 05:30:48 +00002034
Tim Peters8485b562004-08-04 18:46:34 +00002035######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00002036## 8. Unittest Support
Tim Peters8485b562004-08-04 18:46:34 +00002037######################################################################
Tim Petersdb3756d2003-06-29 05:30:48 +00002038
Jim Fultonf54bad42004-08-28 14:57:56 +00002039_unittest_reportflags = 0
Tim Peters38330fe2004-08-30 16:19:24 +00002040
Jim Fultonf54bad42004-08-28 14:57:56 +00002041def set_unittest_reportflags(flags):
Tim Peters38330fe2004-08-30 16:19:24 +00002042 """Sets the unittest option flags.
Jim Fultonf54bad42004-08-28 14:57:56 +00002043
2044 The old flag is returned so that a runner could restore the old
2045 value if it wished to:
2046
Tim Petersb7e99b62005-03-28 23:50:54 +00002047 >>> import doctest
2048 >>> old = doctest._unittest_reportflags
2049 >>> doctest.set_unittest_reportflags(REPORT_NDIFF |
Jim Fultonf54bad42004-08-28 14:57:56 +00002050 ... REPORT_ONLY_FIRST_FAILURE) == old
2051 True
2052
Jim Fultonf54bad42004-08-28 14:57:56 +00002053 >>> doctest._unittest_reportflags == (REPORT_NDIFF |
2054 ... REPORT_ONLY_FIRST_FAILURE)
2055 True
Tim Petersdf7a2082004-08-29 00:38:17 +00002056
Jim Fultonf54bad42004-08-28 14:57:56 +00002057 Only reporting flags can be set:
2058
Tim Petersb7e99b62005-03-28 23:50:54 +00002059 >>> doctest.set_unittest_reportflags(ELLIPSIS)
Jim Fultonf54bad42004-08-28 14:57:56 +00002060 Traceback (most recent call last):
2061 ...
Tim Peters38330fe2004-08-30 16:19:24 +00002062 ValueError: ('Only reporting flags allowed', 8)
Jim Fultonf54bad42004-08-28 14:57:56 +00002063
Tim Petersb7e99b62005-03-28 23:50:54 +00002064 >>> doctest.set_unittest_reportflags(old) == (REPORT_NDIFF |
Jim Fultonf54bad42004-08-28 14:57:56 +00002065 ... REPORT_ONLY_FIRST_FAILURE)
2066 True
Jim Fultonf54bad42004-08-28 14:57:56 +00002067 """
Jim Fultonf54bad42004-08-28 14:57:56 +00002068 global _unittest_reportflags
Tim Peters38330fe2004-08-30 16:19:24 +00002069
2070 if (flags & REPORTING_FLAGS) != flags:
2071 raise ValueError("Only reporting flags allowed", flags)
Jim Fultonf54bad42004-08-28 14:57:56 +00002072 old = _unittest_reportflags
2073 _unittest_reportflags = flags
2074 return old
Tim Petersdf7a2082004-08-29 00:38:17 +00002075
Jim Fultonf54bad42004-08-28 14:57:56 +00002076
Tim Peters19397e52004-08-06 22:02:59 +00002077class DocTestCase(unittest.TestCase):
Tim Petersdb3756d2003-06-29 05:30:48 +00002078
Edward Loper34fcb142004-08-09 02:45:41 +00002079 def __init__(self, test, optionflags=0, setUp=None, tearDown=None,
2080 checker=None):
Jim Fulton07a349c2004-08-22 14:10:00 +00002081
Jim Fultona643b652004-07-14 19:06:50 +00002082 unittest.TestCase.__init__(self)
Tim Peters19397e52004-08-06 22:02:59 +00002083 self._dt_optionflags = optionflags
Edward Loper34fcb142004-08-09 02:45:41 +00002084 self._dt_checker = checker
Tim Peters19397e52004-08-06 22:02:59 +00002085 self._dt_test = test
2086 self._dt_setUp = setUp
2087 self._dt_tearDown = tearDown
Tim Petersdb3756d2003-06-29 05:30:48 +00002088
Jim Fultona643b652004-07-14 19:06:50 +00002089 def setUp(self):
Jim Fultonf54bad42004-08-28 14:57:56 +00002090 test = self._dt_test
Tim Petersdf7a2082004-08-29 00:38:17 +00002091
Tim Peters19397e52004-08-06 22:02:59 +00002092 if self._dt_setUp is not None:
Jim Fultonf54bad42004-08-28 14:57:56 +00002093 self._dt_setUp(test)
Jim Fultona643b652004-07-14 19:06:50 +00002094
2095 def tearDown(self):
Jim Fultonf54bad42004-08-28 14:57:56 +00002096 test = self._dt_test
2097
Tim Peters19397e52004-08-06 22:02:59 +00002098 if self._dt_tearDown is not None:
Jim Fultonf54bad42004-08-28 14:57:56 +00002099 self._dt_tearDown(test)
2100
2101 test.globs.clear()
Jim Fultona643b652004-07-14 19:06:50 +00002102
2103 def runTest(self):
Tim Peters19397e52004-08-06 22:02:59 +00002104 test = self._dt_test
Jim Fultona643b652004-07-14 19:06:50 +00002105 old = sys.stdout
2106 new = StringIO()
Jim Fultonf54bad42004-08-28 14:57:56 +00002107 optionflags = self._dt_optionflags
Tim Petersdf7a2082004-08-29 00:38:17 +00002108
Tim Peters38330fe2004-08-30 16:19:24 +00002109 if not (optionflags & REPORTING_FLAGS):
Jim Fultonf54bad42004-08-28 14:57:56 +00002110 # The option flags don't include any reporting flags,
2111 # so add the default reporting flags
2112 optionflags |= _unittest_reportflags
Tim Petersdf7a2082004-08-29 00:38:17 +00002113
Jim Fultonf54bad42004-08-28 14:57:56 +00002114 runner = DocTestRunner(optionflags=optionflags,
Edward Loper34fcb142004-08-09 02:45:41 +00002115 checker=self._dt_checker, verbose=False)
Tim Peters19397e52004-08-06 22:02:59 +00002116
Jim Fultona643b652004-07-14 19:06:50 +00002117 try:
Tim Peters19397e52004-08-06 22:02:59 +00002118 runner.DIVIDER = "-"*70
Jim Fultonf54bad42004-08-28 14:57:56 +00002119 failures, tries = runner.run(
2120 test, out=new.write, clear_globs=False)
Jim Fultona643b652004-07-14 19:06:50 +00002121 finally:
2122 sys.stdout = old
2123
2124 if failures:
Tim Peters19397e52004-08-06 22:02:59 +00002125 raise self.failureException(self.format_failure(new.getvalue()))
Tim Peters8485b562004-08-04 18:46:34 +00002126
Tim Peters19397e52004-08-06 22:02:59 +00002127 def format_failure(self, err):
2128 test = self._dt_test
2129 if test.lineno is None:
2130 lineno = 'unknown line number'
2131 else:
Jim Fulton07a349c2004-08-22 14:10:00 +00002132 lineno = '%s' % test.lineno
Tim Peters19397e52004-08-06 22:02:59 +00002133 lname = '.'.join(test.name.split('.')[-1:])
2134 return ('Failed doctest test for %s\n'
2135 ' File "%s", line %s, in %s\n\n%s'
2136 % (test.name, test.filename, lineno, lname, err)
2137 )
2138
2139 def debug(self):
2140 r"""Run the test case without results and without catching exceptions
2141
2142 The unit test framework includes a debug method on test cases
2143 and test suites to support post-mortem debugging. The test code
2144 is run in such a way that errors are not caught. This way a
2145 caller can catch the errors and initiate post-mortem debugging.
2146
2147 The DocTestCase provides a debug method that raises
2148 UnexpectedException errors if there is an unexepcted
2149 exception:
2150
Edward Lopera1ef6112004-08-09 16:14:41 +00002151 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
Tim Peters19397e52004-08-06 22:02:59 +00002152 ... {}, 'foo', 'foo.py', 0)
2153 >>> case = DocTestCase(test)
2154 >>> try:
2155 ... case.debug()
Guido van Rossumb940e112007-01-10 16:19:56 +00002156 ... except UnexpectedException as f:
2157 ... failure = f
Tim Peters19397e52004-08-06 22:02:59 +00002158
2159 The UnexpectedException contains the test, the example, and
2160 the original exception:
2161
2162 >>> failure.test is test
2163 True
2164
2165 >>> failure.example.want
2166 '42\n'
2167
2168 >>> exc_info = failure.exc_info
Collin Winter828f04a2007-08-31 00:04:24 +00002169 >>> raise exc_info[1] # Already has the traceback
Tim Peters19397e52004-08-06 22:02:59 +00002170 Traceback (most recent call last):
2171 ...
2172 KeyError
2173
2174 If the output doesn't match, then a DocTestFailure is raised:
2175
Edward Lopera1ef6112004-08-09 16:14:41 +00002176 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00002177 ... >>> x = 1
2178 ... >>> x
2179 ... 2
2180 ... ''', {}, 'foo', 'foo.py', 0)
2181 >>> case = DocTestCase(test)
2182
2183 >>> try:
2184 ... case.debug()
Guido van Rossumb940e112007-01-10 16:19:56 +00002185 ... except DocTestFailure as f:
2186 ... failure = f
Tim Peters19397e52004-08-06 22:02:59 +00002187
2188 DocTestFailure objects provide access to the test:
2189
2190 >>> failure.test is test
2191 True
2192
2193 As well as to the example:
2194
2195 >>> failure.example.want
2196 '2\n'
2197
2198 and the actual output:
2199
2200 >>> failure.got
2201 '1\n'
2202
2203 """
2204
Jim Fultonf54bad42004-08-28 14:57:56 +00002205 self.setUp()
Edward Loper34fcb142004-08-09 02:45:41 +00002206 runner = DebugRunner(optionflags=self._dt_optionflags,
2207 checker=self._dt_checker, verbose=False)
Edward Loper3a3817f2004-08-19 19:26:06 +00002208 runner.run(self._dt_test)
Jim Fultonf54bad42004-08-28 14:57:56 +00002209 self.tearDown()
Jim Fultona643b652004-07-14 19:06:50 +00002210
2211 def id(self):
Tim Peters19397e52004-08-06 22:02:59 +00002212 return self._dt_test.name
Jim Fultona643b652004-07-14 19:06:50 +00002213
2214 def __repr__(self):
Tim Peters19397e52004-08-06 22:02:59 +00002215 name = self._dt_test.name.split('.')
Jim Fultona643b652004-07-14 19:06:50 +00002216 return "%s (%s)" % (name[-1], '.'.join(name[:-1]))
2217
2218 __str__ = __repr__
2219
2220 def shortDescription(self):
Tim Peters19397e52004-08-06 22:02:59 +00002221 return "Doctest: " + self._dt_test.name
Jim Fultona643b652004-07-14 19:06:50 +00002222
Jim Fultonf54bad42004-08-28 14:57:56 +00002223def DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None,
2224 **options):
Tim Peters8485b562004-08-04 18:46:34 +00002225 """
Tim Peters75dc5e12004-08-22 17:50:45 +00002226 Convert doctest tests for a module to a unittest test suite.
Jim Fultona643b652004-07-14 19:06:50 +00002227
Tim Peters19397e52004-08-06 22:02:59 +00002228 This converts each documentation string in a module that
2229 contains doctest tests to a unittest test case. If any of the
2230 tests in a doc string fail, then the test case fails. An exception
2231 is raised showing the name of the file containing the test and a
Jim Fultona643b652004-07-14 19:06:50 +00002232 (sometimes approximate) line number.
2233
Tim Peters19397e52004-08-06 22:02:59 +00002234 The `module` argument provides the module to be tested. The argument
Jim Fultona643b652004-07-14 19:06:50 +00002235 can be either a module or a module name.
2236
2237 If no argument is given, the calling module is used.
Jim Fultonf54bad42004-08-28 14:57:56 +00002238
2239 A number of options may be provided as keyword arguments:
2240
Jim Fultonf54bad42004-08-28 14:57:56 +00002241 setUp
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002242 A set-up function. This is called before running the
Jim Fultonf54bad42004-08-28 14:57:56 +00002243 tests in each file. The setUp function will be passed a DocTest
2244 object. The setUp function can access the test globals as the
2245 globs attribute of the test passed.
2246
2247 tearDown
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002248 A tear-down function. This is called after running the
Jim Fultonf54bad42004-08-28 14:57:56 +00002249 tests in each file. The tearDown function will be passed a DocTest
2250 object. The tearDown function can access the test globals as the
2251 globs attribute of the test passed.
2252
2253 globs
2254 A dictionary containing initial global variables for the tests.
2255
2256 optionflags
2257 A set of doctest option flags expressed as an integer.
Jim Fultona643b652004-07-14 19:06:50 +00002258 """
Jim Fultona643b652004-07-14 19:06:50 +00002259
Tim Peters8485b562004-08-04 18:46:34 +00002260 if test_finder is None:
2261 test_finder = DocTestFinder()
Tim Peters8485b562004-08-04 18:46:34 +00002262
Tim Peters19397e52004-08-06 22:02:59 +00002263 module = _normalize_module(module)
2264 tests = test_finder.find(module, globs=globs, extraglobs=extraglobs)
2265 if globs is None:
2266 globs = module.__dict__
Jim Fultonf54bad42004-08-28 14:57:56 +00002267 if not tests:
2268 # Why do we want to do this? Because it reveals a bug that might
2269 # otherwise be hidden.
Tim Peters19397e52004-08-06 22:02:59 +00002270 raise ValueError(module, "has no tests")
Tim Petersdb3756d2003-06-29 05:30:48 +00002271
2272 tests.sort()
2273 suite = unittest.TestSuite()
Tim Peters8485b562004-08-04 18:46:34 +00002274 for test in tests:
Tim Peters19397e52004-08-06 22:02:59 +00002275 if len(test.examples) == 0:
2276 continue
Tim Peters8485b562004-08-04 18:46:34 +00002277 if not test.filename:
Tim Petersdb3756d2003-06-29 05:30:48 +00002278 filename = module.__file__
Jim Fulton07a349c2004-08-22 14:10:00 +00002279 if filename[-4:] in (".pyc", ".pyo"):
Tim Petersdb3756d2003-06-29 05:30:48 +00002280 filename = filename[:-1]
Tim Peters8485b562004-08-04 18:46:34 +00002281 test.filename = filename
Jim Fultonf54bad42004-08-28 14:57:56 +00002282 suite.addTest(DocTestCase(test, **options))
Tim Peters19397e52004-08-06 22:02:59 +00002283
2284 return suite
2285
2286class DocFileCase(DocTestCase):
2287
2288 def id(self):
2289 return '_'.join(self._dt_test.name.split('.'))
2290
2291 def __repr__(self):
2292 return self._dt_test.filename
2293 __str__ = __repr__
2294
2295 def format_failure(self, err):
2296 return ('Failed doctest test for %s\n File "%s", line 0\n\n%s'
2297 % (self._dt_test.name, self._dt_test.filename, err)
2298 )
2299
Edward Loper052d0cd2004-09-19 17:19:33 +00002300def DocFileTest(path, module_relative=True, package=None,
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00002301 globs=None, parser=DocTestParser(),
2302 encoding=None, **options):
Tim Peters19397e52004-08-06 22:02:59 +00002303 if globs is None:
2304 globs = {}
Fred Drake7c404a42004-12-21 23:46:34 +00002305 else:
2306 globs = globs.copy()
Tim Peters19397e52004-08-06 22:02:59 +00002307
Edward Loper052d0cd2004-09-19 17:19:33 +00002308 if package and not module_relative:
2309 raise ValueError("Package may only be specified for module-"
2310 "relative paths.")
Tim Petersbab3e992004-09-20 19:52:34 +00002311
Edward Loper052d0cd2004-09-19 17:19:33 +00002312 # Relativize the path.
Guido van Rossum1b81e7b2007-08-29 03:53:53 +00002313 doc, path = _load_testfile(path, package, module_relative,
2314 encoding or "utf-8")
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00002315
Fred Drake7c404a42004-12-21 23:46:34 +00002316 if "__file__" not in globs:
2317 globs["__file__"] = path
Tim Peters19397e52004-08-06 22:02:59 +00002318
Edward Loper052d0cd2004-09-19 17:19:33 +00002319 # Find the file and read it.
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002320 name = os.path.basename(path)
Edward Loper052d0cd2004-09-19 17:19:33 +00002321
2322 # Convert it to a test, and wrap it in a DocFileCase.
Edward Loper498a1862004-09-27 03:42:58 +00002323 test = parser.get_doctest(doc, globs, name, path, 0)
Jim Fultonf54bad42004-08-28 14:57:56 +00002324 return DocFileCase(test, **options)
Tim Peters19397e52004-08-06 22:02:59 +00002325
2326def DocFileSuite(*paths, **kw):
Edward Loper052d0cd2004-09-19 17:19:33 +00002327 """A unittest suite for one or more doctest files.
Tim Petersbab3e992004-09-20 19:52:34 +00002328
Edward Loper052d0cd2004-09-19 17:19:33 +00002329 The path to each doctest file is given as a string; the
2330 interpretation of that string depends on the keyword argument
2331 "module_relative".
Tim Peters19397e52004-08-06 22:02:59 +00002332
2333 A number of options may be provided as keyword arguments:
2334
Edward Loper052d0cd2004-09-19 17:19:33 +00002335 module_relative
2336 If "module_relative" is True, then the given file paths are
2337 interpreted as os-independent module-relative paths. By
2338 default, these paths are relative to the calling module's
2339 directory; but if the "package" argument is specified, then
2340 they are relative to that package. To ensure os-independence,
2341 "filename" should use "/" characters to separate path
2342 segments, and may not be an absolute path (i.e., it may not
2343 begin with "/").
Tim Petersbab3e992004-09-20 19:52:34 +00002344
Edward Loper052d0cd2004-09-19 17:19:33 +00002345 If "module_relative" is False, then the given file paths are
2346 interpreted as os-specific paths. These paths may be absolute
2347 or relative (to the current working directory).
2348
Tim Peters19397e52004-08-06 22:02:59 +00002349 package
Edward Loper052d0cd2004-09-19 17:19:33 +00002350 A Python package or the name of a Python package whose directory
2351 should be used as the base directory for module relative paths.
2352 If "package" is not specified, then the calling module's
2353 directory is used as the base directory for module relative
2354 filenames. It is an error to specify "package" if
2355 "module_relative" is False.
Tim Peters19397e52004-08-06 22:02:59 +00002356
2357 setUp
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002358 A set-up function. This is called before running the
Jim Fultonf54bad42004-08-28 14:57:56 +00002359 tests in each file. The setUp function will be passed a DocTest
2360 object. The setUp function can access the test globals as the
2361 globs attribute of the test passed.
Tim Peters19397e52004-08-06 22:02:59 +00002362
2363 tearDown
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002364 A tear-down function. This is called after running the
Jim Fultonf54bad42004-08-28 14:57:56 +00002365 tests in each file. The tearDown function will be passed a DocTest
2366 object. The tearDown function can access the test globals as the
2367 globs attribute of the test passed.
Tim Peters19397e52004-08-06 22:02:59 +00002368
2369 globs
2370 A dictionary containing initial global variables for the tests.
Jim Fultonf54bad42004-08-28 14:57:56 +00002371
2372 optionflags
Edward Loper498a1862004-09-27 03:42:58 +00002373 A set of doctest option flags expressed as an integer.
2374
2375 parser
2376 A DocTestParser (or subclass) that should be used to extract
2377 tests from the files.
Thomas Wouters4d70c3d2006-06-08 14:42:34 +00002378
2379 encoding
2380 An encoding that will be used to convert the files to unicode.
Tim Peters19397e52004-08-06 22:02:59 +00002381 """
2382 suite = unittest.TestSuite()
2383
2384 # We do this here so that _normalize_module is called at the right
2385 # level. If it were called in DocFileTest, then this function
2386 # would be the caller and we might guess the package incorrectly.
Edward Loper052d0cd2004-09-19 17:19:33 +00002387 if kw.get('module_relative', True):
2388 kw['package'] = _normalize_module(kw.get('package'))
Tim Peters19397e52004-08-06 22:02:59 +00002389
2390 for path in paths:
2391 suite.addTest(DocFileTest(path, **kw))
Jim Fultona643b652004-07-14 19:06:50 +00002392
Tim Petersdb3756d2003-06-29 05:30:48 +00002393 return suite
2394
Tim Peters8485b562004-08-04 18:46:34 +00002395######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00002396## 9. Debugging Support
Tim Peters8485b562004-08-04 18:46:34 +00002397######################################################################
Jim Fultona643b652004-07-14 19:06:50 +00002398
Tim Peters19397e52004-08-06 22:02:59 +00002399def script_from_examples(s):
2400 r"""Extract script from text with examples.
2401
2402 Converts text with examples to a Python script. Example input is
2403 converted to regular code. Example output and all other words
2404 are converted to comments:
2405
2406 >>> text = '''
2407 ... Here are examples of simple math.
2408 ...
2409 ... Python has super accurate integer addition
2410 ...
2411 ... >>> 2 + 2
2412 ... 5
2413 ...
2414 ... And very friendly error messages:
2415 ...
2416 ... >>> 1/0
2417 ... To Infinity
2418 ... And
2419 ... Beyond
2420 ...
2421 ... You can use logic if you want:
2422 ...
2423 ... >>> if 0:
2424 ... ... blah
2425 ... ... blah
2426 ... ...
2427 ...
2428 ... Ho hum
2429 ... '''
2430
Guido van Rossum7131f842007-02-09 20:13:25 +00002431 >>> print(script_from_examples(text))
Edward Lopera5db6002004-08-12 02:41:30 +00002432 # Here are examples of simple math.
Tim Peters19397e52004-08-06 22:02:59 +00002433 #
Edward Lopera5db6002004-08-12 02:41:30 +00002434 # Python has super accurate integer addition
Tim Peters19397e52004-08-06 22:02:59 +00002435 #
2436 2 + 2
2437 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +00002438 ## 5
Tim Peters19397e52004-08-06 22:02:59 +00002439 #
Edward Lopera5db6002004-08-12 02:41:30 +00002440 # And very friendly error messages:
Tim Peters19397e52004-08-06 22:02:59 +00002441 #
2442 1/0
2443 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +00002444 ## To Infinity
2445 ## And
2446 ## Beyond
Tim Peters19397e52004-08-06 22:02:59 +00002447 #
Edward Lopera5db6002004-08-12 02:41:30 +00002448 # You can use logic if you want:
Tim Peters19397e52004-08-06 22:02:59 +00002449 #
2450 if 0:
2451 blah
2452 blah
Tim Peters19397e52004-08-06 22:02:59 +00002453 #
Edward Lopera5db6002004-08-12 02:41:30 +00002454 # Ho hum
Georg Brandlecf93c72005-06-26 23:09:51 +00002455 <BLANKLINE>
Tim Peters19397e52004-08-06 22:02:59 +00002456 """
Edward Loper00f8da72004-08-26 18:05:07 +00002457 output = []
2458 for piece in DocTestParser().parse(s):
2459 if isinstance(piece, Example):
2460 # Add the example's source code (strip trailing NL)
2461 output.append(piece.source[:-1])
2462 # Add the expected output:
2463 want = piece.want
2464 if want:
2465 output.append('# Expected:')
2466 output += ['## '+l for l in want.split('\n')[:-1]]
2467 else:
2468 # Add non-example text.
2469 output += [_comment_line(l)
2470 for l in piece.split('\n')[:-1]]
Tim Peters19397e52004-08-06 22:02:59 +00002471
Edward Loper00f8da72004-08-26 18:05:07 +00002472 # Trim junk on both ends.
2473 while output and output[-1] == '#':
2474 output.pop()
2475 while output and output[0] == '#':
2476 output.pop(0)
2477 # Combine the output, and return it.
Georg Brandl1f149642005-06-26 22:22:31 +00002478 # Add a courtesy newline to prevent exec from choking (see bug #1172785)
2479 return '\n'.join(output) + '\n'
Tim Petersdb3756d2003-06-29 05:30:48 +00002480
2481def testsource(module, name):
Tim Peters19397e52004-08-06 22:02:59 +00002482 """Extract the test sources from a doctest docstring as a script.
Tim Petersdb3756d2003-06-29 05:30:48 +00002483
2484 Provide the module (or dotted name of the module) containing the
Jim Fultona643b652004-07-14 19:06:50 +00002485 test to be debugged and the name (within the module) of the object
2486 with the doc string with tests to be debugged.
Tim Petersdb3756d2003-06-29 05:30:48 +00002487 """
Tim Peters8485b562004-08-04 18:46:34 +00002488 module = _normalize_module(module)
2489 tests = DocTestFinder().find(module)
2490 test = [t for t in tests if t.name == name]
Tim Petersdb3756d2003-06-29 05:30:48 +00002491 if not test:
2492 raise ValueError(name, "not found in tests")
2493 test = test[0]
Tim Peters19397e52004-08-06 22:02:59 +00002494 testsrc = script_from_examples(test.docstring)
Jim Fultona643b652004-07-14 19:06:50 +00002495 return testsrc
Tim Petersdb3756d2003-06-29 05:30:48 +00002496
Jim Fultona643b652004-07-14 19:06:50 +00002497def debug_src(src, pm=False, globs=None):
Tim Peters19397e52004-08-06 22:02:59 +00002498 """Debug a single doctest docstring, in argument `src`'"""
2499 testsrc = script_from_examples(src)
Tim Peters8485b562004-08-04 18:46:34 +00002500 debug_script(testsrc, pm, globs)
Tim Petersdb3756d2003-06-29 05:30:48 +00002501
Jim Fultona643b652004-07-14 19:06:50 +00002502def debug_script(src, pm=False, globs=None):
Tim Peters19397e52004-08-06 22:02:59 +00002503 "Debug a test script. `src` is the script, as a string."
Tim Petersdb3756d2003-06-29 05:30:48 +00002504 import pdb
Tim Petersdb3756d2003-06-29 05:30:48 +00002505
Tim Petersb6a04d62004-08-23 21:37:56 +00002506 # Note that tempfile.NameTemporaryFile() cannot be used. As the
2507 # docs say, a file so created cannot be opened by name a second time
Neal Norwitz01688022007-08-12 00:43:29 +00002508 # on modern Windows boxes, and exec() needs to open and read it.
Tim Petersb6a04d62004-08-23 21:37:56 +00002509 srcfilename = tempfile.mktemp(".py", "doctestdebug")
Tim Peters8485b562004-08-04 18:46:34 +00002510 f = open(srcfilename, 'w')
2511 f.write(src)
2512 f.close()
2513
Tim Petersb6a04d62004-08-23 21:37:56 +00002514 try:
2515 if globs:
2516 globs = globs.copy()
2517 else:
2518 globs = {}
Tim Petersdb3756d2003-06-29 05:30:48 +00002519
Tim Petersb6a04d62004-08-23 21:37:56 +00002520 if pm:
2521 try:
Neal Norwitz01688022007-08-12 00:43:29 +00002522 exec(open(srcfilename).read(), globs, globs)
Tim Petersb6a04d62004-08-23 21:37:56 +00002523 except:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00002524 print(sys.exc_info()[1])
Tim Petersb6a04d62004-08-23 21:37:56 +00002525 pdb.post_mortem(sys.exc_info()[2])
2526 else:
Neal Norwitz01688022007-08-12 00:43:29 +00002527 fp = open(srcfilename)
2528 try:
2529 script = fp.read()
2530 finally:
2531 fp.close()
2532 pdb.run("exec(%r)" % script, globs, globs)
Tim Petersb6a04d62004-08-23 21:37:56 +00002533
2534 finally:
2535 os.remove(srcfilename)
Tim Petersdb3756d2003-06-29 05:30:48 +00002536
Jim Fultona643b652004-07-14 19:06:50 +00002537def debug(module, name, pm=False):
Tim Peters19397e52004-08-06 22:02:59 +00002538 """Debug a single doctest docstring.
Jim Fultona643b652004-07-14 19:06:50 +00002539
2540 Provide the module (or dotted name of the module) containing the
2541 test to be debugged and the name (within the module) of the object
Tim Peters19397e52004-08-06 22:02:59 +00002542 with the docstring with tests to be debugged.
Jim Fultona643b652004-07-14 19:06:50 +00002543 """
Tim Peters8485b562004-08-04 18:46:34 +00002544 module = _normalize_module(module)
Jim Fultona643b652004-07-14 19:06:50 +00002545 testsrc = testsource(module, name)
2546 debug_script(testsrc, pm, module.__dict__)
2547
Tim Peters8485b562004-08-04 18:46:34 +00002548######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00002549## 10. Example Usage
Tim Peters8485b562004-08-04 18:46:34 +00002550######################################################################
Tim Peters8a7d2d52001-01-16 07:10:57 +00002551class _TestClass:
2552 """
2553 A pointless class, for sanity-checking of docstring testing.
2554
2555 Methods:
2556 square()
2557 get()
2558
2559 >>> _TestClass(13).get() + _TestClass(-12).get()
2560 1
2561 >>> hex(_TestClass(13).square().get())
2562 '0xa9'
2563 """
2564
2565 def __init__(self, val):
2566 """val -> _TestClass object with associated value val.
2567
2568 >>> t = _TestClass(123)
Guido van Rossum7131f842007-02-09 20:13:25 +00002569 >>> print(t.get())
Tim Peters8a7d2d52001-01-16 07:10:57 +00002570 123
2571 """
2572
2573 self.val = val
2574
2575 def square(self):
2576 """square() -> square TestClass's associated value
2577
2578 >>> _TestClass(13).square().get()
2579 169
2580 """
2581
2582 self.val = self.val ** 2
2583 return self
2584
2585 def get(self):
2586 """get() -> return TestClass's associated value.
2587
2588 >>> x = _TestClass(-42)
Guido van Rossum7131f842007-02-09 20:13:25 +00002589 >>> print(x.get())
Tim Peters8a7d2d52001-01-16 07:10:57 +00002590 -42
2591 """
2592
2593 return self.val
2594
2595__test__ = {"_TestClass": _TestClass,
2596 "string": r"""
2597 Example of a string object, searched as-is.
2598 >>> x = 1; y = 2
2599 >>> x + y, x * y
2600 (3, 2)
Tim Peters6ebe61f2003-06-27 20:48:05 +00002601 """,
Tim Peters3fa8c202004-08-23 21:43:39 +00002602
Tim Peters6ebe61f2003-06-27 20:48:05 +00002603 "bool-int equivalence": r"""
2604 In 2.2, boolean expressions displayed
2605 0 or 1. By default, we still accept
2606 them. This can be disabled by passing
2607 DONT_ACCEPT_TRUE_FOR_1 to the new
2608 optionflags argument.
2609 >>> 4 == 4
2610 1
2611 >>> 4 == 4
2612 True
2613 >>> 4 > 4
2614 0
2615 >>> 4 > 4
2616 False
2617 """,
Tim Peters3fa8c202004-08-23 21:43:39 +00002618
Tim Peters8485b562004-08-04 18:46:34 +00002619 "blank lines": r"""
Tim Peters3fa8c202004-08-23 21:43:39 +00002620 Blank lines can be marked with <BLANKLINE>:
Guido van Rossum7131f842007-02-09 20:13:25 +00002621 >>> print('foo\n\nbar\n')
Tim Peters3fa8c202004-08-23 21:43:39 +00002622 foo
2623 <BLANKLINE>
2624 bar
2625 <BLANKLINE>
Tim Peters8485b562004-08-04 18:46:34 +00002626 """,
Tim Peters3fa8c202004-08-23 21:43:39 +00002627
2628 "ellipsis": r"""
2629 If the ellipsis flag is used, then '...' can be used to
2630 elide substrings in the desired output:
Guido van Rossum805365e2007-05-07 22:24:25 +00002631 >>> print(list(range(1000))) #doctest: +ELLIPSIS
Tim Peters3fa8c202004-08-23 21:43:39 +00002632 [0, 1, 2, ..., 999]
2633 """,
2634
2635 "whitespace normalization": r"""
2636 If the whitespace normalization flag is used, then
2637 differences in whitespace are ignored.
Guido van Rossum805365e2007-05-07 22:24:25 +00002638 >>> print(list(range(30))) #doctest: +NORMALIZE_WHITESPACE
Tim Peters3fa8c202004-08-23 21:43:39 +00002639 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
2640 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,
2641 27, 28, 29]
2642 """,
2643 }
Tim Peters8485b562004-08-04 18:46:34 +00002644
Tim Peters8a7d2d52001-01-16 07:10:57 +00002645def _test():
Guido van Rossumd8faa362007-04-27 19:54:29 +00002646 testfiles = [arg for arg in sys.argv[1:] if arg and arg[0] != '-']
2647 if testfiles:
2648 for filename in testfiles:
2649 if filename.endswith(".py"):
2650 # It is a module -- insert its dir into sys.path and try to
2651 # import it. If it is part of a package, that possibly won't work
2652 # because of package imports.
2653 dirname, filename = os.path.split(filename)
2654 sys.path.insert(0, dirname)
2655 m = __import__(filename[:-3])
2656 del sys.path[0]
Christian Heimes895627f2007-12-08 17:28:33 +00002657 failures, _ = testmod(m)
Guido van Rossumd8faa362007-04-27 19:54:29 +00002658 else:
Christian Heimes895627f2007-12-08 17:28:33 +00002659 failures, _ = testfile(filename, module_relative=False)
2660 if failures:
2661 return 1
Guido van Rossumd8faa362007-04-27 19:54:29 +00002662 else:
2663 r = unittest.TextTestRunner()
2664 r.run(DocTestSuite())
Christian Heimes895627f2007-12-08 17:28:33 +00002665 return 0
Tim Peters8a7d2d52001-01-16 07:10:57 +00002666
2667if __name__ == "__main__":
Christian Heimes895627f2007-12-08 17:28:33 +00002668 sys.exit(_test())