blob: 6244fae6ccb6cd62564c5e002ac614a1b1851ed6 [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',
Tim Peters1fbf9c52004-09-04 17:21:02 +000057 'IGNORE_EXCEPTION_DETAIL',
Tim Petersba601962004-09-04 15:04:06 +000058 'COMPARISON_FLAGS',
Edward Loper71f55af2004-08-26 01:41:51 +000059 'REPORT_UDIFF',
60 'REPORT_CDIFF',
61 'REPORT_NDIFF',
Jim Fultonf54bad42004-08-28 14:57:56 +000062 'REPORT_ONLY_FIRST_FAILURE',
Tim Petersba601962004-09-04 15:04:06 +000063 'REPORTING_FLAGS',
Edward Loperb7503ff2004-08-19 19:19:03 +000064 # 1. Utility Functions
Tim Peters8485b562004-08-04 18:46:34 +000065 'is_private',
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
Tim Peters19397e52004-08-06 22:02:59 +000098import sys, traceback, inspect, linecache, os, re, types
Jim Fulton356fd192004-08-09 11:34:47 +000099import unittest, difflib, pdb, tempfile
Tim Petersf727c6c2004-08-08 01:48:59 +0000100import warnings
Tim Peters8485b562004-08-04 18:46:34 +0000101from StringIO import StringIO
Tim Peters7402f792001-10-02 03:53:41 +0000102
Tim Petersdd50cb72004-08-23 22:42:55 +0000103# Don't whine about the deprecated is_private function in this
104# module's tests.
105warnings.filterwarnings("ignore", "is_private", DeprecationWarning,
106 __name__, 0)
107
Tim Peters19397e52004-08-06 22:02:59 +0000108# There are 4 basic classes:
109# - Example: a <source, want> pair, plus an intra-docstring line number.
110# - DocTest: a collection of examples, parsed from a docstring, plus
111# info about where the docstring came from (name, filename, lineno).
112# - DocTestFinder: extracts DocTests from a given object's docstring and
113# its contained objects' docstrings.
114# - DocTestRunner: runs DocTest cases, and accumulates statistics.
115#
116# So the basic picture is:
117#
118# list of:
119# +------+ +---------+ +-------+
120# |object| --DocTestFinder-> | DocTest | --DocTestRunner-> |results|
121# +------+ +---------+ +-------+
122# | Example |
123# | ... |
124# | Example |
125# +---------+
126
Edward Loperac20f572004-08-12 02:02:24 +0000127# Option constants.
Tim Peters38330fe2004-08-30 16:19:24 +0000128
Edward Loperac20f572004-08-12 02:02:24 +0000129OPTIONFLAGS_BY_NAME = {}
130def register_optionflag(name):
131 flag = 1 << len(OPTIONFLAGS_BY_NAME)
132 OPTIONFLAGS_BY_NAME[name] = flag
133 return flag
134
135DONT_ACCEPT_TRUE_FOR_1 = register_optionflag('DONT_ACCEPT_TRUE_FOR_1')
136DONT_ACCEPT_BLANKLINE = register_optionflag('DONT_ACCEPT_BLANKLINE')
137NORMALIZE_WHITESPACE = register_optionflag('NORMALIZE_WHITESPACE')
138ELLIPSIS = register_optionflag('ELLIPSIS')
Tim Peters1fbf9c52004-09-04 17:21:02 +0000139IGNORE_EXCEPTION_DETAIL = register_optionflag('IGNORE_EXCEPTION_DETAIL')
Tim Peters38330fe2004-08-30 16:19:24 +0000140
141COMPARISON_FLAGS = (DONT_ACCEPT_TRUE_FOR_1 |
142 DONT_ACCEPT_BLANKLINE |
143 NORMALIZE_WHITESPACE |
Tim Peters1fbf9c52004-09-04 17:21:02 +0000144 ELLIPSIS |
Edward Loper7d88a582004-09-28 05:50:57 +0000145 IGNORE_EXCEPTION_DETAIL)
Tim Peters38330fe2004-08-30 16:19:24 +0000146
Edward Loper71f55af2004-08-26 01:41:51 +0000147REPORT_UDIFF = register_optionflag('REPORT_UDIFF')
148REPORT_CDIFF = register_optionflag('REPORT_CDIFF')
149REPORT_NDIFF = register_optionflag('REPORT_NDIFF')
Edward Lopera89f88d2004-08-26 02:45:51 +0000150REPORT_ONLY_FIRST_FAILURE = register_optionflag('REPORT_ONLY_FIRST_FAILURE')
Edward Loperac20f572004-08-12 02:02:24 +0000151
Tim Peters38330fe2004-08-30 16:19:24 +0000152REPORTING_FLAGS = (REPORT_UDIFF |
153 REPORT_CDIFF |
154 REPORT_NDIFF |
155 REPORT_ONLY_FIRST_FAILURE)
156
Edward Loperac20f572004-08-12 02:02:24 +0000157# Special string markers for use in `want` strings:
158BLANKLINE_MARKER = '<BLANKLINE>'
159ELLIPSIS_MARKER = '...'
160
Tim Peters8485b562004-08-04 18:46:34 +0000161######################################################################
162## Table of Contents
163######################################################################
Edward Loper7c748462004-08-09 02:06:06 +0000164# 1. Utility Functions
165# 2. Example & DocTest -- store test cases
166# 3. DocTest Parser -- extracts examples from strings
167# 4. DocTest Finder -- extracts test cases from objects
168# 5. DocTest Runner -- runs test cases
169# 6. Test Functions -- convenient wrappers for testing
170# 7. Tester Class -- for backwards compatibility
171# 8. Unittest Support
172# 9. Debugging Support
173# 10. Example Usage
Tim Peters8a7d2d52001-01-16 07:10:57 +0000174
Tim Peters8485b562004-08-04 18:46:34 +0000175######################################################################
176## 1. Utility Functions
177######################################################################
Tim Peters8a7d2d52001-01-16 07:10:57 +0000178
179def is_private(prefix, base):
180 """prefix, base -> true iff name prefix + "." + base is "private".
181
182 Prefix may be an empty string, and base does not contain a period.
183 Prefix is ignored (although functions you write conforming to this
184 protocol may make use of it).
185 Return true iff base begins with an (at least one) underscore, but
186 does not both begin and end with (at least) two underscores.
187
188 >>> is_private("a.b", "my_func")
Guido van Rossum77f6a652002-04-03 22:41:51 +0000189 False
Tim Peters8a7d2d52001-01-16 07:10:57 +0000190 >>> is_private("____", "_my_func")
Guido van Rossum77f6a652002-04-03 22:41:51 +0000191 True
Tim Peters8a7d2d52001-01-16 07:10:57 +0000192 >>> is_private("someclass", "__init__")
Guido van Rossum77f6a652002-04-03 22:41:51 +0000193 False
Tim Peters8a7d2d52001-01-16 07:10:57 +0000194 >>> is_private("sometypo", "__init_")
Guido van Rossum77f6a652002-04-03 22:41:51 +0000195 True
Tim Peters8a7d2d52001-01-16 07:10:57 +0000196 >>> is_private("x.y.z", "_")
Guido van Rossum77f6a652002-04-03 22:41:51 +0000197 True
Tim Peters8a7d2d52001-01-16 07:10:57 +0000198 >>> is_private("_x.y.z", "__")
Guido van Rossum77f6a652002-04-03 22:41:51 +0000199 False
Tim Peters8a7d2d52001-01-16 07:10:57 +0000200 >>> is_private("", "") # senseless but consistent
Guido van Rossum77f6a652002-04-03 22:41:51 +0000201 False
Tim Peters8a7d2d52001-01-16 07:10:57 +0000202 """
Tim Petersbafb1fe2004-08-08 01:52:57 +0000203 warnings.warn("is_private is deprecated; it wasn't useful; "
204 "examine DocTestFinder.find() lists instead",
Tim Peters3ddd60a2004-08-08 02:43:33 +0000205 DeprecationWarning, stacklevel=2)
Tim Peters8a7d2d52001-01-16 07:10:57 +0000206 return base[:1] == "_" and not base[:2] == "__" == base[-2:]
207
Tim Peters8485b562004-08-04 18:46:34 +0000208def _extract_future_flags(globs):
209 """
210 Return the compiler-flags associated with the future features that
211 have been imported into the given namespace (globs).
212 """
213 flags = 0
214 for fname in __future__.all_feature_names:
215 feature = globs.get(fname, None)
216 if feature is getattr(__future__, fname):
217 flags |= feature.compiler_flag
218 return flags
Tim Peters7402f792001-10-02 03:53:41 +0000219
Tim Peters8485b562004-08-04 18:46:34 +0000220def _normalize_module(module, depth=2):
221 """
222 Return the module specified by `module`. In particular:
223 - If `module` is a module, then return module.
224 - If `module` is a string, then import and return the
225 module with that name.
226 - If `module` is None, then return the calling module.
227 The calling module is assumed to be the module of
228 the stack frame at the given depth in the call stack.
229 """
230 if inspect.ismodule(module):
231 return module
232 elif isinstance(module, (str, unicode)):
233 return __import__(module, globals(), locals(), ["*"])
234 elif module is None:
235 return sys.modules[sys._getframe(depth).f_globals['__name__']]
236 else:
237 raise TypeError("Expected a module, string, or None")
Tim Peters7402f792001-10-02 03:53:41 +0000238
Edward Loperaacf0832004-08-26 01:19:50 +0000239def _indent(s, indent=4):
Tim Peters8485b562004-08-04 18:46:34 +0000240 """
Edward Loperaacf0832004-08-26 01:19:50 +0000241 Add the given number of space characters to the beginning every
242 non-blank line in `s`, and return the result.
Tim Peters8485b562004-08-04 18:46:34 +0000243 """
Edward Loperaacf0832004-08-26 01:19:50 +0000244 # This regexp matches the start of non-blank lines:
245 return re.sub('(?m)^(?!$)', indent*' ', s)
Tim Peters8a7d2d52001-01-16 07:10:57 +0000246
Edward Loper8e4a34b2004-08-12 02:34:27 +0000247def _exception_traceback(exc_info):
248 """
249 Return a string containing a traceback message for the given
250 exc_info tuple (as returned by sys.exc_info()).
251 """
252 # Get a traceback message.
253 excout = StringIO()
254 exc_type, exc_val, exc_tb = exc_info
255 traceback.print_exception(exc_type, exc_val, exc_tb, file=excout)
256 return excout.getvalue()
257
Tim Peters8485b562004-08-04 18:46:34 +0000258# Override some StringIO methods.
259class _SpoofOut(StringIO):
260 def getvalue(self):
261 result = StringIO.getvalue(self)
262 # If anything at all was written, make sure there's a trailing
263 # newline. There's no way for the expected output to indicate
264 # that a trailing newline is missing.
265 if result and not result.endswith("\n"):
266 result += "\n"
267 # Prevent softspace from screwing up the next test case, in
268 # case they used print with a trailing comma in an example.
269 if hasattr(self, "softspace"):
270 del self.softspace
271 return result
Tim Peters8a7d2d52001-01-16 07:10:57 +0000272
Tim Peters8485b562004-08-04 18:46:34 +0000273 def truncate(self, size=None):
274 StringIO.truncate(self, size)
275 if hasattr(self, "softspace"):
276 del self.softspace
Tim Peters8a7d2d52001-01-16 07:10:57 +0000277
Tim Peters26b3ebb2004-08-19 08:10:08 +0000278# Worst-case linear-time ellipsis matching.
Tim Petersb0a04e12004-08-20 02:08:04 +0000279def _ellipsis_match(want, got):
Tim Petersdc5de3b2004-08-19 14:06:20 +0000280 """
281 Essentially the only subtle case:
Tim Petersb0a04e12004-08-20 02:08:04 +0000282 >>> _ellipsis_match('aa...aa', 'aaa')
Tim Petersdc5de3b2004-08-19 14:06:20 +0000283 False
284 """
Tim Peters26b3ebb2004-08-19 08:10:08 +0000285 if ELLIPSIS_MARKER not in want:
286 return want == got
Tim Petersdc5de3b2004-08-19 14:06:20 +0000287
Tim Peters26b3ebb2004-08-19 08:10:08 +0000288 # Find "the real" strings.
289 ws = want.split(ELLIPSIS_MARKER)
290 assert len(ws) >= 2
Tim Peters26b3ebb2004-08-19 08:10:08 +0000291
Tim Petersdc5de3b2004-08-19 14:06:20 +0000292 # Deal with exact matches possibly needed at one or both ends.
293 startpos, endpos = 0, len(got)
294 w = ws[0]
295 if w: # starts with exact match
296 if got.startswith(w):
297 startpos = len(w)
298 del ws[0]
299 else:
300 return False
301 w = ws[-1]
302 if w: # ends with exact match
303 if got.endswith(w):
304 endpos -= len(w)
305 del ws[-1]
306 else:
307 return False
308
309 if startpos > endpos:
310 # Exact end matches required more characters than we have, as in
Tim Petersb0a04e12004-08-20 02:08:04 +0000311 # _ellipsis_match('aa...aa', 'aaa')
Tim Petersdc5de3b2004-08-19 14:06:20 +0000312 return False
313
314 # For the rest, we only need to find the leftmost non-overlapping
315 # match for each piece. If there's no overall match that way alone,
316 # there's no overall match period.
Tim Peters26b3ebb2004-08-19 08:10:08 +0000317 for w in ws:
318 # w may be '' at times, if there are consecutive ellipses, or
319 # due to an ellipsis at the start or end of `want`. That's OK.
Tim Petersdc5de3b2004-08-19 14:06:20 +0000320 # Search for an empty string succeeds, and doesn't change startpos.
321 startpos = got.find(w, startpos, endpos)
322 if startpos < 0:
Tim Peters26b3ebb2004-08-19 08:10:08 +0000323 return False
Tim Petersdc5de3b2004-08-19 14:06:20 +0000324 startpos += len(w)
Tim Peters26b3ebb2004-08-19 08:10:08 +0000325
Tim Petersdc5de3b2004-08-19 14:06:20 +0000326 return True
Tim Peters26b3ebb2004-08-19 08:10:08 +0000327
Edward Loper00f8da72004-08-26 18:05:07 +0000328def _comment_line(line):
329 "Return a commented form of the given line"
330 line = line.rstrip()
331 if line:
332 return '# '+line
333 else:
334 return '#'
335
Edward Loper2de91ba2004-08-27 02:07:46 +0000336class _OutputRedirectingPdb(pdb.Pdb):
337 """
338 A specialized version of the python debugger that redirects stdout
339 to a given stream when interacting with the user. Stdout is *not*
340 redirected when traced code is executed.
341 """
342 def __init__(self, out):
343 self.__out = out
344 pdb.Pdb.__init__(self)
345
346 def trace_dispatch(self, *args):
347 # Redirect stdout to the given stream.
348 save_stdout = sys.stdout
349 sys.stdout = self.__out
350 # Call Pdb's trace dispatch method.
Tim Petersd7bbbbc2004-11-08 22:30:28 +0000351 try:
352 return pdb.Pdb.trace_dispatch(self, *args)
353 finally:
Tim Petersd7bbbbc2004-11-08 22:30:28 +0000354 sys.stdout = save_stdout
Edward Loper2de91ba2004-08-27 02:07:46 +0000355
Edward Lopera2fc7ec2004-09-21 03:24:24 +0000356# [XX] Normalize with respect to os.path.pardir?
Edward Loper052d0cd2004-09-19 17:19:33 +0000357def _module_relative_path(module, path):
358 if not inspect.ismodule(module):
359 raise TypeError, 'Expected a module: %r' % module
360 if path.startswith('/'):
361 raise ValueError, 'Module-relative files may not have absolute paths'
362
363 # Find the base directory for the path.
364 if hasattr(module, '__file__'):
365 # A normal module/package
366 basedir = os.path.split(module.__file__)[0]
367 elif module.__name__ == '__main__':
368 # An interactive session.
369 if len(sys.argv)>0 and sys.argv[0] != '':
370 basedir = os.path.split(sys.argv[0])[0]
371 else:
372 basedir = os.curdir
373 else:
374 # A module w/o __file__ (this includes builtins)
375 raise ValueError("Can't resolve paths relative to the module " +
376 module + " (it has no __file__)")
377
378 # Combine the base directory and the path.
379 return os.path.join(basedir, *(path.split('/')))
380
Tim Peters8485b562004-08-04 18:46:34 +0000381######################################################################
382## 2. Example & DocTest
383######################################################################
384## - An "example" is a <source, want> pair, where "source" is a
385## fragment of source code, and "want" is the expected output for
386## "source." The Example class also includes information about
387## where the example was extracted from.
388##
Edward Lopera1ef6112004-08-09 16:14:41 +0000389## - A "doctest" is a collection of examples, typically extracted from
390## a string (such as an object's docstring). The DocTest class also
391## includes information about where the string was extracted from.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000392
Tim Peters8485b562004-08-04 18:46:34 +0000393class Example:
394 """
395 A single doctest example, consisting of source code and expected
Edward Lopera1ef6112004-08-09 16:14:41 +0000396 output. `Example` defines the following attributes:
Tim Peters8a7d2d52001-01-16 07:10:57 +0000397
Edward Loper74bca7a2004-08-12 02:27:44 +0000398 - source: A single Python statement, always ending with a newline.
Tim Petersbb431472004-08-09 03:51:46 +0000399 The constructor adds a newline if needed.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000400
Edward Loper74bca7a2004-08-12 02:27:44 +0000401 - want: The expected output from running the source code (either
Tim Petersbb431472004-08-09 03:51:46 +0000402 from stdout, or a traceback in case of exception). `want` ends
403 with a newline unless it's empty, in which case it's an empty
404 string. The constructor adds a newline if needed.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000405
Edward Lopera6b68322004-08-26 00:05:43 +0000406 - exc_msg: The exception message generated by the example, if
407 the example is expected to generate an exception; or `None` if
408 it is not expected to generate an exception. This exception
409 message is compared against the return value of
410 `traceback.format_exception_only()`. `exc_msg` ends with a
411 newline unless it's `None`. The constructor adds a newline
412 if needed.
413
Edward Loper74bca7a2004-08-12 02:27:44 +0000414 - lineno: The line number within the DocTest string containing
Tim Peters8485b562004-08-04 18:46:34 +0000415 this Example where the Example begins. This line number is
416 zero-based, with respect to the beginning of the DocTest.
Edward Loper74bca7a2004-08-12 02:27:44 +0000417
418 - indent: The example's indentation in the DocTest string.
419 I.e., the number of space characters that preceed the
420 example's first prompt.
421
422 - options: A dictionary mapping from option flags to True or
423 False, which is used to override default options for this
424 example. Any option flags not contained in this dictionary
425 are left at their default value (as specified by the
426 DocTestRunner's optionflags). By default, no options are set.
Tim Peters8485b562004-08-04 18:46:34 +0000427 """
Edward Lopera6b68322004-08-26 00:05:43 +0000428 def __init__(self, source, want, exc_msg=None, lineno=0, indent=0,
429 options=None):
Tim Petersbb431472004-08-09 03:51:46 +0000430 # Normalize inputs.
431 if not source.endswith('\n'):
432 source += '\n'
433 if want and not want.endswith('\n'):
434 want += '\n'
Edward Lopera6b68322004-08-26 00:05:43 +0000435 if exc_msg is not None and not exc_msg.endswith('\n'):
436 exc_msg += '\n'
Tim Peters8485b562004-08-04 18:46:34 +0000437 # Store properties.
438 self.source = source
439 self.want = want
440 self.lineno = lineno
Edward Loper74bca7a2004-08-12 02:27:44 +0000441 self.indent = indent
442 if options is None: options = {}
443 self.options = options
Edward Lopera6b68322004-08-26 00:05:43 +0000444 self.exc_msg = exc_msg
Tim Peters8a7d2d52001-01-16 07:10:57 +0000445
Tim Peters8485b562004-08-04 18:46:34 +0000446class DocTest:
447 """
448 A collection of doctest examples that should be run in a single
Edward Lopera1ef6112004-08-09 16:14:41 +0000449 namespace. Each `DocTest` defines the following attributes:
Tim Peters8a7d2d52001-01-16 07:10:57 +0000450
Tim Peters8485b562004-08-04 18:46:34 +0000451 - examples: the list of examples.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000452
Tim Peters8485b562004-08-04 18:46:34 +0000453 - globs: The namespace (aka globals) that the examples should
454 be run in.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000455
Tim Peters8485b562004-08-04 18:46:34 +0000456 - name: A name identifying the DocTest (typically, the name of
457 the object whose docstring this DocTest was extracted from).
Tim Peters8a7d2d52001-01-16 07:10:57 +0000458
Tim Peters8485b562004-08-04 18:46:34 +0000459 - filename: The name of the file that this DocTest was extracted
Edward Lopera1ef6112004-08-09 16:14:41 +0000460 from, or `None` if the filename is unknown.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000461
Tim Peters8485b562004-08-04 18:46:34 +0000462 - lineno: The line number within filename where this DocTest
Edward Lopera1ef6112004-08-09 16:14:41 +0000463 begins, or `None` if the line number is unavailable. This
464 line number is zero-based, with respect to the beginning of
465 the file.
466
467 - docstring: The string that the examples were extracted from,
468 or `None` if the string is unavailable.
Tim Peters8485b562004-08-04 18:46:34 +0000469 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000470 def __init__(self, examples, globs, name, filename, lineno, docstring):
Tim Peters8485b562004-08-04 18:46:34 +0000471 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000472 Create a new DocTest containing the given examples. The
473 DocTest's globals are initialized with a copy of `globs`.
Tim Peters8485b562004-08-04 18:46:34 +0000474 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000475 assert not isinstance(examples, basestring), \
476 "DocTest no longer accepts str; use DocTestParser instead"
477 self.examples = examples
478 self.docstring = docstring
Tim Peters8485b562004-08-04 18:46:34 +0000479 self.globs = globs.copy()
Tim Peters8485b562004-08-04 18:46:34 +0000480 self.name = name
481 self.filename = filename
482 self.lineno = lineno
Tim Peters8485b562004-08-04 18:46:34 +0000483
484 def __repr__(self):
485 if len(self.examples) == 0:
486 examples = 'no examples'
487 elif len(self.examples) == 1:
488 examples = '1 example'
489 else:
490 examples = '%d examples' % len(self.examples)
491 return ('<DocTest %s from %s:%s (%s)>' %
492 (self.name, self.filename, self.lineno, examples))
493
494
495 # This lets us sort tests by name:
496 def __cmp__(self, other):
497 if not isinstance(other, DocTest):
498 return -1
499 return cmp((self.name, self.filename, self.lineno, id(self)),
500 (other.name, other.filename, other.lineno, id(other)))
501
502######################################################################
Edward Loperb7503ff2004-08-19 19:19:03 +0000503## 3. DocTestParser
Edward Loper7c748462004-08-09 02:06:06 +0000504######################################################################
505
Edward Lopera1ef6112004-08-09 16:14:41 +0000506class DocTestParser:
Edward Loper7c748462004-08-09 02:06:06 +0000507 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000508 A class used to parse strings containing doctest examples.
Edward Loper7c748462004-08-09 02:06:06 +0000509 """
Edward Loper8e4a34b2004-08-12 02:34:27 +0000510 # This regular expression is used to find doctest examples in a
511 # string. It defines three groups: `source` is the source code
512 # (including leading indentation and prompts); `indent` is the
513 # indentation of the first (PS1) line of the source code; and
514 # `want` is the expected output (including leading indentation).
Edward Loper7c748462004-08-09 02:06:06 +0000515 _EXAMPLE_RE = re.compile(r'''
Tim Petersd40a92b2004-08-09 03:28:45 +0000516 # Source consists of a PS1 line followed by zero or more PS2 lines.
517 (?P<source>
518 (?:^(?P<indent> [ ]*) >>> .*) # PS1 line
519 (?:\n [ ]* \.\.\. .*)*) # PS2 lines
520 \n?
521 # Want consists of any non-blank lines that do not start with PS1.
522 (?P<want> (?:(?![ ]*$) # Not a blank line
523 (?![ ]*>>>) # Not a line starting with PS1
524 .*$\n? # But any other line
525 )*)
526 ''', re.MULTILINE | re.VERBOSE)
Edward Loper8e4a34b2004-08-12 02:34:27 +0000527
Edward Lopera6b68322004-08-26 00:05:43 +0000528 # A regular expression for handling `want` strings that contain
529 # expected exceptions. It divides `want` into three pieces:
530 # - the traceback header line (`hdr`)
531 # - the traceback stack (`stack`)
532 # - the exception message (`msg`), as generated by
533 # traceback.format_exception_only()
534 # `msg` may have multiple lines. We assume/require that the
535 # exception message is the first non-indented line starting with a word
536 # character following the traceback header line.
537 _EXCEPTION_RE = re.compile(r"""
538 # Grab the traceback header. Different versions of Python have
539 # said different things on the first traceback line.
540 ^(?P<hdr> Traceback\ \(
541 (?: most\ recent\ call\ last
542 | innermost\ last
543 ) \) :
544 )
545 \s* $ # toss trailing whitespace on the header.
546 (?P<stack> .*?) # don't blink: absorb stuff until...
547 ^ (?P<msg> \w+ .*) # a line *starts* with alphanum.
548 """, re.VERBOSE | re.MULTILINE | re.DOTALL)
549
Tim Peters7ea48dd2004-08-13 01:52:59 +0000550 # A callable returning a true value iff its argument is a blank line
551 # or contains a single comment.
Edward Loper8e4a34b2004-08-12 02:34:27 +0000552 _IS_BLANK_OR_COMMENT = re.compile(r'^[ ]*(#.*)?$').match
Edward Loper7c748462004-08-09 02:06:06 +0000553
Edward Loper00f8da72004-08-26 18:05:07 +0000554 def parse(self, string, name='<string>'):
555 """
556 Divide the given string into examples and intervening text,
557 and return them as a list of alternating Examples and strings.
558 Line numbers for the Examples are 0-based. The optional
559 argument `name` is a name identifying this string, and is only
560 used for error messages.
561 """
562 string = string.expandtabs()
563 # If all lines begin with the same indentation, then strip it.
564 min_indent = self._min_indent(string)
565 if min_indent > 0:
566 string = '\n'.join([l[min_indent:] for l in string.split('\n')])
567
568 output = []
569 charno, lineno = 0, 0
570 # Find all doctest examples in the string:
Edward Loper2de91ba2004-08-27 02:07:46 +0000571 for m in self._EXAMPLE_RE.finditer(string):
Edward Loper00f8da72004-08-26 18:05:07 +0000572 # Add the pre-example text to `output`.
573 output.append(string[charno:m.start()])
574 # Update lineno (lines before this example)
575 lineno += string.count('\n', charno, m.start())
576 # Extract info from the regexp match.
577 (source, options, want, exc_msg) = \
578 self._parse_example(m, name, lineno)
579 # Create an Example, and add it to the list.
580 if not self._IS_BLANK_OR_COMMENT(source):
581 output.append( Example(source, want, exc_msg,
582 lineno=lineno,
583 indent=min_indent+len(m.group('indent')),
584 options=options) )
585 # Update lineno (lines inside this example)
586 lineno += string.count('\n', m.start(), m.end())
587 # Update charno.
588 charno = m.end()
589 # Add any remaining post-example text to `output`.
590 output.append(string[charno:])
591 return output
592
Edward Lopera1ef6112004-08-09 16:14:41 +0000593 def get_doctest(self, string, globs, name, filename, lineno):
Edward Loper7c748462004-08-09 02:06:06 +0000594 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000595 Extract all doctest examples from the given string, and
596 collect them into a `DocTest` object.
597
598 `globs`, `name`, `filename`, and `lineno` are attributes for
599 the new `DocTest` object. See the documentation for `DocTest`
600 for more information.
601 """
602 return DocTest(self.get_examples(string, name), globs,
603 name, filename, lineno, string)
604
605 def get_examples(self, string, name='<string>'):
606 """
607 Extract all doctest examples from the given string, and return
608 them as a list of `Example` objects. Line numbers are
609 0-based, because it's most common in doctests that nothing
610 interesting appears on the same line as opening triple-quote,
611 and so the first interesting line is called \"line 1\" then.
612
613 The optional argument `name` is a name identifying this
614 string, and is only used for error messages.
Edward Loper7c748462004-08-09 02:06:06 +0000615 """
Edward Loper00f8da72004-08-26 18:05:07 +0000616 return [x for x in self.parse(string, name)
617 if isinstance(x, Example)]
Edward Loper7c748462004-08-09 02:06:06 +0000618
Edward Loper74bca7a2004-08-12 02:27:44 +0000619 def _parse_example(self, m, name, lineno):
620 """
621 Given a regular expression match from `_EXAMPLE_RE` (`m`),
622 return a pair `(source, want)`, where `source` is the matched
623 example's source code (with prompts and indentation stripped);
624 and `want` is the example's expected output (with indentation
625 stripped).
626
627 `name` is the string's name, and `lineno` is the line number
628 where the example starts; both are used for error messages.
629 """
Edward Loper7c748462004-08-09 02:06:06 +0000630 # Get the example's indentation level.
631 indent = len(m.group('indent'))
632
633 # Divide source into lines; check that they're properly
634 # indented; and then strip their indentation & prompts.
635 source_lines = m.group('source').split('\n')
Edward Lopera1ef6112004-08-09 16:14:41 +0000636 self._check_prompt_blank(source_lines, indent, name, lineno)
Tim Petersc5049152004-08-22 17:34:58 +0000637 self._check_prefix(source_lines[1:], ' '*indent + '.', name, lineno)
Edward Loper7c748462004-08-09 02:06:06 +0000638 source = '\n'.join([sl[indent+4:] for sl in source_lines])
Edward Loper7c748462004-08-09 02:06:06 +0000639
Tim Petersc5049152004-08-22 17:34:58 +0000640 # Divide want into lines; check that it's properly indented; and
641 # then strip the indentation. Spaces before the last newline should
642 # be preserved, so plain rstrip() isn't good enough.
Jim Fulton07a349c2004-08-22 14:10:00 +0000643 want = m.group('want')
Jim Fulton07a349c2004-08-22 14:10:00 +0000644 want_lines = want.split('\n')
Tim Petersc5049152004-08-22 17:34:58 +0000645 if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]):
646 del want_lines[-1] # forget final newline & spaces after it
Edward Lopera1ef6112004-08-09 16:14:41 +0000647 self._check_prefix(want_lines, ' '*indent, name,
Tim Petersc5049152004-08-22 17:34:58 +0000648 lineno + len(source_lines))
Edward Loper7c748462004-08-09 02:06:06 +0000649 want = '\n'.join([wl[indent:] for wl in want_lines])
Edward Loper7c748462004-08-09 02:06:06 +0000650
Edward Lopera6b68322004-08-26 00:05:43 +0000651 # If `want` contains a traceback message, then extract it.
652 m = self._EXCEPTION_RE.match(want)
653 if m:
654 exc_msg = m.group('msg')
655 else:
656 exc_msg = None
657
Edward Loper00f8da72004-08-26 18:05:07 +0000658 # Extract options from the source.
659 options = self._find_options(source, name, lineno)
660
661 return source, options, want, exc_msg
Edward Loper7c748462004-08-09 02:06:06 +0000662
Edward Loper74bca7a2004-08-12 02:27:44 +0000663 # This regular expression looks for option directives in the
664 # source code of an example. Option directives are comments
665 # starting with "doctest:". Warning: this may give false
666 # positives for string-literals that contain the string
667 # "#doctest:". Eliminating these false positives would require
668 # actually parsing the string; but we limit them by ignoring any
669 # line containing "#doctest:" that is *followed* by a quote mark.
670 _OPTION_DIRECTIVE_RE = re.compile(r'#\s*doctest:\s*([^\n\'"]*)$',
671 re.MULTILINE)
672
673 def _find_options(self, source, name, lineno):
674 """
675 Return a dictionary containing option overrides extracted from
676 option directives in the given source string.
677
678 `name` is the string's name, and `lineno` is the line number
679 where the example starts; both are used for error messages.
680 """
681 options = {}
682 # (note: with the current regexp, this will match at most once:)
683 for m in self._OPTION_DIRECTIVE_RE.finditer(source):
684 option_strings = m.group(1).replace(',', ' ').split()
685 for option in option_strings:
686 if (option[0] not in '+-' or
687 option[1:] not in OPTIONFLAGS_BY_NAME):
688 raise ValueError('line %r of the doctest for %s '
689 'has an invalid option: %r' %
690 (lineno+1, name, option))
691 flag = OPTIONFLAGS_BY_NAME[option[1:]]
692 options[flag] = (option[0] == '+')
693 if options and self._IS_BLANK_OR_COMMENT(source):
694 raise ValueError('line %r of the doctest for %s has an option '
695 'directive on a line with no example: %r' %
696 (lineno, name, source))
697 return options
698
Edward Lopera5db6002004-08-12 02:41:30 +0000699 # This regular expression finds the indentation of every non-blank
700 # line in a string.
Edward Loper00f8da72004-08-26 18:05:07 +0000701 _INDENT_RE = re.compile('^([ ]*)(?=\S)', re.MULTILINE)
Edward Lopera5db6002004-08-12 02:41:30 +0000702
703 def _min_indent(self, s):
704 "Return the minimum indentation of any non-blank line in `s`"
Edward Loper00f8da72004-08-26 18:05:07 +0000705 indents = [len(indent) for indent in self._INDENT_RE.findall(s)]
706 if len(indents) > 0:
707 return min(indents)
Tim Petersdd0e4752004-08-09 03:31:56 +0000708 else:
Edward Loper00f8da72004-08-26 18:05:07 +0000709 return 0
Edward Loper7c748462004-08-09 02:06:06 +0000710
Edward Lopera1ef6112004-08-09 16:14:41 +0000711 def _check_prompt_blank(self, lines, indent, name, lineno):
Edward Loper74bca7a2004-08-12 02:27:44 +0000712 """
713 Given the lines of a source string (including prompts and
714 leading indentation), check to make sure that every prompt is
715 followed by a space character. If any line is not followed by
716 a space character, then raise ValueError.
717 """
Edward Loper7c748462004-08-09 02:06:06 +0000718 for i, line in enumerate(lines):
719 if len(line) >= indent+4 and line[indent+3] != ' ':
720 raise ValueError('line %r of the docstring for %s '
721 'lacks blank after %s: %r' %
Edward Lopera1ef6112004-08-09 16:14:41 +0000722 (lineno+i+1, name,
Edward Loper7c748462004-08-09 02:06:06 +0000723 line[indent:indent+3], line))
724
Edward Lopera1ef6112004-08-09 16:14:41 +0000725 def _check_prefix(self, lines, prefix, name, lineno):
Edward Loper74bca7a2004-08-12 02:27:44 +0000726 """
727 Check that every line in the given list starts with the given
728 prefix; if any line does not, then raise a ValueError.
729 """
Edward Loper7c748462004-08-09 02:06:06 +0000730 for i, line in enumerate(lines):
731 if line and not line.startswith(prefix):
732 raise ValueError('line %r of the docstring for %s has '
733 'inconsistent leading whitespace: %r' %
Edward Lopera1ef6112004-08-09 16:14:41 +0000734 (lineno+i+1, name, line))
Edward Loper7c748462004-08-09 02:06:06 +0000735
736
737######################################################################
738## 4. DocTest Finder
Tim Peters8485b562004-08-04 18:46:34 +0000739######################################################################
740
741class DocTestFinder:
742 """
743 A class used to extract the DocTests that are relevant to a given
744 object, from its docstring and the docstrings of its contained
745 objects. Doctests can currently be extracted from the following
746 object types: modules, functions, classes, methods, staticmethods,
747 classmethods, and properties.
Tim Peters8485b562004-08-04 18:46:34 +0000748 """
749
Edward Lopera1ef6112004-08-09 16:14:41 +0000750 def __init__(self, verbose=False, parser=DocTestParser(),
Tim Peters958cc892004-09-13 14:53:28 +0000751 recurse=True, _namefilter=None, exclude_empty=True):
Tim Peters8485b562004-08-04 18:46:34 +0000752 """
753 Create a new doctest finder.
754
Edward Lopera1ef6112004-08-09 16:14:41 +0000755 The optional argument `parser` specifies a class or
Tim Peters19397e52004-08-06 22:02:59 +0000756 function that should be used to create new DocTest objects (or
Tim Peters161c9632004-08-08 03:38:33 +0000757 objects that implement the same interface as DocTest). The
Tim Peters19397e52004-08-06 22:02:59 +0000758 signature for this factory function should match the signature
759 of the DocTest constructor.
760
Tim Peters8485b562004-08-04 18:46:34 +0000761 If the optional argument `recurse` is false, then `find` will
762 only examine the given object, and not any contained objects.
Edward Loper32ddbf72004-09-13 05:47:24 +0000763
Tim Peters958cc892004-09-13 14:53:28 +0000764 If the optional argument `exclude_empty` is false, then `find`
765 will include tests for objects with empty docstrings.
Tim Peters8485b562004-08-04 18:46:34 +0000766 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000767 self._parser = parser
Tim Peters8485b562004-08-04 18:46:34 +0000768 self._verbose = verbose
Tim Peters8485b562004-08-04 18:46:34 +0000769 self._recurse = recurse
Edward Loper32ddbf72004-09-13 05:47:24 +0000770 self._exclude_empty = exclude_empty
Tim Petersf727c6c2004-08-08 01:48:59 +0000771 # _namefilter is undocumented, and exists only for temporary backward-
772 # compatibility support of testmod's deprecated isprivate mess.
773 self._namefilter = _namefilter
Tim Peters8485b562004-08-04 18:46:34 +0000774
775 def find(self, obj, name=None, module=None, globs=None,
Tim Petersf3f57472004-08-08 06:11:48 +0000776 extraglobs=None):
Tim Peters8485b562004-08-04 18:46:34 +0000777 """
778 Return a list of the DocTests that are defined by the given
779 object's docstring, or by any of its contained objects'
780 docstrings.
781
782 The optional parameter `module` is the module that contains
Tim Petersf3f57472004-08-08 06:11:48 +0000783 the given object. If the module is not specified or is None, then
784 the test finder will attempt to automatically determine the
Tim Peters8485b562004-08-04 18:46:34 +0000785 correct module. The object's module is used:
786
787 - As a default namespace, if `globs` is not specified.
788 - To prevent the DocTestFinder from extracting DocTests
Tim Petersf3f57472004-08-08 06:11:48 +0000789 from objects that are imported from other modules.
Tim Peters8485b562004-08-04 18:46:34 +0000790 - To find the name of the file containing the object.
791 - To help find the line number of the object within its
792 file.
793
Tim Petersf3f57472004-08-08 06:11:48 +0000794 Contained objects whose module does not match `module` are ignored.
795
796 If `module` is False, no attempt to find the module will be made.
797 This is obscure, of use mostly in tests: if `module` is False, or
798 is None but cannot be found automatically, then all objects are
799 considered to belong to the (non-existent) module, so all contained
800 objects will (recursively) be searched for doctests.
801
Tim Peters8485b562004-08-04 18:46:34 +0000802 The globals for each DocTest is formed by combining `globs`
803 and `extraglobs` (bindings in `extraglobs` override bindings
804 in `globs`). A new copy of the globals dictionary is created
805 for each DocTest. If `globs` is not specified, then it
806 defaults to the module's `__dict__`, if specified, or {}
807 otherwise. If `extraglobs` is not specified, then it defaults
808 to {}.
809
Tim Peters8485b562004-08-04 18:46:34 +0000810 """
811 # If name was not specified, then extract it from the object.
812 if name is None:
813 name = getattr(obj, '__name__', None)
814 if name is None:
815 raise ValueError("DocTestFinder.find: name must be given "
816 "when obj.__name__ doesn't exist: %r" %
817 (type(obj),))
818
819 # Find the module that contains the given object (if obj is
820 # a module, then module=obj.). Note: this may fail, in which
821 # case module will be None.
Tim Petersf3f57472004-08-08 06:11:48 +0000822 if module is False:
823 module = None
824 elif module is None:
Tim Peters8485b562004-08-04 18:46:34 +0000825 module = inspect.getmodule(obj)
826
827 # Read the module's source code. This is used by
828 # DocTestFinder._find_lineno to find the line number for a
829 # given object's docstring.
830 try:
831 file = inspect.getsourcefile(obj) or inspect.getfile(obj)
832 source_lines = linecache.getlines(file)
833 if not source_lines:
834 source_lines = None
835 except TypeError:
836 source_lines = None
837
838 # Initialize globals, and merge in extraglobs.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000839 if globs is None:
Tim Peters8485b562004-08-04 18:46:34 +0000840 if module is None:
841 globs = {}
842 else:
843 globs = module.__dict__.copy()
844 else:
845 globs = globs.copy()
846 if extraglobs is not None:
847 globs.update(extraglobs)
Tim Peters8a7d2d52001-01-16 07:10:57 +0000848
Tim Peters8485b562004-08-04 18:46:34 +0000849 # Recursively expore `obj`, extracting DocTests.
850 tests = []
Tim Petersf3f57472004-08-08 06:11:48 +0000851 self._find(tests, obj, name, module, source_lines, globs, {})
Tim Peters8485b562004-08-04 18:46:34 +0000852 return tests
853
854 def _filter(self, obj, prefix, base):
855 """
856 Return true if the given object should not be examined.
857 """
Tim Petersf727c6c2004-08-08 01:48:59 +0000858 return (self._namefilter is not None and
859 self._namefilter(prefix, base))
Tim Peters8485b562004-08-04 18:46:34 +0000860
861 def _from_module(self, module, object):
862 """
863 Return true if the given object is defined in the given
864 module.
865 """
866 if module is None:
867 return True
868 elif inspect.isfunction(object):
869 return module.__dict__ is object.func_globals
870 elif inspect.isclass(object):
871 return module.__name__ == object.__module__
872 elif inspect.getmodule(object) is not None:
873 return module is inspect.getmodule(object)
874 elif hasattr(object, '__module__'):
875 return module.__name__ == object.__module__
876 elif isinstance(object, property):
877 return True # [XX] no way not be sure.
878 else:
879 raise ValueError("object must be a class or function")
880
Tim Petersf3f57472004-08-08 06:11:48 +0000881 def _find(self, tests, obj, name, module, source_lines, globs, seen):
Tim Peters8485b562004-08-04 18:46:34 +0000882 """
883 Find tests for the given object and any contained objects, and
884 add them to `tests`.
885 """
886 if self._verbose:
887 print 'Finding tests in %s' % name
888
889 # If we've already processed this object, then ignore it.
890 if id(obj) in seen:
891 return
892 seen[id(obj)] = 1
893
894 # Find a test for this object, and add it to the list of tests.
895 test = self._get_test(obj, name, module, globs, source_lines)
896 if test is not None:
897 tests.append(test)
898
899 # Look for tests in a module's contained objects.
900 if inspect.ismodule(obj) and self._recurse:
901 for valname, val in obj.__dict__.items():
902 # Check if this contained object should be ignored.
903 if self._filter(val, name, valname):
904 continue
905 valname = '%s.%s' % (name, valname)
906 # Recurse to functions & classes.
907 if ((inspect.isfunction(val) or inspect.isclass(val)) and
Tim Petersf3f57472004-08-08 06:11:48 +0000908 self._from_module(module, val)):
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 module's __test__ dictionary.
913 if inspect.ismodule(obj) and self._recurse:
914 for valname, val in getattr(obj, '__test__', {}).items():
915 if not isinstance(valname, basestring):
916 raise ValueError("DocTestFinder.find: __test__ keys "
917 "must be strings: %r" %
918 (type(valname),))
919 if not (inspect.isfunction(val) or inspect.isclass(val) or
920 inspect.ismethod(val) or inspect.ismodule(val) or
921 isinstance(val, basestring)):
922 raise ValueError("DocTestFinder.find: __test__ values "
923 "must be strings, functions, methods, "
924 "classes, or modules: %r" %
925 (type(val),))
Tim Petersc5684782004-09-13 01:07:12 +0000926 valname = '%s.__test__.%s' % (name, valname)
Tim Peters8485b562004-08-04 18:46:34 +0000927 self._find(tests, val, valname, module, source_lines,
Tim Petersf3f57472004-08-08 06:11:48 +0000928 globs, seen)
Tim Peters8485b562004-08-04 18:46:34 +0000929
930 # Look for tests in a class's contained objects.
931 if inspect.isclass(obj) and self._recurse:
932 for valname, val in obj.__dict__.items():
933 # Check if this contained object should be ignored.
934 if self._filter(val, name, valname):
935 continue
936 # Special handling for staticmethod/classmethod.
937 if isinstance(val, staticmethod):
938 val = getattr(obj, valname)
939 if isinstance(val, classmethod):
940 val = getattr(obj, valname).im_func
941
942 # Recurse to methods, properties, and nested classes.
943 if ((inspect.isfunction(val) or inspect.isclass(val) or
Tim Petersf3f57472004-08-08 06:11:48 +0000944 isinstance(val, property)) and
945 self._from_module(module, val)):
Tim Peters8485b562004-08-04 18:46:34 +0000946 valname = '%s.%s' % (name, valname)
947 self._find(tests, val, valname, module, source_lines,
Tim Petersf3f57472004-08-08 06:11:48 +0000948 globs, seen)
Tim Peters8485b562004-08-04 18:46:34 +0000949
950 def _get_test(self, obj, name, module, globs, source_lines):
951 """
952 Return a DocTest for the given object, if it defines a docstring;
953 otherwise, return None.
954 """
955 # Extract the object's docstring. If it doesn't have one,
956 # then return None (no test for this object).
957 if isinstance(obj, basestring):
958 docstring = obj
959 else:
960 try:
961 if obj.__doc__ is None:
Edward Loper32ddbf72004-09-13 05:47:24 +0000962 docstring = ''
963 else:
Jim Fulton7d428782004-10-13 14:15:32 +0000964 docstring = obj.__doc__
965 if not isinstance(docstring, basestring):
966 docstring = str(docstring)
Tim Peters8485b562004-08-04 18:46:34 +0000967 except (TypeError, AttributeError):
Edward Loper32ddbf72004-09-13 05:47:24 +0000968 docstring = ''
Tim Peters8485b562004-08-04 18:46:34 +0000969
970 # Find the docstring's location in the file.
971 lineno = self._find_lineno(obj, source_lines)
972
Edward Loper32ddbf72004-09-13 05:47:24 +0000973 # Don't bother if the docstring is empty.
974 if self._exclude_empty and not docstring:
975 return None
976
Tim Peters8485b562004-08-04 18:46:34 +0000977 # Return a DocTest for this object.
978 if module is None:
979 filename = None
980 else:
981 filename = getattr(module, '__file__', module.__name__)
Jim Fulton07a349c2004-08-22 14:10:00 +0000982 if filename[-4:] in (".pyc", ".pyo"):
983 filename = filename[:-1]
Edward Lopera1ef6112004-08-09 16:14:41 +0000984 return self._parser.get_doctest(docstring, globs, name,
985 filename, lineno)
Tim Peters8485b562004-08-04 18:46:34 +0000986
987 def _find_lineno(self, obj, source_lines):
988 """
989 Return a line number of the given object's docstring. Note:
990 this method assumes that the object has a docstring.
991 """
992 lineno = None
993
994 # Find the line number for modules.
995 if inspect.ismodule(obj):
996 lineno = 0
997
998 # Find the line number for classes.
999 # Note: this could be fooled if a class is defined multiple
1000 # times in a single file.
1001 if inspect.isclass(obj):
1002 if source_lines is None:
1003 return None
1004 pat = re.compile(r'^\s*class\s*%s\b' %
1005 getattr(obj, '__name__', '-'))
1006 for i, line in enumerate(source_lines):
1007 if pat.match(line):
1008 lineno = i
1009 break
1010
1011 # Find the line number for functions & methods.
1012 if inspect.ismethod(obj): obj = obj.im_func
1013 if inspect.isfunction(obj): obj = obj.func_code
1014 if inspect.istraceback(obj): obj = obj.tb_frame
1015 if inspect.isframe(obj): obj = obj.f_code
1016 if inspect.iscode(obj):
1017 lineno = getattr(obj, 'co_firstlineno', None)-1
1018
1019 # Find the line number where the docstring starts. Assume
1020 # that it's the first line that begins with a quote mark.
1021 # Note: this could be fooled by a multiline function
1022 # signature, where a continuation line begins with a quote
1023 # mark.
1024 if lineno is not None:
1025 if source_lines is None:
1026 return lineno+1
1027 pat = re.compile('(^|.*:)\s*\w*("|\')')
1028 for lineno in range(lineno, len(source_lines)):
1029 if pat.match(source_lines[lineno]):
1030 return lineno
1031
1032 # We couldn't find the line number.
1033 return None
1034
1035######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00001036## 5. DocTest Runner
Tim Peters8485b562004-08-04 18:46:34 +00001037######################################################################
1038
Tim Peters8485b562004-08-04 18:46:34 +00001039class DocTestRunner:
1040 """
1041 A class used to run DocTest test cases, and accumulate statistics.
1042 The `run` method is used to process a single DocTest case. It
1043 returns a tuple `(f, t)`, where `t` is the number of test cases
1044 tried, and `f` is the number of test cases that failed.
1045
1046 >>> tests = DocTestFinder().find(_TestClass)
1047 >>> runner = DocTestRunner(verbose=False)
1048 >>> for test in tests:
1049 ... print runner.run(test)
1050 (0, 2)
1051 (0, 1)
1052 (0, 2)
1053 (0, 2)
1054
1055 The `summarize` method prints a summary of all the test cases that
1056 have been run by the runner, and returns an aggregated `(f, t)`
1057 tuple:
1058
1059 >>> runner.summarize(verbose=1)
1060 4 items passed all tests:
1061 2 tests in _TestClass
1062 2 tests in _TestClass.__init__
1063 2 tests in _TestClass.get
1064 1 tests in _TestClass.square
1065 7 tests in 4 items.
1066 7 passed and 0 failed.
1067 Test passed.
1068 (0, 7)
1069
1070 The aggregated number of tried examples and failed examples is
1071 also available via the `tries` and `failures` attributes:
1072
1073 >>> runner.tries
1074 7
1075 >>> runner.failures
1076 0
1077
1078 The comparison between expected outputs and actual outputs is done
Edward Loper34fcb142004-08-09 02:45:41 +00001079 by an `OutputChecker`. This comparison may be customized with a
1080 number of option flags; see the documentation for `testmod` for
1081 more information. If the option flags are insufficient, then the
1082 comparison may also be customized by passing a subclass of
1083 `OutputChecker` to the constructor.
Tim Peters8485b562004-08-04 18:46:34 +00001084
1085 The test runner's display output can be controlled in two ways.
1086 First, an output function (`out) can be passed to
1087 `TestRunner.run`; this function will be called with strings that
1088 should be displayed. It defaults to `sys.stdout.write`. If
1089 capturing the output is not sufficient, then the display output
1090 can be also customized by subclassing DocTestRunner, and
1091 overriding the methods `report_start`, `report_success`,
1092 `report_unexpected_exception`, and `report_failure`.
1093 """
1094 # This divider string is used to separate failure messages, and to
1095 # separate sections of the summary.
1096 DIVIDER = "*" * 70
1097
Edward Loper34fcb142004-08-09 02:45:41 +00001098 def __init__(self, checker=None, verbose=None, optionflags=0):
Tim Peters8485b562004-08-04 18:46:34 +00001099 """
1100 Create a new test runner.
1101
Edward Loper34fcb142004-08-09 02:45:41 +00001102 Optional keyword arg `checker` is the `OutputChecker` that
1103 should be used to compare the expected outputs and actual
1104 outputs of doctest examples.
1105
Tim Peters8485b562004-08-04 18:46:34 +00001106 Optional keyword arg 'verbose' prints lots of stuff if true,
1107 only failures if false; by default, it's true iff '-v' is in
1108 sys.argv.
1109
1110 Optional argument `optionflags` can be used to control how the
1111 test runner compares expected output to actual output, and how
1112 it displays failures. See the documentation for `testmod` for
1113 more information.
1114 """
Edward Loper34fcb142004-08-09 02:45:41 +00001115 self._checker = checker or OutputChecker()
Tim Peters8a7d2d52001-01-16 07:10:57 +00001116 if verbose is None:
Tim Peters8485b562004-08-04 18:46:34 +00001117 verbose = '-v' in sys.argv
1118 self._verbose = verbose
Tim Peters6ebe61f2003-06-27 20:48:05 +00001119 self.optionflags = optionflags
Jim Fulton07a349c2004-08-22 14:10:00 +00001120 self.original_optionflags = optionflags
Tim Peters6ebe61f2003-06-27 20:48:05 +00001121
Tim Peters8485b562004-08-04 18:46:34 +00001122 # Keep track of the examples we've run.
1123 self.tries = 0
1124 self.failures = 0
1125 self._name2ft = {}
Tim Peters8a7d2d52001-01-16 07:10:57 +00001126
Tim Peters8485b562004-08-04 18:46:34 +00001127 # Create a fake output target for capturing doctest output.
1128 self._fakeout = _SpoofOut()
Tim Peters4fd9e2f2001-08-18 00:05:50 +00001129
Tim Peters8485b562004-08-04 18:46:34 +00001130 #/////////////////////////////////////////////////////////////////
Tim Peters8485b562004-08-04 18:46:34 +00001131 # Reporting methods
1132 #/////////////////////////////////////////////////////////////////
Tim Peters17111f32001-10-03 04:08:26 +00001133
Tim Peters8485b562004-08-04 18:46:34 +00001134 def report_start(self, out, test, example):
Tim Peters8a7d2d52001-01-16 07:10:57 +00001135 """
Tim Peters8485b562004-08-04 18:46:34 +00001136 Report that the test runner is about to process the given
1137 example. (Only displays a message if verbose=True)
1138 """
1139 if self._verbose:
Edward Loperaacf0832004-08-26 01:19:50 +00001140 if example.want:
1141 out('Trying:\n' + _indent(example.source) +
1142 'Expecting:\n' + _indent(example.want))
1143 else:
1144 out('Trying:\n' + _indent(example.source) +
1145 'Expecting nothing\n')
Tim Peters8a7d2d52001-01-16 07:10:57 +00001146
Tim Peters8485b562004-08-04 18:46:34 +00001147 def report_success(self, out, test, example, got):
1148 """
1149 Report that the given example ran successfully. (Only
1150 displays a message if verbose=True)
1151 """
1152 if self._verbose:
1153 out("ok\n")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001154
Tim Peters8485b562004-08-04 18:46:34 +00001155 def report_failure(self, out, test, example, got):
1156 """
1157 Report that the given example failed.
1158 """
Edward Loper8e4a34b2004-08-12 02:34:27 +00001159 out(self._failure_header(test, example) +
Edward Loperca9111e2004-08-26 03:00:24 +00001160 self._checker.output_difference(example, got, self.optionflags))
Tim Peters7402f792001-10-02 03:53:41 +00001161
Tim Peters8485b562004-08-04 18:46:34 +00001162 def report_unexpected_exception(self, out, test, example, exc_info):
1163 """
1164 Report that the given example raised an unexpected exception.
1165 """
Edward Loper8e4a34b2004-08-12 02:34:27 +00001166 out(self._failure_header(test, example) +
Edward Loperaacf0832004-08-26 01:19:50 +00001167 'Exception raised:\n' + _indent(_exception_traceback(exc_info)))
Tim Peters7402f792001-10-02 03:53:41 +00001168
Edward Loper8e4a34b2004-08-12 02:34:27 +00001169 def _failure_header(self, test, example):
Jim Fulton07a349c2004-08-22 14:10:00 +00001170 out = [self.DIVIDER]
1171 if test.filename:
1172 if test.lineno is not None and example.lineno is not None:
1173 lineno = test.lineno + example.lineno + 1
1174 else:
1175 lineno = '?'
1176 out.append('File "%s", line %s, in %s' %
1177 (test.filename, lineno, test.name))
Tim Peters8485b562004-08-04 18:46:34 +00001178 else:
Jim Fulton07a349c2004-08-22 14:10:00 +00001179 out.append('Line %s, in %s' % (example.lineno+1, test.name))
1180 out.append('Failed example:')
1181 source = example.source
Edward Loperaacf0832004-08-26 01:19:50 +00001182 out.append(_indent(source))
1183 return '\n'.join(out)
Tim Peters7402f792001-10-02 03:53:41 +00001184
Tim Peters8485b562004-08-04 18:46:34 +00001185 #/////////////////////////////////////////////////////////////////
1186 # DocTest Running
1187 #/////////////////////////////////////////////////////////////////
Tim Peters7402f792001-10-02 03:53:41 +00001188
Tim Peters8485b562004-08-04 18:46:34 +00001189 def __run(self, test, compileflags, out):
Tim Peters8a7d2d52001-01-16 07:10:57 +00001190 """
Tim Peters8485b562004-08-04 18:46:34 +00001191 Run the examples in `test`. Write the outcome of each example
1192 with one of the `DocTestRunner.report_*` methods, using the
1193 writer function `out`. `compileflags` is the set of compiler
1194 flags that should be used to execute examples. Return a tuple
1195 `(f, t)`, where `t` is the number of examples tried, and `f`
1196 is the number of examples that failed. The examples are run
1197 in the namespace `test.globs`.
1198 """
1199 # Keep track of the number of failures and tries.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001200 failures = tries = 0
Tim Peters8485b562004-08-04 18:46:34 +00001201
1202 # Save the option flags (since option directives can be used
1203 # to modify them).
1204 original_optionflags = self.optionflags
1205
Tim Peters1fbf9c52004-09-04 17:21:02 +00001206 SUCCESS, FAILURE, BOOM = range(3) # `outcome` state
1207
1208 check = self._checker.check_output
1209
Tim Peters8485b562004-08-04 18:46:34 +00001210 # Process each example.
Edward Loper2de91ba2004-08-27 02:07:46 +00001211 for examplenum, example in enumerate(test.examples):
1212
Edward Lopera89f88d2004-08-26 02:45:51 +00001213 # If REPORT_ONLY_FIRST_FAILURE is set, then supress
1214 # reporting after the first failure.
1215 quiet = (self.optionflags & REPORT_ONLY_FIRST_FAILURE and
1216 failures > 0)
1217
Edward Loper74bca7a2004-08-12 02:27:44 +00001218 # Merge in the example's options.
1219 self.optionflags = original_optionflags
1220 if example.options:
1221 for (optionflag, val) in example.options.items():
1222 if val:
1223 self.optionflags |= optionflag
1224 else:
1225 self.optionflags &= ~optionflag
Tim Peters8485b562004-08-04 18:46:34 +00001226
1227 # Record that we started this example.
1228 tries += 1
Edward Lopera89f88d2004-08-26 02:45:51 +00001229 if not quiet:
1230 self.report_start(out, test, example)
Tim Peters8485b562004-08-04 18:46:34 +00001231
Edward Loper2de91ba2004-08-27 02:07:46 +00001232 # Use a special filename for compile(), so we can retrieve
1233 # the source code during interactive debugging (see
1234 # __patched_linecache_getlines).
1235 filename = '<doctest %s[%d]>' % (test.name, examplenum)
1236
Tim Peters8485b562004-08-04 18:46:34 +00001237 # Run the example in the given context (globs), and record
1238 # any exception that gets raised. (But don't intercept
1239 # keyboard interrupts.)
1240 try:
Tim Peters208ca702004-08-09 04:12:36 +00001241 # Don't blink! This is where the user's code gets run.
Edward Loper2de91ba2004-08-27 02:07:46 +00001242 exec compile(example.source, filename, "single",
Tim Peters8485b562004-08-04 18:46:34 +00001243 compileflags, 1) in test.globs
Edward Loper2de91ba2004-08-27 02:07:46 +00001244 self.debugger.set_continue() # ==== Example Finished ====
Tim Peters8485b562004-08-04 18:46:34 +00001245 exception = None
1246 except KeyboardInterrupt:
1247 raise
1248 except:
1249 exception = sys.exc_info()
Edward Loper2de91ba2004-08-27 02:07:46 +00001250 self.debugger.set_continue() # ==== Example Finished ====
Tim Peters8485b562004-08-04 18:46:34 +00001251
Tim Peters208ca702004-08-09 04:12:36 +00001252 got = self._fakeout.getvalue() # the actual output
Tim Peters8485b562004-08-04 18:46:34 +00001253 self._fakeout.truncate(0)
Tim Peters1fbf9c52004-09-04 17:21:02 +00001254 outcome = FAILURE # guilty until proved innocent or insane
Tim Peters8485b562004-08-04 18:46:34 +00001255
1256 # If the example executed without raising any exceptions,
Tim Peters1fbf9c52004-09-04 17:21:02 +00001257 # verify its output.
Tim Peters8485b562004-08-04 18:46:34 +00001258 if exception is None:
Tim Peters1fbf9c52004-09-04 17:21:02 +00001259 if check(example.want, got, self.optionflags):
1260 outcome = SUCCESS
Tim Peters8485b562004-08-04 18:46:34 +00001261
Tim Peters1fbf9c52004-09-04 17:21:02 +00001262 # The example raised an exception: check if it was expected.
Tim Peters8485b562004-08-04 18:46:34 +00001263 else:
1264 exc_info = sys.exc_info()
1265 exc_msg = traceback.format_exception_only(*exc_info[:2])[-1]
Tim Peters1fbf9c52004-09-04 17:21:02 +00001266 if not quiet:
1267 got += _exception_traceback(exc_info)
Tim Peters8485b562004-08-04 18:46:34 +00001268
Tim Peters1fbf9c52004-09-04 17:21:02 +00001269 # If `example.exc_msg` is None, then we weren't expecting
1270 # an exception.
Edward Lopera6b68322004-08-26 00:05:43 +00001271 if example.exc_msg is None:
Tim Peters1fbf9c52004-09-04 17:21:02 +00001272 outcome = BOOM
1273
1274 # We expected an exception: see whether it matches.
1275 elif check(example.exc_msg, exc_msg, self.optionflags):
1276 outcome = SUCCESS
1277
1278 # Another chance if they didn't care about the detail.
1279 elif self.optionflags & IGNORE_EXCEPTION_DETAIL:
1280 m1 = re.match(r'[^:]*:', example.exc_msg)
1281 m2 = re.match(r'[^:]*:', exc_msg)
1282 if m1 and m2 and check(m1.group(0), m2.group(0),
1283 self.optionflags):
1284 outcome = SUCCESS
1285
1286 # Report the outcome.
1287 if outcome is SUCCESS:
1288 if not quiet:
1289 self.report_success(out, test, example, got)
1290 elif outcome is FAILURE:
1291 if not quiet:
1292 self.report_failure(out, test, example, got)
1293 failures += 1
1294 elif outcome is BOOM:
1295 if not quiet:
1296 self.report_unexpected_exception(out, test, example,
1297 exc_info)
1298 failures += 1
1299 else:
1300 assert False, ("unknown outcome", outcome)
Tim Peters8485b562004-08-04 18:46:34 +00001301
1302 # Restore the option flags (in case they were modified)
1303 self.optionflags = original_optionflags
1304
1305 # Record and return the number of failures and tries.
1306 self.__record_outcome(test, failures, tries)
Tim Peters8a7d2d52001-01-16 07:10:57 +00001307 return failures, tries
1308
Tim Peters8485b562004-08-04 18:46:34 +00001309 def __record_outcome(self, test, f, t):
1310 """
1311 Record the fact that the given DocTest (`test`) generated `f`
1312 failures out of `t` tried examples.
1313 """
1314 f2, t2 = self._name2ft.get(test.name, (0,0))
1315 self._name2ft[test.name] = (f+f2, t+t2)
1316 self.failures += f
1317 self.tries += t
1318
Edward Loper2de91ba2004-08-27 02:07:46 +00001319 __LINECACHE_FILENAME_RE = re.compile(r'<doctest '
1320 r'(?P<name>[\w\.]+)'
1321 r'\[(?P<examplenum>\d+)\]>$')
1322 def __patched_linecache_getlines(self, filename):
1323 m = self.__LINECACHE_FILENAME_RE.match(filename)
1324 if m and m.group('name') == self.test.name:
1325 example = self.test.examples[int(m.group('examplenum'))]
1326 return example.source.splitlines(True)
1327 else:
1328 return self.save_linecache_getlines(filename)
1329
Tim Peters8485b562004-08-04 18:46:34 +00001330 def run(self, test, compileflags=None, out=None, clear_globs=True):
1331 """
1332 Run the examples in `test`, and display the results using the
1333 writer function `out`.
1334
1335 The examples are run in the namespace `test.globs`. If
1336 `clear_globs` is true (the default), then this namespace will
1337 be cleared after the test runs, to help with garbage
1338 collection. If you would like to examine the namespace after
1339 the test completes, then use `clear_globs=False`.
1340
1341 `compileflags` gives the set of flags that should be used by
1342 the Python compiler when running the examples. If not
1343 specified, then it will default to the set of future-import
1344 flags that apply to `globs`.
1345
1346 The output of each example is checked using
1347 `DocTestRunner.check_output`, and the results are formatted by
1348 the `DocTestRunner.report_*` methods.
1349 """
Edward Loper2de91ba2004-08-27 02:07:46 +00001350 self.test = test
1351
Tim Peters8485b562004-08-04 18:46:34 +00001352 if compileflags is None:
1353 compileflags = _extract_future_flags(test.globs)
Jim Fulton356fd192004-08-09 11:34:47 +00001354
Tim Peters6c542b72004-08-09 16:43:36 +00001355 save_stdout = sys.stdout
Tim Peters8485b562004-08-04 18:46:34 +00001356 if out is None:
Tim Peters6c542b72004-08-09 16:43:36 +00001357 out = save_stdout.write
1358 sys.stdout = self._fakeout
Tim Peters8485b562004-08-04 18:46:34 +00001359
Edward Loper2de91ba2004-08-27 02:07:46 +00001360 # Patch pdb.set_trace to restore sys.stdout during interactive
1361 # debugging (so it's not still redirected to self._fakeout).
1362 # Note that the interactive output will go to *our*
1363 # save_stdout, even if that's not the real sys.stdout; this
1364 # allows us to write test cases for the set_trace behavior.
Tim Peters6c542b72004-08-09 16:43:36 +00001365 save_set_trace = pdb.set_trace
Edward Loper2de91ba2004-08-27 02:07:46 +00001366 self.debugger = _OutputRedirectingPdb(save_stdout)
1367 self.debugger.reset()
1368 pdb.set_trace = self.debugger.set_trace
1369
1370 # Patch linecache.getlines, so we can see the example's source
1371 # when we're inside the debugger.
1372 self.save_linecache_getlines = linecache.getlines
1373 linecache.getlines = self.__patched_linecache_getlines
1374
Tim Peters8485b562004-08-04 18:46:34 +00001375 try:
Tim Peters8485b562004-08-04 18:46:34 +00001376 return self.__run(test, compileflags, out)
1377 finally:
Tim Peters6c542b72004-08-09 16:43:36 +00001378 sys.stdout = save_stdout
1379 pdb.set_trace = save_set_trace
Edward Loper2de91ba2004-08-27 02:07:46 +00001380 linecache.getlines = self.save_linecache_getlines
Tim Peters8485b562004-08-04 18:46:34 +00001381 if clear_globs:
1382 test.globs.clear()
1383
1384 #/////////////////////////////////////////////////////////////////
1385 # Summarization
1386 #/////////////////////////////////////////////////////////////////
Tim Peters8a7d2d52001-01-16 07:10:57 +00001387 def summarize(self, verbose=None):
1388 """
Tim Peters8485b562004-08-04 18:46:34 +00001389 Print a summary of all the test cases that have been run by
1390 this DocTestRunner, and return a tuple `(f, t)`, where `f` is
1391 the total number of failed examples, and `t` is the total
1392 number of tried examples.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001393
Tim Peters8485b562004-08-04 18:46:34 +00001394 The optional `verbose` argument controls how detailed the
1395 summary is. If the verbosity is not specified, then the
1396 DocTestRunner's verbosity is used.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001397 """
Tim Peters8a7d2d52001-01-16 07:10:57 +00001398 if verbose is None:
Tim Peters8485b562004-08-04 18:46:34 +00001399 verbose = self._verbose
Tim Peters8a7d2d52001-01-16 07:10:57 +00001400 notests = []
1401 passed = []
1402 failed = []
1403 totalt = totalf = 0
Tim Peters8485b562004-08-04 18:46:34 +00001404 for x in self._name2ft.items():
Tim Peters8a7d2d52001-01-16 07:10:57 +00001405 name, (f, t) = x
1406 assert f <= t
Tim Peters8485b562004-08-04 18:46:34 +00001407 totalt += t
1408 totalf += f
Tim Peters8a7d2d52001-01-16 07:10:57 +00001409 if t == 0:
1410 notests.append(name)
1411 elif f == 0:
1412 passed.append( (name, t) )
1413 else:
1414 failed.append(x)
1415 if verbose:
1416 if notests:
1417 print len(notests), "items had no tests:"
1418 notests.sort()
1419 for thing in notests:
1420 print " ", thing
1421 if passed:
1422 print len(passed), "items passed all tests:"
1423 passed.sort()
1424 for thing, count in passed:
1425 print " %3d tests in %s" % (count, thing)
1426 if failed:
Tim Peters8485b562004-08-04 18:46:34 +00001427 print self.DIVIDER
Tim Peters8a7d2d52001-01-16 07:10:57 +00001428 print len(failed), "items had failures:"
1429 failed.sort()
1430 for thing, (f, t) in failed:
1431 print " %3d of %3d in %s" % (f, t, thing)
1432 if verbose:
Tim Peters8485b562004-08-04 18:46:34 +00001433 print totalt, "tests in", len(self._name2ft), "items."
Tim Peters8a7d2d52001-01-16 07:10:57 +00001434 print totalt - totalf, "passed and", totalf, "failed."
1435 if totalf:
1436 print "***Test Failed***", totalf, "failures."
1437 elif verbose:
1438 print "Test passed."
1439 return totalf, totalt
1440
Tim Peters82076ef2004-09-13 00:52:51 +00001441 #/////////////////////////////////////////////////////////////////
1442 # Backward compatibility cruft to maintain doctest.master.
1443 #/////////////////////////////////////////////////////////////////
1444 def merge(self, other):
1445 d = self._name2ft
1446 for name, (f, t) in other._name2ft.items():
1447 if name in d:
1448 print "*** DocTestRunner.merge: '" + name + "' in both" \
1449 " testers; summing outcomes."
1450 f2, t2 = d[name]
1451 f = f + f2
1452 t = t + t2
1453 d[name] = f, t
1454
Edward Loper34fcb142004-08-09 02:45:41 +00001455class OutputChecker:
1456 """
1457 A class used to check the whether the actual output from a doctest
1458 example matches the expected output. `OutputChecker` defines two
1459 methods: `check_output`, which compares a given pair of outputs,
1460 and returns true if they match; and `output_difference`, which
1461 returns a string describing the differences between two outputs.
1462 """
1463 def check_output(self, want, got, optionflags):
1464 """
Edward Loper74bca7a2004-08-12 02:27:44 +00001465 Return True iff the actual output from an example (`got`)
1466 matches the expected output (`want`). These strings are
1467 always considered to match if they are identical; but
1468 depending on what option flags the test runner is using,
1469 several non-exact match types are also possible. See the
1470 documentation for `TestRunner` for more information about
1471 option flags.
Edward Loper34fcb142004-08-09 02:45:41 +00001472 """
1473 # Handle the common case first, for efficiency:
1474 # if they're string-identical, always return true.
1475 if got == want:
1476 return True
1477
1478 # The values True and False replaced 1 and 0 as the return
1479 # value for boolean comparisons in Python 2.3.
1480 if not (optionflags & DONT_ACCEPT_TRUE_FOR_1):
1481 if (got,want) == ("True\n", "1\n"):
1482 return True
1483 if (got,want) == ("False\n", "0\n"):
1484 return True
1485
1486 # <BLANKLINE> can be used as a special sequence to signify a
1487 # blank line, unless the DONT_ACCEPT_BLANKLINE flag is used.
1488 if not (optionflags & DONT_ACCEPT_BLANKLINE):
1489 # Replace <BLANKLINE> in want with a blank line.
1490 want = re.sub('(?m)^%s\s*?$' % re.escape(BLANKLINE_MARKER),
1491 '', want)
1492 # If a line in got contains only spaces, then remove the
1493 # spaces.
1494 got = re.sub('(?m)^\s*?$', '', got)
1495 if got == want:
1496 return True
1497
1498 # This flag causes doctest to ignore any differences in the
1499 # contents of whitespace strings. Note that this can be used
Tim Peters3fa8c202004-08-23 21:43:39 +00001500 # in conjunction with the ELLIPSIS flag.
Tim Peters1cf3aa62004-08-19 06:49:33 +00001501 if optionflags & NORMALIZE_WHITESPACE:
Edward Loper34fcb142004-08-09 02:45:41 +00001502 got = ' '.join(got.split())
1503 want = ' '.join(want.split())
1504 if got == want:
1505 return True
1506
1507 # The ELLIPSIS flag says to let the sequence "..." in `want`
Tim Peters26b3ebb2004-08-19 08:10:08 +00001508 # match any substring in `got`.
Tim Peters1cf3aa62004-08-19 06:49:33 +00001509 if optionflags & ELLIPSIS:
Tim Petersb0a04e12004-08-20 02:08:04 +00001510 if _ellipsis_match(want, got):
Edward Loper34fcb142004-08-09 02:45:41 +00001511 return True
1512
1513 # We didn't find any match; return false.
1514 return False
1515
Tim Petersc6cbab02004-08-22 19:43:28 +00001516 # Should we do a fancy diff?
1517 def _do_a_fancy_diff(self, want, got, optionflags):
1518 # Not unless they asked for a fancy diff.
Edward Loper71f55af2004-08-26 01:41:51 +00001519 if not optionflags & (REPORT_UDIFF |
1520 REPORT_CDIFF |
1521 REPORT_NDIFF):
Tim Petersc6cbab02004-08-22 19:43:28 +00001522 return False
Tim Peters5b799c12004-08-26 05:21:59 +00001523
Tim Petersc6cbab02004-08-22 19:43:28 +00001524 # If expected output uses ellipsis, a meaningful fancy diff is
Tim Peters5b799c12004-08-26 05:21:59 +00001525 # too hard ... or maybe not. In two real-life failures Tim saw,
1526 # a diff was a major help anyway, so this is commented out.
1527 # [todo] _ellipsis_match() knows which pieces do and don't match,
1528 # and could be the basis for a kick-ass diff in this case.
1529 ##if optionflags & ELLIPSIS and ELLIPSIS_MARKER in want:
1530 ## return False
1531
Tim Petersc6cbab02004-08-22 19:43:28 +00001532 # ndiff does intraline difference marking, so can be useful even
Tim Peters5b799c12004-08-26 05:21:59 +00001533 # for 1-line differences.
Edward Loper71f55af2004-08-26 01:41:51 +00001534 if optionflags & REPORT_NDIFF:
Tim Petersc6cbab02004-08-22 19:43:28 +00001535 return True
Tim Peters5b799c12004-08-26 05:21:59 +00001536
Tim Petersc6cbab02004-08-22 19:43:28 +00001537 # The other diff types need at least a few lines to be helpful.
1538 return want.count('\n') > 2 and got.count('\n') > 2
1539
Edward Loperca9111e2004-08-26 03:00:24 +00001540 def output_difference(self, example, got, optionflags):
Edward Loper34fcb142004-08-09 02:45:41 +00001541 """
1542 Return a string describing the differences between the
Edward Loperca9111e2004-08-26 03:00:24 +00001543 expected output for a given example (`example`) and the actual
1544 output (`got`). `optionflags` is the set of option flags used
1545 to compare `want` and `got`.
Edward Loper34fcb142004-08-09 02:45:41 +00001546 """
Edward Loperca9111e2004-08-26 03:00:24 +00001547 want = example.want
Edward Loper68ba9a62004-08-12 02:43:49 +00001548 # If <BLANKLINE>s are being used, then replace blank lines
1549 # with <BLANKLINE> in the actual output string.
Edward Loper34fcb142004-08-09 02:45:41 +00001550 if not (optionflags & DONT_ACCEPT_BLANKLINE):
Edward Loper68ba9a62004-08-12 02:43:49 +00001551 got = re.sub('(?m)^[ ]*(?=\n)', BLANKLINE_MARKER, got)
Edward Loper34fcb142004-08-09 02:45:41 +00001552
Tim Peters5b799c12004-08-26 05:21:59 +00001553 # Check if we should use diff.
Tim Petersc6cbab02004-08-22 19:43:28 +00001554 if self._do_a_fancy_diff(want, got, optionflags):
Edward Loper34fcb142004-08-09 02:45:41 +00001555 # Split want & got into lines.
Tim Peterse7edcb82004-08-26 05:44:27 +00001556 want_lines = want.splitlines(True) # True == keep line ends
1557 got_lines = got.splitlines(True)
Edward Loper34fcb142004-08-09 02:45:41 +00001558 # Use difflib to find their differences.
Edward Loper71f55af2004-08-26 01:41:51 +00001559 if optionflags & REPORT_UDIFF:
Edward Loper56629292004-08-26 01:31:56 +00001560 diff = difflib.unified_diff(want_lines, got_lines, n=2)
1561 diff = list(diff)[2:] # strip the diff header
1562 kind = 'unified diff with -expected +actual'
Edward Loper71f55af2004-08-26 01:41:51 +00001563 elif optionflags & REPORT_CDIFF:
Edward Loper56629292004-08-26 01:31:56 +00001564 diff = difflib.context_diff(want_lines, got_lines, n=2)
1565 diff = list(diff)[2:] # strip the diff header
1566 kind = 'context diff with expected followed by actual'
Edward Loper71f55af2004-08-26 01:41:51 +00001567 elif optionflags & REPORT_NDIFF:
Tim Petersc6cbab02004-08-22 19:43:28 +00001568 engine = difflib.Differ(charjunk=difflib.IS_CHARACTER_JUNK)
1569 diff = list(engine.compare(want_lines, got_lines))
1570 kind = 'ndiff with -expected +actual'
Edward Loper34fcb142004-08-09 02:45:41 +00001571 else:
1572 assert 0, 'Bad diff option'
1573 # Remove trailing whitespace on diff output.
1574 diff = [line.rstrip() + '\n' for line in diff]
Edward Loperaacf0832004-08-26 01:19:50 +00001575 return 'Differences (%s):\n' % kind + _indent(''.join(diff))
Edward Loper34fcb142004-08-09 02:45:41 +00001576
1577 # If we're not using diff, then simply list the expected
1578 # output followed by the actual output.
Edward Loperaacf0832004-08-26 01:19:50 +00001579 if want and got:
1580 return 'Expected:\n%sGot:\n%s' % (_indent(want), _indent(got))
1581 elif want:
1582 return 'Expected:\n%sGot nothing\n' % _indent(want)
1583 elif got:
1584 return 'Expected nothing\nGot:\n%s' % _indent(got)
1585 else:
1586 return 'Expected nothing\nGot nothing\n'
Edward Loper34fcb142004-08-09 02:45:41 +00001587
Tim Peters19397e52004-08-06 22:02:59 +00001588class DocTestFailure(Exception):
1589 """A DocTest example has failed in debugging mode.
1590
1591 The exception instance has variables:
1592
1593 - test: the DocTest object being run
1594
1595 - excample: the Example object that failed
1596
1597 - got: the actual output
1598 """
1599 def __init__(self, test, example, got):
1600 self.test = test
1601 self.example = example
1602 self.got = got
1603
1604 def __str__(self):
1605 return str(self.test)
1606
1607class UnexpectedException(Exception):
1608 """A DocTest example has encountered an unexpected exception
1609
1610 The exception instance has variables:
1611
1612 - test: the DocTest object being run
1613
1614 - excample: the Example object that failed
1615
1616 - exc_info: the exception info
1617 """
1618 def __init__(self, test, example, exc_info):
1619 self.test = test
1620 self.example = example
1621 self.exc_info = exc_info
1622
1623 def __str__(self):
1624 return str(self.test)
Tim Petersd1b78272004-08-07 06:03:09 +00001625
Tim Peters19397e52004-08-06 22:02:59 +00001626class DebugRunner(DocTestRunner):
1627 r"""Run doc tests but raise an exception as soon as there is a failure.
1628
1629 If an unexpected exception occurs, an UnexpectedException is raised.
1630 It contains the test, the example, and the original exception:
1631
1632 >>> runner = DebugRunner(verbose=False)
Edward Lopera1ef6112004-08-09 16:14:41 +00001633 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
1634 ... {}, 'foo', 'foo.py', 0)
Tim Peters19397e52004-08-06 22:02:59 +00001635 >>> try:
1636 ... runner.run(test)
1637 ... except UnexpectedException, failure:
1638 ... pass
1639
1640 >>> failure.test is test
1641 True
1642
1643 >>> failure.example.want
1644 '42\n'
1645
1646 >>> exc_info = failure.exc_info
1647 >>> raise exc_info[0], exc_info[1], exc_info[2]
1648 Traceback (most recent call last):
1649 ...
1650 KeyError
1651
1652 We wrap the original exception to give the calling application
1653 access to the test and example information.
1654
1655 If the output doesn't match, then a DocTestFailure is raised:
1656
Edward Lopera1ef6112004-08-09 16:14:41 +00001657 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00001658 ... >>> x = 1
1659 ... >>> x
1660 ... 2
1661 ... ''', {}, 'foo', 'foo.py', 0)
1662
1663 >>> try:
1664 ... runner.run(test)
1665 ... except DocTestFailure, failure:
1666 ... pass
1667
1668 DocTestFailure objects provide access to the test:
1669
1670 >>> failure.test is test
1671 True
1672
1673 As well as to the example:
1674
1675 >>> failure.example.want
1676 '2\n'
1677
1678 and the actual output:
1679
1680 >>> failure.got
1681 '1\n'
1682
1683 If a failure or error occurs, the globals are left intact:
1684
1685 >>> del test.globs['__builtins__']
1686 >>> test.globs
1687 {'x': 1}
1688
Edward Lopera1ef6112004-08-09 16:14:41 +00001689 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00001690 ... >>> x = 2
1691 ... >>> raise KeyError
1692 ... ''', {}, 'foo', 'foo.py', 0)
1693
1694 >>> runner.run(test)
1695 Traceback (most recent call last):
1696 ...
1697 UnexpectedException: <DocTest foo from foo.py:0 (2 examples)>
Tim Petersd1b78272004-08-07 06:03:09 +00001698
Tim Peters19397e52004-08-06 22:02:59 +00001699 >>> del test.globs['__builtins__']
1700 >>> test.globs
1701 {'x': 2}
1702
1703 But the globals are cleared if there is no error:
1704
Edward Lopera1ef6112004-08-09 16:14:41 +00001705 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00001706 ... >>> x = 2
1707 ... ''', {}, 'foo', 'foo.py', 0)
1708
1709 >>> runner.run(test)
1710 (0, 1)
1711
1712 >>> test.globs
1713 {}
1714
1715 """
1716
1717 def run(self, test, compileflags=None, out=None, clear_globs=True):
1718 r = DocTestRunner.run(self, test, compileflags, out, False)
1719 if clear_globs:
1720 test.globs.clear()
1721 return r
1722
1723 def report_unexpected_exception(self, out, test, example, exc_info):
1724 raise UnexpectedException(test, example, exc_info)
1725
1726 def report_failure(self, out, test, example, got):
1727 raise DocTestFailure(test, example, got)
1728
Tim Peters8485b562004-08-04 18:46:34 +00001729######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00001730## 6. Test Functions
Tim Peters8485b562004-08-04 18:46:34 +00001731######################################################################
1732# These should be backwards compatible.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001733
Tim Peters82076ef2004-09-13 00:52:51 +00001734# For backward compatibility, a global instance of a DocTestRunner
1735# class, updated by testmod.
1736master = None
1737
Martin v. Löwis4581cfa2002-11-22 08:23:09 +00001738def testmod(m=None, name=None, globs=None, verbose=None, isprivate=None,
Tim Peters19397e52004-08-06 22:02:59 +00001739 report=True, optionflags=0, extraglobs=None,
Tim Peters958cc892004-09-13 14:53:28 +00001740 raise_on_error=False, exclude_empty=False):
Tim Peters6ebe61f2003-06-27 20:48:05 +00001741 """m=None, name=None, globs=None, verbose=None, isprivate=None,
Tim Peters958cc892004-09-13 14:53:28 +00001742 report=True, optionflags=0, extraglobs=None, raise_on_error=False,
1743 exclude_empty=False
Tim Peters8a7d2d52001-01-16 07:10:57 +00001744
Martin v. Löwis4581cfa2002-11-22 08:23:09 +00001745 Test examples in docstrings in functions and classes reachable
1746 from module m (or the current module if m is not supplied), starting
Raymond Hettinger71adf7e2003-07-16 19:25:22 +00001747 with m.__doc__. Unless isprivate is specified, private names
1748 are not skipped.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001749
1750 Also test examples reachable from dict m.__test__ if it exists and is
Tim Petersc2388a22004-08-10 01:41:28 +00001751 not None. m.__test__ maps names to functions, classes and strings;
Tim Peters8a7d2d52001-01-16 07:10:57 +00001752 function and class docstrings are tested even if the name is private;
1753 strings are tested directly, as if they were docstrings.
1754
1755 Return (#failures, #tests).
1756
1757 See doctest.__doc__ for an overview.
1758
1759 Optional keyword arg "name" gives the name of the module; by default
1760 use m.__name__.
1761
1762 Optional keyword arg "globs" gives a dict to be used as the globals
1763 when executing examples; by default, use m.__dict__. A copy of this
1764 dict is actually used for each docstring, so that each docstring's
1765 examples start with a clean slate.
1766
Tim Peters8485b562004-08-04 18:46:34 +00001767 Optional keyword arg "extraglobs" gives a dictionary that should be
1768 merged into the globals that are used to execute examples. By
1769 default, no extra globals are used. This is new in 2.4.
1770
Tim Peters8a7d2d52001-01-16 07:10:57 +00001771 Optional keyword arg "verbose" prints lots of stuff if true, prints
1772 only failures if false; by default, it's true iff "-v" is in sys.argv.
1773
Tim Peters8a7d2d52001-01-16 07:10:57 +00001774 Optional keyword arg "report" prints a summary at the end when true,
1775 else prints nothing at the end. In verbose mode, the summary is
1776 detailed, else very brief (in fact, empty if all tests passed).
1777
Tim Peters6ebe61f2003-06-27 20:48:05 +00001778 Optional keyword arg "optionflags" or's together module constants,
Tim Petersf82a9de2004-08-22 20:51:53 +00001779 and defaults to 0. This is new in 2.3. Possible values (see the
1780 docs for details):
Tim Peters6ebe61f2003-06-27 20:48:05 +00001781
1782 DONT_ACCEPT_TRUE_FOR_1
Tim Peters8485b562004-08-04 18:46:34 +00001783 DONT_ACCEPT_BLANKLINE
Tim Peters8485b562004-08-04 18:46:34 +00001784 NORMALIZE_WHITESPACE
Tim Peters8485b562004-08-04 18:46:34 +00001785 ELLIPSIS
Edward Loper052d0cd2004-09-19 17:19:33 +00001786 IGNORE_EXCEPTION_DETAIL
Edward Loper71f55af2004-08-26 01:41:51 +00001787 REPORT_UDIFF
1788 REPORT_CDIFF
1789 REPORT_NDIFF
Edward Lopera89f88d2004-08-26 02:45:51 +00001790 REPORT_ONLY_FIRST_FAILURE
Tim Peters19397e52004-08-06 22:02:59 +00001791
1792 Optional keyword arg "raise_on_error" raises an exception on the
1793 first unexpected exception or failure. This allows failures to be
1794 post-mortem debugged.
1795
Tim Petersf727c6c2004-08-08 01:48:59 +00001796 Deprecated in Python 2.4:
1797 Optional keyword arg "isprivate" specifies a function used to
1798 determine whether a name is private. The default function is
1799 treat all functions as public. Optionally, "isprivate" can be
1800 set to doctest.is_private to skip over functions marked as private
1801 using the underscore naming convention; see its docs for details.
Tim Peters8485b562004-08-04 18:46:34 +00001802
Tim Peters8a7d2d52001-01-16 07:10:57 +00001803 Advanced tomfoolery: testmod runs methods of a local instance of
1804 class doctest.Tester, then merges the results into (or creates)
1805 global Tester instance doctest.master. Methods of doctest.master
1806 can be called directly too, if you want to do something unusual.
1807 Passing report=0 to testmod is especially useful then, to delay
1808 displaying a summary. Invoke doctest.master.summarize(verbose)
1809 when you're done fiddling.
1810 """
Tim Peters82076ef2004-09-13 00:52:51 +00001811 global master
1812
Tim Petersf727c6c2004-08-08 01:48:59 +00001813 if isprivate is not None:
1814 warnings.warn("the isprivate argument is deprecated; "
1815 "examine DocTestFinder.find() lists instead",
1816 DeprecationWarning)
1817
Tim Peters8485b562004-08-04 18:46:34 +00001818 # If no module was given, then use __main__.
Martin v. Löwis4581cfa2002-11-22 08:23:09 +00001819 if m is None:
Martin v. Löwis4581cfa2002-11-22 08:23:09 +00001820 # DWA - m will still be None if this wasn't invoked from the command
1821 # line, in which case the following TypeError is about as good an error
1822 # as we should expect
1823 m = sys.modules.get('__main__')
1824
Tim Peters8485b562004-08-04 18:46:34 +00001825 # Check that we were actually given a module.
1826 if not inspect.ismodule(m):
Walter Dörwald70a6b492004-02-12 17:35:32 +00001827 raise TypeError("testmod: module required; %r" % (m,))
Tim Peters8485b562004-08-04 18:46:34 +00001828
1829 # If no name was given, then use the module's name.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001830 if name is None:
1831 name = m.__name__
Tim Peters8485b562004-08-04 18:46:34 +00001832
1833 # Find, parse, and run all tests in the given module.
Tim Peters958cc892004-09-13 14:53:28 +00001834 finder = DocTestFinder(_namefilter=isprivate, exclude_empty=exclude_empty)
Tim Peters19397e52004-08-06 22:02:59 +00001835
1836 if raise_on_error:
1837 runner = DebugRunner(verbose=verbose, optionflags=optionflags)
1838 else:
1839 runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1840
Tim Peters8485b562004-08-04 18:46:34 +00001841 for test in finder.find(m, name, globs=globs, extraglobs=extraglobs):
1842 runner.run(test)
1843
Tim Peters8a7d2d52001-01-16 07:10:57 +00001844 if report:
Tim Peters8485b562004-08-04 18:46:34 +00001845 runner.summarize()
Tim Peters8a7d2d52001-01-16 07:10:57 +00001846
Tim Peters82076ef2004-09-13 00:52:51 +00001847 if master is None:
1848 master = runner
1849 else:
1850 master.merge(runner)
1851
Tim Peters8485b562004-08-04 18:46:34 +00001852 return runner.failures, runner.tries
Tim Petersdb3756d2003-06-29 05:30:48 +00001853
Edward Loper052d0cd2004-09-19 17:19:33 +00001854def testfile(filename, module_relative=True, name=None, package=None,
1855 globs=None, verbose=None, report=True, optionflags=0,
Edward Loper498a1862004-09-27 03:42:58 +00001856 extraglobs=None, raise_on_error=False, parser=DocTestParser()):
Edward Loper052d0cd2004-09-19 17:19:33 +00001857 """
1858 Test examples in the given file. Return (#failures, #tests).
1859
1860 Optional keyword arg "module_relative" specifies how filenames
1861 should be interpreted:
1862
1863 - If "module_relative" is True (the default), then "filename"
1864 specifies a module-relative path. By default, this path is
1865 relative to the calling module's directory; but if the
1866 "package" argument is specified, then it is relative to that
1867 package. To ensure os-independence, "filename" should use
1868 "/" characters to separate path segments, and should not
1869 be an absolute path (i.e., it may not begin with "/").
1870
1871 - If "module_relative" is False, then "filename" specifies an
1872 os-specific path. The path may be absolute or relative (to
1873 the current working directory).
1874
Edward Lopera2fc7ec2004-09-21 03:24:24 +00001875 Optional keyword arg "name" gives the name of the test; by default
1876 use the file's basename.
Edward Loper052d0cd2004-09-19 17:19:33 +00001877
1878 Optional keyword argument "package" is a Python package or the
1879 name of a Python package whose directory should be used as the
1880 base directory for a module relative filename. If no package is
1881 specified, then the calling module's directory is used as the base
1882 directory for module relative filenames. It is an error to
1883 specify "package" if "module_relative" is False.
1884
1885 Optional keyword arg "globs" gives a dict to be used as the globals
1886 when executing examples; by default, use {}. A copy of this dict
1887 is actually used for each docstring, so that each docstring's
1888 examples start with a clean slate.
1889
1890 Optional keyword arg "extraglobs" gives a dictionary that should be
1891 merged into the globals that are used to execute examples. By
1892 default, no extra globals are used.
1893
1894 Optional keyword arg "verbose" prints lots of stuff if true, prints
1895 only failures if false; by default, it's true iff "-v" is in sys.argv.
1896
1897 Optional keyword arg "report" prints a summary at the end when true,
1898 else prints nothing at the end. In verbose mode, the summary is
1899 detailed, else very brief (in fact, empty if all tests passed).
1900
1901 Optional keyword arg "optionflags" or's together module constants,
1902 and defaults to 0. Possible values (see the docs for details):
1903
1904 DONT_ACCEPT_TRUE_FOR_1
1905 DONT_ACCEPT_BLANKLINE
1906 NORMALIZE_WHITESPACE
1907 ELLIPSIS
1908 IGNORE_EXCEPTION_DETAIL
1909 REPORT_UDIFF
1910 REPORT_CDIFF
1911 REPORT_NDIFF
1912 REPORT_ONLY_FIRST_FAILURE
1913
1914 Optional keyword arg "raise_on_error" raises an exception on the
1915 first unexpected exception or failure. This allows failures to be
1916 post-mortem debugged.
1917
Edward Loper498a1862004-09-27 03:42:58 +00001918 Optional keyword arg "parser" specifies a DocTestParser (or
1919 subclass) that should be used to extract tests from the files.
1920
Edward Loper052d0cd2004-09-19 17:19:33 +00001921 Advanced tomfoolery: testmod runs methods of a local instance of
1922 class doctest.Tester, then merges the results into (or creates)
1923 global Tester instance doctest.master. Methods of doctest.master
1924 can be called directly too, if you want to do something unusual.
1925 Passing report=0 to testmod is especially useful then, to delay
1926 displaying a summary. Invoke doctest.master.summarize(verbose)
1927 when you're done fiddling.
1928 """
1929 global master
1930
1931 if package and not module_relative:
1932 raise ValueError("Package may only be specified for module-"
1933 "relative paths.")
Tim Petersbab3e992004-09-20 19:52:34 +00001934
Edward Loper052d0cd2004-09-19 17:19:33 +00001935 # Relativize the path
1936 if module_relative:
1937 package = _normalize_module(package)
1938 filename = _module_relative_path(package, filename)
1939
1940 # If no name was given, then use the file's name.
1941 if name is None:
Edward Lopera2fc7ec2004-09-21 03:24:24 +00001942 name = os.path.basename(filename)
Edward Loper052d0cd2004-09-19 17:19:33 +00001943
1944 # Assemble the globals.
1945 if globs is None:
1946 globs = {}
1947 else:
1948 globs = globs.copy()
1949 if extraglobs is not None:
1950 globs.update(extraglobs)
1951
1952 if raise_on_error:
1953 runner = DebugRunner(verbose=verbose, optionflags=optionflags)
1954 else:
1955 runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1956
1957 # Read the file, convert it to a test, and run it.
1958 s = open(filename).read()
Edward Loper498a1862004-09-27 03:42:58 +00001959 test = parser.get_doctest(s, globs, name, filename, 0)
Edward Loper052d0cd2004-09-19 17:19:33 +00001960 runner.run(test)
1961
1962 if report:
1963 runner.summarize()
1964
1965 if master is None:
1966 master = runner
1967 else:
1968 master.merge(runner)
1969
1970 return runner.failures, runner.tries
1971
Tim Peters8485b562004-08-04 18:46:34 +00001972def run_docstring_examples(f, globs, verbose=False, name="NoName",
1973 compileflags=None, optionflags=0):
1974 """
1975 Test examples in the given object's docstring (`f`), using `globs`
1976 as globals. Optional argument `name` is used in failure messages.
1977 If the optional argument `verbose` is true, then generate output
1978 even if there are no failures.
Tim Petersdb3756d2003-06-29 05:30:48 +00001979
Tim Peters8485b562004-08-04 18:46:34 +00001980 `compileflags` gives the set of flags that should be used by the
1981 Python compiler when running the examples. If not specified, then
1982 it will default to the set of future-import flags that apply to
1983 `globs`.
Tim Petersdb3756d2003-06-29 05:30:48 +00001984
Tim Peters8485b562004-08-04 18:46:34 +00001985 Optional keyword arg `optionflags` specifies options for the
1986 testing and output. See the documentation for `testmod` for more
1987 information.
1988 """
1989 # Find, parse, and run all tests in the given module.
1990 finder = DocTestFinder(verbose=verbose, recurse=False)
1991 runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1992 for test in finder.find(f, name, globs=globs):
1993 runner.run(test, compileflags=compileflags)
Tim Petersdb3756d2003-06-29 05:30:48 +00001994
Tim Peters8485b562004-08-04 18:46:34 +00001995######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00001996## 7. Tester
Tim Peters8485b562004-08-04 18:46:34 +00001997######################################################################
1998# This is provided only for backwards compatibility. It's not
1999# actually used in any way.
Tim Petersdb3756d2003-06-29 05:30:48 +00002000
Tim Peters8485b562004-08-04 18:46:34 +00002001class Tester:
2002 def __init__(self, mod=None, globs=None, verbose=None,
2003 isprivate=None, optionflags=0):
Tim Peters3ddd60a2004-08-08 02:43:33 +00002004
2005 warnings.warn("class Tester is deprecated; "
2006 "use class doctest.DocTestRunner instead",
2007 DeprecationWarning, stacklevel=2)
Tim Peters8485b562004-08-04 18:46:34 +00002008 if mod is None and globs is None:
2009 raise TypeError("Tester.__init__: must specify mod or globs")
Tim Peters4be7a922004-09-12 22:39:46 +00002010 if mod is not None and not inspect.ismodule(mod):
Tim Peters8485b562004-08-04 18:46:34 +00002011 raise TypeError("Tester.__init__: mod must be a module; %r" %
2012 (mod,))
2013 if globs is None:
2014 globs = mod.__dict__
2015 self.globs = globs
Tim Petersdb3756d2003-06-29 05:30:48 +00002016
Tim Peters8485b562004-08-04 18:46:34 +00002017 self.verbose = verbose
2018 self.isprivate = isprivate
2019 self.optionflags = optionflags
Tim Petersf727c6c2004-08-08 01:48:59 +00002020 self.testfinder = DocTestFinder(_namefilter=isprivate)
Tim Peters8485b562004-08-04 18:46:34 +00002021 self.testrunner = DocTestRunner(verbose=verbose,
2022 optionflags=optionflags)
Tim Petersdb3756d2003-06-29 05:30:48 +00002023
Tim Peters8485b562004-08-04 18:46:34 +00002024 def runstring(self, s, name):
Edward Lopera1ef6112004-08-09 16:14:41 +00002025 test = DocTestParser().get_doctest(s, self.globs, name, None, None)
Tim Peters8485b562004-08-04 18:46:34 +00002026 if self.verbose:
2027 print "Running string", name
2028 (f,t) = self.testrunner.run(test)
2029 if self.verbose:
2030 print f, "of", t, "examples failed in string", name
2031 return (f,t)
Tim Petersdb3756d2003-06-29 05:30:48 +00002032
Tim Petersf3f57472004-08-08 06:11:48 +00002033 def rundoc(self, object, name=None, module=None):
Tim Peters8485b562004-08-04 18:46:34 +00002034 f = t = 0
2035 tests = self.testfinder.find(object, name, module=module,
Tim Petersf3f57472004-08-08 06:11:48 +00002036 globs=self.globs)
Tim Peters8485b562004-08-04 18:46:34 +00002037 for test in tests:
2038 (f2, t2) = self.testrunner.run(test)
2039 (f,t) = (f+f2, t+t2)
2040 return (f,t)
Tim Petersdb3756d2003-06-29 05:30:48 +00002041
Tim Peters8485b562004-08-04 18:46:34 +00002042 def rundict(self, d, name, module=None):
2043 import new
2044 m = new.module(name)
2045 m.__dict__.update(d)
Tim Petersf3f57472004-08-08 06:11:48 +00002046 if module is None:
2047 module = False
2048 return self.rundoc(m, name, module)
Tim Petersdb3756d2003-06-29 05:30:48 +00002049
Tim Peters8485b562004-08-04 18:46:34 +00002050 def run__test__(self, d, name):
2051 import new
2052 m = new.module(name)
2053 m.__test__ = d
Tim Peters9661f9a2004-09-12 22:45:17 +00002054 return self.rundoc(m, name)
Tim Petersdb3756d2003-06-29 05:30:48 +00002055
Tim Peters8485b562004-08-04 18:46:34 +00002056 def summarize(self, verbose=None):
2057 return self.testrunner.summarize(verbose)
Tim Petersdb3756d2003-06-29 05:30:48 +00002058
Tim Peters8485b562004-08-04 18:46:34 +00002059 def merge(self, other):
Tim Peters82076ef2004-09-13 00:52:51 +00002060 self.testrunner.merge(other.testrunner)
Tim Petersdb3756d2003-06-29 05:30:48 +00002061
Tim Peters8485b562004-08-04 18:46:34 +00002062######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00002063## 8. Unittest Support
Tim Peters8485b562004-08-04 18:46:34 +00002064######################################################################
Tim Petersdb3756d2003-06-29 05:30:48 +00002065
Jim Fultonf54bad42004-08-28 14:57:56 +00002066_unittest_reportflags = 0
Tim Peters38330fe2004-08-30 16:19:24 +00002067
Jim Fultonf54bad42004-08-28 14:57:56 +00002068def set_unittest_reportflags(flags):
Tim Peters38330fe2004-08-30 16:19:24 +00002069 """Sets the unittest option flags.
Jim Fultonf54bad42004-08-28 14:57:56 +00002070
2071 The old flag is returned so that a runner could restore the old
2072 value if it wished to:
2073
Tim Petersb7e99b62005-03-28 23:50:54 +00002074 >>> import doctest
2075 >>> old = doctest._unittest_reportflags
2076 >>> doctest.set_unittest_reportflags(REPORT_NDIFF |
Jim Fultonf54bad42004-08-28 14:57:56 +00002077 ... REPORT_ONLY_FIRST_FAILURE) == old
2078 True
2079
Jim Fultonf54bad42004-08-28 14:57:56 +00002080 >>> doctest._unittest_reportflags == (REPORT_NDIFF |
2081 ... REPORT_ONLY_FIRST_FAILURE)
2082 True
Tim Petersdf7a2082004-08-29 00:38:17 +00002083
Jim Fultonf54bad42004-08-28 14:57:56 +00002084 Only reporting flags can be set:
2085
Tim Petersb7e99b62005-03-28 23:50:54 +00002086 >>> doctest.set_unittest_reportflags(ELLIPSIS)
Jim Fultonf54bad42004-08-28 14:57:56 +00002087 Traceback (most recent call last):
2088 ...
Tim Peters38330fe2004-08-30 16:19:24 +00002089 ValueError: ('Only reporting flags allowed', 8)
Jim Fultonf54bad42004-08-28 14:57:56 +00002090
Tim Petersb7e99b62005-03-28 23:50:54 +00002091 >>> doctest.set_unittest_reportflags(old) == (REPORT_NDIFF |
Jim Fultonf54bad42004-08-28 14:57:56 +00002092 ... REPORT_ONLY_FIRST_FAILURE)
2093 True
Jim Fultonf54bad42004-08-28 14:57:56 +00002094 """
Jim Fultonf54bad42004-08-28 14:57:56 +00002095 global _unittest_reportflags
Tim Peters38330fe2004-08-30 16:19:24 +00002096
2097 if (flags & REPORTING_FLAGS) != flags:
2098 raise ValueError("Only reporting flags allowed", flags)
Jim Fultonf54bad42004-08-28 14:57:56 +00002099 old = _unittest_reportflags
2100 _unittest_reportflags = flags
2101 return old
Tim Petersdf7a2082004-08-29 00:38:17 +00002102
Jim Fultonf54bad42004-08-28 14:57:56 +00002103
Tim Peters19397e52004-08-06 22:02:59 +00002104class DocTestCase(unittest.TestCase):
Tim Petersdb3756d2003-06-29 05:30:48 +00002105
Edward Loper34fcb142004-08-09 02:45:41 +00002106 def __init__(self, test, optionflags=0, setUp=None, tearDown=None,
2107 checker=None):
Jim Fulton07a349c2004-08-22 14:10:00 +00002108
Jim Fultona643b652004-07-14 19:06:50 +00002109 unittest.TestCase.__init__(self)
Tim Peters19397e52004-08-06 22:02:59 +00002110 self._dt_optionflags = optionflags
Edward Loper34fcb142004-08-09 02:45:41 +00002111 self._dt_checker = checker
Tim Peters19397e52004-08-06 22:02:59 +00002112 self._dt_test = test
2113 self._dt_setUp = setUp
2114 self._dt_tearDown = tearDown
Tim Petersdb3756d2003-06-29 05:30:48 +00002115
Jim Fultona643b652004-07-14 19:06:50 +00002116 def setUp(self):
Jim Fultonf54bad42004-08-28 14:57:56 +00002117 test = self._dt_test
Tim Petersdf7a2082004-08-29 00:38:17 +00002118
Tim Peters19397e52004-08-06 22:02:59 +00002119 if self._dt_setUp is not None:
Jim Fultonf54bad42004-08-28 14:57:56 +00002120 self._dt_setUp(test)
Jim Fultona643b652004-07-14 19:06:50 +00002121
2122 def tearDown(self):
Jim Fultonf54bad42004-08-28 14:57:56 +00002123 test = self._dt_test
2124
Tim Peters19397e52004-08-06 22:02:59 +00002125 if self._dt_tearDown is not None:
Jim Fultonf54bad42004-08-28 14:57:56 +00002126 self._dt_tearDown(test)
2127
2128 test.globs.clear()
Jim Fultona643b652004-07-14 19:06:50 +00002129
2130 def runTest(self):
Tim Peters19397e52004-08-06 22:02:59 +00002131 test = self._dt_test
Jim Fultona643b652004-07-14 19:06:50 +00002132 old = sys.stdout
2133 new = StringIO()
Jim Fultonf54bad42004-08-28 14:57:56 +00002134 optionflags = self._dt_optionflags
Tim Petersdf7a2082004-08-29 00:38:17 +00002135
Tim Peters38330fe2004-08-30 16:19:24 +00002136 if not (optionflags & REPORTING_FLAGS):
Jim Fultonf54bad42004-08-28 14:57:56 +00002137 # The option flags don't include any reporting flags,
2138 # so add the default reporting flags
2139 optionflags |= _unittest_reportflags
Tim Petersdf7a2082004-08-29 00:38:17 +00002140
Jim Fultonf54bad42004-08-28 14:57:56 +00002141 runner = DocTestRunner(optionflags=optionflags,
Edward Loper34fcb142004-08-09 02:45:41 +00002142 checker=self._dt_checker, verbose=False)
Tim Peters19397e52004-08-06 22:02:59 +00002143
Jim Fultona643b652004-07-14 19:06:50 +00002144 try:
Tim Peters19397e52004-08-06 22:02:59 +00002145 runner.DIVIDER = "-"*70
Jim Fultonf54bad42004-08-28 14:57:56 +00002146 failures, tries = runner.run(
2147 test, out=new.write, clear_globs=False)
Jim Fultona643b652004-07-14 19:06:50 +00002148 finally:
2149 sys.stdout = old
2150
2151 if failures:
Tim Peters19397e52004-08-06 22:02:59 +00002152 raise self.failureException(self.format_failure(new.getvalue()))
Tim Peters8485b562004-08-04 18:46:34 +00002153
Tim Peters19397e52004-08-06 22:02:59 +00002154 def format_failure(self, err):
2155 test = self._dt_test
2156 if test.lineno is None:
2157 lineno = 'unknown line number'
2158 else:
Jim Fulton07a349c2004-08-22 14:10:00 +00002159 lineno = '%s' % test.lineno
Tim Peters19397e52004-08-06 22:02:59 +00002160 lname = '.'.join(test.name.split('.')[-1:])
2161 return ('Failed doctest test for %s\n'
2162 ' File "%s", line %s, in %s\n\n%s'
2163 % (test.name, test.filename, lineno, lname, err)
2164 )
2165
2166 def debug(self):
2167 r"""Run the test case without results and without catching exceptions
2168
2169 The unit test framework includes a debug method on test cases
2170 and test suites to support post-mortem debugging. The test code
2171 is run in such a way that errors are not caught. This way a
2172 caller can catch the errors and initiate post-mortem debugging.
2173
2174 The DocTestCase provides a debug method that raises
2175 UnexpectedException errors if there is an unexepcted
2176 exception:
2177
Edward Lopera1ef6112004-08-09 16:14:41 +00002178 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
Tim Peters19397e52004-08-06 22:02:59 +00002179 ... {}, 'foo', 'foo.py', 0)
2180 >>> case = DocTestCase(test)
2181 >>> try:
2182 ... case.debug()
2183 ... except UnexpectedException, failure:
2184 ... pass
2185
2186 The UnexpectedException contains the test, the example, and
2187 the original exception:
2188
2189 >>> failure.test is test
2190 True
2191
2192 >>> failure.example.want
2193 '42\n'
2194
2195 >>> exc_info = failure.exc_info
2196 >>> raise exc_info[0], exc_info[1], exc_info[2]
2197 Traceback (most recent call last):
2198 ...
2199 KeyError
2200
2201 If the output doesn't match, then a DocTestFailure is raised:
2202
Edward Lopera1ef6112004-08-09 16:14:41 +00002203 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00002204 ... >>> x = 1
2205 ... >>> x
2206 ... 2
2207 ... ''', {}, 'foo', 'foo.py', 0)
2208 >>> case = DocTestCase(test)
2209
2210 >>> try:
2211 ... case.debug()
2212 ... except DocTestFailure, failure:
2213 ... pass
2214
2215 DocTestFailure objects provide access to the test:
2216
2217 >>> failure.test is test
2218 True
2219
2220 As well as to the example:
2221
2222 >>> failure.example.want
2223 '2\n'
2224
2225 and the actual output:
2226
2227 >>> failure.got
2228 '1\n'
2229
2230 """
2231
Jim Fultonf54bad42004-08-28 14:57:56 +00002232 self.setUp()
Edward Loper34fcb142004-08-09 02:45:41 +00002233 runner = DebugRunner(optionflags=self._dt_optionflags,
2234 checker=self._dt_checker, verbose=False)
Edward Loper3a3817f2004-08-19 19:26:06 +00002235 runner.run(self._dt_test)
Jim Fultonf54bad42004-08-28 14:57:56 +00002236 self.tearDown()
Jim Fultona643b652004-07-14 19:06:50 +00002237
2238 def id(self):
Tim Peters19397e52004-08-06 22:02:59 +00002239 return self._dt_test.name
Jim Fultona643b652004-07-14 19:06:50 +00002240
2241 def __repr__(self):
Tim Peters19397e52004-08-06 22:02:59 +00002242 name = self._dt_test.name.split('.')
Jim Fultona643b652004-07-14 19:06:50 +00002243 return "%s (%s)" % (name[-1], '.'.join(name[:-1]))
2244
2245 __str__ = __repr__
2246
2247 def shortDescription(self):
Tim Peters19397e52004-08-06 22:02:59 +00002248 return "Doctest: " + self._dt_test.name
Jim Fultona643b652004-07-14 19:06:50 +00002249
Jim Fultonf54bad42004-08-28 14:57:56 +00002250def DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None,
2251 **options):
Tim Peters8485b562004-08-04 18:46:34 +00002252 """
Tim Peters75dc5e12004-08-22 17:50:45 +00002253 Convert doctest tests for a module to a unittest test suite.
Jim Fultona643b652004-07-14 19:06:50 +00002254
Tim Peters19397e52004-08-06 22:02:59 +00002255 This converts each documentation string in a module that
2256 contains doctest tests to a unittest test case. If any of the
2257 tests in a doc string fail, then the test case fails. An exception
2258 is raised showing the name of the file containing the test and a
Jim Fultona643b652004-07-14 19:06:50 +00002259 (sometimes approximate) line number.
2260
Tim Peters19397e52004-08-06 22:02:59 +00002261 The `module` argument provides the module to be tested. The argument
Jim Fultona643b652004-07-14 19:06:50 +00002262 can be either a module or a module name.
2263
2264 If no argument is given, the calling module is used.
Jim Fultonf54bad42004-08-28 14:57:56 +00002265
2266 A number of options may be provided as keyword arguments:
2267
Jim Fultonf54bad42004-08-28 14:57:56 +00002268 setUp
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002269 A set-up function. This is called before running the
Jim Fultonf54bad42004-08-28 14:57:56 +00002270 tests in each file. The setUp function will be passed a DocTest
2271 object. The setUp function can access the test globals as the
2272 globs attribute of the test passed.
2273
2274 tearDown
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002275 A tear-down function. This is called after running the
Jim Fultonf54bad42004-08-28 14:57:56 +00002276 tests in each file. The tearDown function will be passed a DocTest
2277 object. The tearDown function can access the test globals as the
2278 globs attribute of the test passed.
2279
2280 globs
2281 A dictionary containing initial global variables for the tests.
2282
2283 optionflags
2284 A set of doctest option flags expressed as an integer.
Jim Fultona643b652004-07-14 19:06:50 +00002285 """
Jim Fultona643b652004-07-14 19:06:50 +00002286
Tim Peters8485b562004-08-04 18:46:34 +00002287 if test_finder is None:
2288 test_finder = DocTestFinder()
Tim Peters8485b562004-08-04 18:46:34 +00002289
Tim Peters19397e52004-08-06 22:02:59 +00002290 module = _normalize_module(module)
2291 tests = test_finder.find(module, globs=globs, extraglobs=extraglobs)
2292 if globs is None:
2293 globs = module.__dict__
Jim Fultonf54bad42004-08-28 14:57:56 +00002294 if not tests:
2295 # Why do we want to do this? Because it reveals a bug that might
2296 # otherwise be hidden.
Tim Peters19397e52004-08-06 22:02:59 +00002297 raise ValueError(module, "has no tests")
Tim Petersdb3756d2003-06-29 05:30:48 +00002298
2299 tests.sort()
2300 suite = unittest.TestSuite()
Tim Peters8485b562004-08-04 18:46:34 +00002301 for test in tests:
Tim Peters19397e52004-08-06 22:02:59 +00002302 if len(test.examples) == 0:
2303 continue
Tim Peters8485b562004-08-04 18:46:34 +00002304 if not test.filename:
Tim Petersdb3756d2003-06-29 05:30:48 +00002305 filename = module.__file__
Jim Fulton07a349c2004-08-22 14:10:00 +00002306 if filename[-4:] in (".pyc", ".pyo"):
Tim Petersdb3756d2003-06-29 05:30:48 +00002307 filename = filename[:-1]
Tim Peters8485b562004-08-04 18:46:34 +00002308 test.filename = filename
Jim Fultonf54bad42004-08-28 14:57:56 +00002309 suite.addTest(DocTestCase(test, **options))
Tim Peters19397e52004-08-06 22:02:59 +00002310
2311 return suite
2312
2313class DocFileCase(DocTestCase):
2314
2315 def id(self):
2316 return '_'.join(self._dt_test.name.split('.'))
2317
2318 def __repr__(self):
2319 return self._dt_test.filename
2320 __str__ = __repr__
2321
2322 def format_failure(self, err):
2323 return ('Failed doctest test for %s\n File "%s", line 0\n\n%s'
2324 % (self._dt_test.name, self._dt_test.filename, err)
2325 )
2326
Edward Loper052d0cd2004-09-19 17:19:33 +00002327def DocFileTest(path, module_relative=True, package=None,
Edward Loper498a1862004-09-27 03:42:58 +00002328 globs=None, parser=DocTestParser(), **options):
Tim Peters19397e52004-08-06 22:02:59 +00002329 if globs is None:
2330 globs = {}
Fred Drake7c404a42004-12-21 23:46:34 +00002331 else:
2332 globs = globs.copy()
Tim Peters19397e52004-08-06 22:02:59 +00002333
Edward Loper052d0cd2004-09-19 17:19:33 +00002334 if package and not module_relative:
2335 raise ValueError("Package may only be specified for module-"
2336 "relative paths.")
Tim Petersbab3e992004-09-20 19:52:34 +00002337
Edward Loper052d0cd2004-09-19 17:19:33 +00002338 # Relativize the path.
2339 if module_relative:
2340 package = _normalize_module(package)
2341 path = _module_relative_path(package, path)
Fred Drake7c404a42004-12-21 23:46:34 +00002342 if "__file__" not in globs:
2343 globs["__file__"] = path
Tim Peters19397e52004-08-06 22:02:59 +00002344
Edward Loper052d0cd2004-09-19 17:19:33 +00002345 # Find the file and read it.
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002346 name = os.path.basename(path)
Edward Loper052d0cd2004-09-19 17:19:33 +00002347 doc = open(path).read()
2348
2349 # Convert it to a test, and wrap it in a DocFileCase.
Edward Loper498a1862004-09-27 03:42:58 +00002350 test = parser.get_doctest(doc, globs, name, path, 0)
Jim Fultonf54bad42004-08-28 14:57:56 +00002351 return DocFileCase(test, **options)
Tim Peters19397e52004-08-06 22:02:59 +00002352
2353def DocFileSuite(*paths, **kw):
Edward Loper052d0cd2004-09-19 17:19:33 +00002354 """A unittest suite for one or more doctest files.
Tim Petersbab3e992004-09-20 19:52:34 +00002355
Edward Loper052d0cd2004-09-19 17:19:33 +00002356 The path to each doctest file is given as a string; the
2357 interpretation of that string depends on the keyword argument
2358 "module_relative".
Tim Peters19397e52004-08-06 22:02:59 +00002359
2360 A number of options may be provided as keyword arguments:
2361
Edward Loper052d0cd2004-09-19 17:19:33 +00002362 module_relative
2363 If "module_relative" is True, then the given file paths are
2364 interpreted as os-independent module-relative paths. By
2365 default, these paths are relative to the calling module's
2366 directory; but if the "package" argument is specified, then
2367 they are relative to that package. To ensure os-independence,
2368 "filename" should use "/" characters to separate path
2369 segments, and may not be an absolute path (i.e., it may not
2370 begin with "/").
Tim Petersbab3e992004-09-20 19:52:34 +00002371
Edward Loper052d0cd2004-09-19 17:19:33 +00002372 If "module_relative" is False, then the given file paths are
2373 interpreted as os-specific paths. These paths may be absolute
2374 or relative (to the current working directory).
2375
Tim Peters19397e52004-08-06 22:02:59 +00002376 package
Edward Loper052d0cd2004-09-19 17:19:33 +00002377 A Python package or the name of a Python package whose directory
2378 should be used as the base directory for module relative paths.
2379 If "package" is not specified, then the calling module's
2380 directory is used as the base directory for module relative
2381 filenames. It is an error to specify "package" if
2382 "module_relative" is False.
Tim Peters19397e52004-08-06 22:02:59 +00002383
2384 setUp
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002385 A set-up function. This is called before running the
Jim Fultonf54bad42004-08-28 14:57:56 +00002386 tests in each file. The setUp function will be passed a DocTest
2387 object. The setUp function can access the test globals as the
2388 globs attribute of the test passed.
Tim Peters19397e52004-08-06 22:02:59 +00002389
2390 tearDown
Edward Lopera2fc7ec2004-09-21 03:24:24 +00002391 A tear-down function. This is called after running the
Jim Fultonf54bad42004-08-28 14:57:56 +00002392 tests in each file. The tearDown function will be passed a DocTest
2393 object. The tearDown function can access the test globals as the
2394 globs attribute of the test passed.
Tim Peters19397e52004-08-06 22:02:59 +00002395
2396 globs
2397 A dictionary containing initial global variables for the tests.
Jim Fultonf54bad42004-08-28 14:57:56 +00002398
2399 optionflags
Edward Loper498a1862004-09-27 03:42:58 +00002400 A set of doctest option flags expressed as an integer.
2401
2402 parser
2403 A DocTestParser (or subclass) that should be used to extract
2404 tests from the files.
Tim Peters19397e52004-08-06 22:02:59 +00002405 """
2406 suite = unittest.TestSuite()
2407
2408 # We do this here so that _normalize_module is called at the right
2409 # level. If it were called in DocFileTest, then this function
2410 # would be the caller and we might guess the package incorrectly.
Edward Loper052d0cd2004-09-19 17:19:33 +00002411 if kw.get('module_relative', True):
2412 kw['package'] = _normalize_module(kw.get('package'))
Tim Peters19397e52004-08-06 22:02:59 +00002413
2414 for path in paths:
2415 suite.addTest(DocFileTest(path, **kw))
Jim Fultona643b652004-07-14 19:06:50 +00002416
Tim Petersdb3756d2003-06-29 05:30:48 +00002417 return suite
2418
Tim Peters8485b562004-08-04 18:46:34 +00002419######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00002420## 9. Debugging Support
Tim Peters8485b562004-08-04 18:46:34 +00002421######################################################################
Jim Fultona643b652004-07-14 19:06:50 +00002422
Tim Peters19397e52004-08-06 22:02:59 +00002423def script_from_examples(s):
2424 r"""Extract script from text with examples.
2425
2426 Converts text with examples to a Python script. Example input is
2427 converted to regular code. Example output and all other words
2428 are converted to comments:
2429
2430 >>> text = '''
2431 ... Here are examples of simple math.
2432 ...
2433 ... Python has super accurate integer addition
2434 ...
2435 ... >>> 2 + 2
2436 ... 5
2437 ...
2438 ... And very friendly error messages:
2439 ...
2440 ... >>> 1/0
2441 ... To Infinity
2442 ... And
2443 ... Beyond
2444 ...
2445 ... You can use logic if you want:
2446 ...
2447 ... >>> if 0:
2448 ... ... blah
2449 ... ... blah
2450 ... ...
2451 ...
2452 ... Ho hum
2453 ... '''
2454
2455 >>> print script_from_examples(text)
Edward Lopera5db6002004-08-12 02:41:30 +00002456 # Here are examples of simple math.
Tim Peters19397e52004-08-06 22:02:59 +00002457 #
Edward Lopera5db6002004-08-12 02:41:30 +00002458 # Python has super accurate integer addition
Tim Peters19397e52004-08-06 22:02:59 +00002459 #
2460 2 + 2
2461 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +00002462 ## 5
Tim Peters19397e52004-08-06 22:02:59 +00002463 #
Edward Lopera5db6002004-08-12 02:41:30 +00002464 # And very friendly error messages:
Tim Peters19397e52004-08-06 22:02:59 +00002465 #
2466 1/0
2467 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +00002468 ## To Infinity
2469 ## And
2470 ## Beyond
Tim Peters19397e52004-08-06 22:02:59 +00002471 #
Edward Lopera5db6002004-08-12 02:41:30 +00002472 # You can use logic if you want:
Tim Peters19397e52004-08-06 22:02:59 +00002473 #
2474 if 0:
2475 blah
2476 blah
Tim Peters19397e52004-08-06 22:02:59 +00002477 #
Edward Lopera5db6002004-08-12 02:41:30 +00002478 # Ho hum
Georg Brandlecf93c72005-06-26 23:09:51 +00002479 <BLANKLINE>
Tim Peters19397e52004-08-06 22:02:59 +00002480 """
Edward Loper00f8da72004-08-26 18:05:07 +00002481 output = []
2482 for piece in DocTestParser().parse(s):
2483 if isinstance(piece, Example):
2484 # Add the example's source code (strip trailing NL)
2485 output.append(piece.source[:-1])
2486 # Add the expected output:
2487 want = piece.want
2488 if want:
2489 output.append('# Expected:')
2490 output += ['## '+l for l in want.split('\n')[:-1]]
2491 else:
2492 # Add non-example text.
2493 output += [_comment_line(l)
2494 for l in piece.split('\n')[:-1]]
Tim Peters19397e52004-08-06 22:02:59 +00002495
Edward Loper00f8da72004-08-26 18:05:07 +00002496 # Trim junk on both ends.
2497 while output and output[-1] == '#':
2498 output.pop()
2499 while output and output[0] == '#':
2500 output.pop(0)
2501 # Combine the output, and return it.
Georg Brandl1f149642005-06-26 22:22:31 +00002502 # Add a courtesy newline to prevent exec from choking (see bug #1172785)
2503 return '\n'.join(output) + '\n'
Tim Petersdb3756d2003-06-29 05:30:48 +00002504
2505def testsource(module, name):
Tim Peters19397e52004-08-06 22:02:59 +00002506 """Extract the test sources from a doctest docstring as a script.
Tim Petersdb3756d2003-06-29 05:30:48 +00002507
2508 Provide the module (or dotted name of the module) containing the
Jim Fultona643b652004-07-14 19:06:50 +00002509 test to be debugged and the name (within the module) of the object
2510 with the doc string with tests to be debugged.
Tim Petersdb3756d2003-06-29 05:30:48 +00002511 """
Tim Peters8485b562004-08-04 18:46:34 +00002512 module = _normalize_module(module)
2513 tests = DocTestFinder().find(module)
2514 test = [t for t in tests if t.name == name]
Tim Petersdb3756d2003-06-29 05:30:48 +00002515 if not test:
2516 raise ValueError(name, "not found in tests")
2517 test = test[0]
Tim Peters19397e52004-08-06 22:02:59 +00002518 testsrc = script_from_examples(test.docstring)
Jim Fultona643b652004-07-14 19:06:50 +00002519 return testsrc
Tim Petersdb3756d2003-06-29 05:30:48 +00002520
Jim Fultona643b652004-07-14 19:06:50 +00002521def debug_src(src, pm=False, globs=None):
Tim Peters19397e52004-08-06 22:02:59 +00002522 """Debug a single doctest docstring, in argument `src`'"""
2523 testsrc = script_from_examples(src)
Tim Peters8485b562004-08-04 18:46:34 +00002524 debug_script(testsrc, pm, globs)
Tim Petersdb3756d2003-06-29 05:30:48 +00002525
Jim Fultona643b652004-07-14 19:06:50 +00002526def debug_script(src, pm=False, globs=None):
Tim Peters19397e52004-08-06 22:02:59 +00002527 "Debug a test script. `src` is the script, as a string."
Tim Petersdb3756d2003-06-29 05:30:48 +00002528 import pdb
Tim Petersdb3756d2003-06-29 05:30:48 +00002529
Tim Petersb6a04d62004-08-23 21:37:56 +00002530 # Note that tempfile.NameTemporaryFile() cannot be used. As the
2531 # docs say, a file so created cannot be opened by name a second time
2532 # on modern Windows boxes, and execfile() needs to open it.
2533 srcfilename = tempfile.mktemp(".py", "doctestdebug")
Tim Peters8485b562004-08-04 18:46:34 +00002534 f = open(srcfilename, 'w')
2535 f.write(src)
2536 f.close()
2537
Tim Petersb6a04d62004-08-23 21:37:56 +00002538 try:
2539 if globs:
2540 globs = globs.copy()
2541 else:
2542 globs = {}
Tim Petersdb3756d2003-06-29 05:30:48 +00002543
Tim Petersb6a04d62004-08-23 21:37:56 +00002544 if pm:
2545 try:
2546 execfile(srcfilename, globs, globs)
2547 except:
2548 print sys.exc_info()[1]
2549 pdb.post_mortem(sys.exc_info()[2])
2550 else:
2551 # Note that %r is vital here. '%s' instead can, e.g., cause
2552 # backslashes to get treated as metacharacters on Windows.
2553 pdb.run("execfile(%r)" % srcfilename, globs, globs)
2554
2555 finally:
2556 os.remove(srcfilename)
Tim Petersdb3756d2003-06-29 05:30:48 +00002557
Jim Fultona643b652004-07-14 19:06:50 +00002558def debug(module, name, pm=False):
Tim Peters19397e52004-08-06 22:02:59 +00002559 """Debug a single doctest docstring.
Jim Fultona643b652004-07-14 19:06:50 +00002560
2561 Provide the module (or dotted name of the module) containing the
2562 test to be debugged and the name (within the module) of the object
Tim Peters19397e52004-08-06 22:02:59 +00002563 with the docstring with tests to be debugged.
Jim Fultona643b652004-07-14 19:06:50 +00002564 """
Tim Peters8485b562004-08-04 18:46:34 +00002565 module = _normalize_module(module)
Jim Fultona643b652004-07-14 19:06:50 +00002566 testsrc = testsource(module, name)
2567 debug_script(testsrc, pm, module.__dict__)
2568
Tim Peters8485b562004-08-04 18:46:34 +00002569######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00002570## 10. Example Usage
Tim Peters8485b562004-08-04 18:46:34 +00002571######################################################################
Tim Peters8a7d2d52001-01-16 07:10:57 +00002572class _TestClass:
2573 """
2574 A pointless class, for sanity-checking of docstring testing.
2575
2576 Methods:
2577 square()
2578 get()
2579
2580 >>> _TestClass(13).get() + _TestClass(-12).get()
2581 1
2582 >>> hex(_TestClass(13).square().get())
2583 '0xa9'
2584 """
2585
2586 def __init__(self, val):
2587 """val -> _TestClass object with associated value val.
2588
2589 >>> t = _TestClass(123)
2590 >>> print t.get()
2591 123
2592 """
2593
2594 self.val = val
2595
2596 def square(self):
2597 """square() -> square TestClass's associated value
2598
2599 >>> _TestClass(13).square().get()
2600 169
2601 """
2602
2603 self.val = self.val ** 2
2604 return self
2605
2606 def get(self):
2607 """get() -> return TestClass's associated value.
2608
2609 >>> x = _TestClass(-42)
2610 >>> print x.get()
2611 -42
2612 """
2613
2614 return self.val
2615
2616__test__ = {"_TestClass": _TestClass,
2617 "string": r"""
2618 Example of a string object, searched as-is.
2619 >>> x = 1; y = 2
2620 >>> x + y, x * y
2621 (3, 2)
Tim Peters6ebe61f2003-06-27 20:48:05 +00002622 """,
Tim Peters3fa8c202004-08-23 21:43:39 +00002623
Tim Peters6ebe61f2003-06-27 20:48:05 +00002624 "bool-int equivalence": r"""
2625 In 2.2, boolean expressions displayed
2626 0 or 1. By default, we still accept
2627 them. This can be disabled by passing
2628 DONT_ACCEPT_TRUE_FOR_1 to the new
2629 optionflags argument.
2630 >>> 4 == 4
2631 1
2632 >>> 4 == 4
2633 True
2634 >>> 4 > 4
2635 0
2636 >>> 4 > 4
2637 False
2638 """,
Tim Peters3fa8c202004-08-23 21:43:39 +00002639
Tim Peters8485b562004-08-04 18:46:34 +00002640 "blank lines": r"""
Tim Peters3fa8c202004-08-23 21:43:39 +00002641 Blank lines can be marked with <BLANKLINE>:
2642 >>> print 'foo\n\nbar\n'
2643 foo
2644 <BLANKLINE>
2645 bar
2646 <BLANKLINE>
Tim Peters8485b562004-08-04 18:46:34 +00002647 """,
Tim Peters3fa8c202004-08-23 21:43:39 +00002648
2649 "ellipsis": r"""
2650 If the ellipsis flag is used, then '...' can be used to
2651 elide substrings in the desired output:
2652 >>> print range(1000) #doctest: +ELLIPSIS
2653 [0, 1, 2, ..., 999]
2654 """,
2655
2656 "whitespace normalization": r"""
2657 If the whitespace normalization flag is used, then
2658 differences in whitespace are ignored.
2659 >>> print range(30) #doctest: +NORMALIZE_WHITESPACE
2660 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
2661 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,
2662 27, 28, 29]
2663 """,
2664 }
Tim Peters8485b562004-08-04 18:46:34 +00002665
Tim Peters8a7d2d52001-01-16 07:10:57 +00002666def _test():
Tim Peters8485b562004-08-04 18:46:34 +00002667 r = unittest.TextTestRunner()
2668 r.run(DocTestSuite())
Tim Peters8a7d2d52001-01-16 07:10:57 +00002669
2670if __name__ == "__main__":
2671 _test()