blob: 67de4c5a99f44ece6ebda9dec190e3af82b9c436 [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
11NORMAL USAGE
12
Tim Peters80e53142004-08-09 04:34:45 +000013In simplest use, end each module M to be tested with:
Tim Peters8a7d2d52001-01-16 07:10:57 +000014
15def _test():
Tim Peters80e53142004-08-09 04:34:45 +000016 import doctest
17 return doctest.testmod()
Tim Peters8a7d2d52001-01-16 07:10:57 +000018
19if __name__ == "__main__":
20 _test()
21
22Then running the module as a script will cause the examples in the
23docstrings to get executed and verified:
24
25python M.py
26
27This won't display anything unless an example fails, in which case the
28failing example(s) and the cause(s) of the failure(s) are printed to stdout
29(why not stderr? because stderr is a lame hack <0.2 wink>), and the final
30line of output is "Test failed.".
31
32Run it with the -v switch instead:
33
34python M.py -v
35
36and a detailed report of all examples tried is printed to stdout, along
37with assorted summaries at the end.
38
Tim Peters80e53142004-08-09 04:34:45 +000039You can force verbose mode by passing "verbose=True" to testmod, or prohibit
40it by passing "verbose=False". In either of those cases, sys.argv is not
Tim Peters8a7d2d52001-01-16 07:10:57 +000041examined by testmod.
42
43In any case, testmod returns a 2-tuple of ints (f, t), where f is the
44number of docstring examples that failed and t is the total number of
45docstring examples attempted.
46
Tim Peters80e53142004-08-09 04:34:45 +000047There are a variety of other ways to run doctests, including integration
48with the unittest framework, and support for running non-Python text
49files containing doctests. There are also many ways to override parts
50of doctest's default behaviors. See the Library Reference Manual for
51details.
52
Tim Peters8a7d2d52001-01-16 07:10:57 +000053
54WHICH DOCSTRINGS ARE EXAMINED?
55
56+ M.__doc__.
57
58+ f.__doc__ for all functions f in M.__dict__.values(), except those
Raymond Hettinger71adf7e2003-07-16 19:25:22 +000059 defined in other modules.
Tim Peters8a7d2d52001-01-16 07:10:57 +000060
Raymond Hettinger71adf7e2003-07-16 19:25:22 +000061+ C.__doc__ for all classes C in M.__dict__.values(), except those
62 defined in other modules.
Tim Peters8a7d2d52001-01-16 07:10:57 +000063
64+ If M.__test__ exists and "is true", it must be a dict, and
65 each entry maps a (string) name to a function object, class object, or
66 string. Function and class object docstrings found from M.__test__
Tim Peters80e53142004-08-09 04:34:45 +000067 are searched, and strings are searched directly as if they were docstrings.
68 In output, a key K in M.__test__ appears with name
Tim Peters8a7d2d52001-01-16 07:10:57 +000069 <name of M>.__test__.K
70
71Any classes found are recursively searched similarly, to test docstrings in
Tim Peters80e53142004-08-09 04:34:45 +000072their contained methods and nested classes.
Tim Peters8a7d2d52001-01-16 07:10:57 +000073
Tim Peters8a7d2d52001-01-16 07:10:57 +000074
Tim Peters8a7d2d52001-01-16 07:10:57 +000075WHAT'S THE EXECUTION CONTEXT?
76
77By default, each time testmod finds a docstring to test, it uses a *copy*
78of M's globals (so that running tests on a module doesn't change the
79module's real globals, and so that one test in M can't leave behind crumbs
80that accidentally allow another test to work). This means examples can
81freely use any names defined at top-level in M. It also means that sloppy
82imports (see above) can cause examples in external docstrings to use
83globals inappropriate for them.
84
85You can force use of your own dict as the execution context by passing
86"globs=your_dict" to testmod instead. Presumably this would be a copy of
87M.__dict__ merged with the globals from other imported modules.
88
89
Tim Peters8a7d2d52001-01-16 07:10:57 +000090WHAT ABOUT EXCEPTIONS?
91
92No problem, as long as the only output generated by the example is the
93traceback itself. For example:
94
Tim Peters60e23f42001-02-14 00:43:21 +000095 >>> [1, 2, 3].remove(42)
Tim Petersea4f9312001-02-13 20:54:42 +000096 Traceback (most recent call last):
Tim Peters8a7d2d52001-01-16 07:10:57 +000097 File "<stdin>", line 1, in ?
Tim Peters60e23f42001-02-14 00:43:21 +000098 ValueError: list.remove(x): x not in list
Tim Peters8a7d2d52001-01-16 07:10:57 +000099 >>>
100
Tim Peters80e53142004-08-09 04:34:45 +0000101Note that only the exception type and value are compared.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000102
103
Tim Peters80e53142004-08-09 04:34:45 +0000104SO WHAT DOES A DOCTEST EXAMPLE LOOK LIKE ALREADY!?
Tim Peters8a7d2d52001-01-16 07:10:57 +0000105
106Oh ya. It's easy! In most cases a copy-and-paste of an interactive
107console session works fine -- just make sure the leading whitespace is
108rigidly consistent (you can mix tabs and spaces if you're too lazy to do it
109right, but doctest is not in the business of guessing what you think a tab
110means).
111
112 >>> # comments are ignored
113 >>> x = 12
114 >>> x
115 12
116 >>> if x == 13:
117 ... print "yes"
118 ... else:
119 ... print "no"
120 ... print "NO"
121 ... print "NO!!!"
122 ...
123 no
124 NO
125 NO!!!
126 >>>
127
128Any expected output must immediately follow the final ">>>" or "..." line
129containing the code, and the expected output (if any) extends to the next
130">>>" or all-whitespace line. That's it.
131
132Bummers:
133
Tim Peters8a7d2d52001-01-16 07:10:57 +0000134+ Output to stdout is captured, but not output to stderr (exception
135 tracebacks are captured via a different means).
136
Martin v. Löwis92816de2004-05-31 19:01:00 +0000137+ If you continue a line via backslashing in an interactive session,
138 or for any other reason use a backslash, you should use a raw
139 docstring, which will preserve your backslahses exactly as you type
140 them:
Tim Peters8a7d2d52001-01-16 07:10:57 +0000141
Tim Peters4e0e1b62004-07-07 20:54:48 +0000142 >>> def f(x):
Martin v. Löwis92816de2004-05-31 19:01:00 +0000143 ... r'''Backslashes in a raw docstring: m\n'''
144 >>> print f.__doc__
145 Backslashes in a raw docstring: m\n
Tim Peters8a7d2d52001-01-16 07:10:57 +0000146
Martin v. Löwis92816de2004-05-31 19:01:00 +0000147 Otherwise, the backslash will be interpreted as part of the string.
148 E.g., the "\n" above would be interpreted as a newline character.
149 Alternatively, you can double each backslash in the doctest version
150 (and not use a raw string):
151
Tim Peters4e0e1b62004-07-07 20:54:48 +0000152 >>> def f(x):
Martin v. Löwis92816de2004-05-31 19:01:00 +0000153 ... '''Backslashes in a raw docstring: m\\n'''
154 >>> print f.__doc__
155 Backslashes in a raw docstring: m\n
Tim Peters4e0e1b62004-07-07 20:54:48 +0000156
Tim Peters8a7d2d52001-01-16 07:10:57 +0000157The starting column doesn't matter:
158
159>>> assert "Easy!"
160 >>> import math
161 >>> math.floor(1.9)
162 1.0
163
164and as many leading whitespace characters are stripped from the expected
165output as appeared in the initial ">>>" line that triggered it.
166
167If you execute this very file, the examples above will be found and
Tim Peters80e53142004-08-09 04:34:45 +0000168executed.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000169"""
Edward Loper8e4a34b2004-08-12 02:34:27 +0000170__docformat__ = 'reStructuredText en'
Tim Peters8a7d2d52001-01-16 07:10:57 +0000171
Tim Peters4fd9e2f2001-08-18 00:05:50 +0000172__all__ = [
Edward Loperb7503ff2004-08-19 19:19:03 +0000173 # 0, Option Flags
174 'register_optionflag',
175 'DONT_ACCEPT_TRUE_FOR_1',
176 'DONT_ACCEPT_BLANKLINE',
177 'NORMALIZE_WHITESPACE',
178 'ELLIPSIS',
Edward Loper71f55af2004-08-26 01:41:51 +0000179 'REPORT_UDIFF',
180 'REPORT_CDIFF',
181 'REPORT_NDIFF',
Edward Loperb7503ff2004-08-19 19:19:03 +0000182 # 1. Utility Functions
Tim Peters8485b562004-08-04 18:46:34 +0000183 'is_private',
Edward Loperb7503ff2004-08-19 19:19:03 +0000184 # 2. Example & DocTest
Tim Peters8485b562004-08-04 18:46:34 +0000185 'Example',
186 'DocTest',
Edward Loperb7503ff2004-08-19 19:19:03 +0000187 # 3. Doctest Parser
188 'DocTestParser',
189 # 4. Doctest Finder
Tim Peters8485b562004-08-04 18:46:34 +0000190 'DocTestFinder',
Edward Loperb7503ff2004-08-19 19:19:03 +0000191 # 5. Doctest Runner
Tim Peters8485b562004-08-04 18:46:34 +0000192 'DocTestRunner',
Edward Loperb7503ff2004-08-19 19:19:03 +0000193 'OutputChecker',
194 'DocTestFailure',
195 'UnexpectedException',
196 'DebugRunner',
197 # 6. Test Functions
Tim Peters4fd9e2f2001-08-18 00:05:50 +0000198 'testmod',
199 'run_docstring_examples',
Edward Loperb7503ff2004-08-19 19:19:03 +0000200 # 7. Tester
Tim Peters4fd9e2f2001-08-18 00:05:50 +0000201 'Tester',
Edward Loperb7503ff2004-08-19 19:19:03 +0000202 # 8. Unittest Support
Tim Peters19397e52004-08-06 22:02:59 +0000203 'DocTestCase',
Tim Petersdb3756d2003-06-29 05:30:48 +0000204 'DocTestSuite',
Edward Loperb7503ff2004-08-19 19:19:03 +0000205 'DocFileCase',
206 'DocFileTest',
207 'DocFileSuite',
208 # 9. Debugging Support
209 'script_from_examples',
Tim Petersdb3756d2003-06-29 05:30:48 +0000210 'testsource',
Edward Loperb7503ff2004-08-19 19:19:03 +0000211 'debug_src',
212 'debug_script',
Tim Petersdb3756d2003-06-29 05:30:48 +0000213 'debug',
Tim Peters4fd9e2f2001-08-18 00:05:50 +0000214]
Tim Peters8a7d2d52001-01-16 07:10:57 +0000215
Tim Peters4fd9e2f2001-08-18 00:05:50 +0000216import __future__
Tim Peters8a7d2d52001-01-16 07:10:57 +0000217
Tim Peters19397e52004-08-06 22:02:59 +0000218import sys, traceback, inspect, linecache, os, re, types
Jim Fulton356fd192004-08-09 11:34:47 +0000219import unittest, difflib, pdb, tempfile
Tim Petersf727c6c2004-08-08 01:48:59 +0000220import warnings
Tim Peters8485b562004-08-04 18:46:34 +0000221from StringIO import StringIO
Tim Peters7402f792001-10-02 03:53:41 +0000222
Tim Petersdd50cb72004-08-23 22:42:55 +0000223# Don't whine about the deprecated is_private function in this
224# module's tests.
225warnings.filterwarnings("ignore", "is_private", DeprecationWarning,
226 __name__, 0)
227
Jim Fulton356fd192004-08-09 11:34:47 +0000228real_pdb_set_trace = pdb.set_trace
229
Tim Peters19397e52004-08-06 22:02:59 +0000230# There are 4 basic classes:
231# - Example: a <source, want> pair, plus an intra-docstring line number.
232# - DocTest: a collection of examples, parsed from a docstring, plus
233# info about where the docstring came from (name, filename, lineno).
234# - DocTestFinder: extracts DocTests from a given object's docstring and
235# its contained objects' docstrings.
236# - DocTestRunner: runs DocTest cases, and accumulates statistics.
237#
238# So the basic picture is:
239#
240# list of:
241# +------+ +---------+ +-------+
242# |object| --DocTestFinder-> | DocTest | --DocTestRunner-> |results|
243# +------+ +---------+ +-------+
244# | Example |
245# | ... |
246# | Example |
247# +---------+
248
Edward Loperac20f572004-08-12 02:02:24 +0000249# Option constants.
250OPTIONFLAGS_BY_NAME = {}
251def register_optionflag(name):
252 flag = 1 << len(OPTIONFLAGS_BY_NAME)
253 OPTIONFLAGS_BY_NAME[name] = flag
254 return flag
255
256DONT_ACCEPT_TRUE_FOR_1 = register_optionflag('DONT_ACCEPT_TRUE_FOR_1')
257DONT_ACCEPT_BLANKLINE = register_optionflag('DONT_ACCEPT_BLANKLINE')
258NORMALIZE_WHITESPACE = register_optionflag('NORMALIZE_WHITESPACE')
259ELLIPSIS = register_optionflag('ELLIPSIS')
Edward Loper71f55af2004-08-26 01:41:51 +0000260REPORT_UDIFF = register_optionflag('REPORT_UDIFF')
261REPORT_CDIFF = register_optionflag('REPORT_CDIFF')
262REPORT_NDIFF = register_optionflag('REPORT_NDIFF')
Edward Lopera89f88d2004-08-26 02:45:51 +0000263REPORT_ONLY_FIRST_FAILURE = register_optionflag('REPORT_ONLY_FIRST_FAILURE')
Edward Loperac20f572004-08-12 02:02:24 +0000264
265# Special string markers for use in `want` strings:
266BLANKLINE_MARKER = '<BLANKLINE>'
267ELLIPSIS_MARKER = '...'
268
Tim Peters8485b562004-08-04 18:46:34 +0000269######################################################################
270## Table of Contents
271######################################################################
Edward Loper7c748462004-08-09 02:06:06 +0000272# 1. Utility Functions
273# 2. Example & DocTest -- store test cases
274# 3. DocTest Parser -- extracts examples from strings
275# 4. DocTest Finder -- extracts test cases from objects
276# 5. DocTest Runner -- runs test cases
277# 6. Test Functions -- convenient wrappers for testing
278# 7. Tester Class -- for backwards compatibility
279# 8. Unittest Support
280# 9. Debugging Support
281# 10. Example Usage
Tim Peters8a7d2d52001-01-16 07:10:57 +0000282
Tim Peters8485b562004-08-04 18:46:34 +0000283######################################################################
284## 1. Utility Functions
285######################################################################
Tim Peters8a7d2d52001-01-16 07:10:57 +0000286
287def is_private(prefix, base):
288 """prefix, base -> true iff name prefix + "." + base is "private".
289
290 Prefix may be an empty string, and base does not contain a period.
291 Prefix is ignored (although functions you write conforming to this
292 protocol may make use of it).
293 Return true iff base begins with an (at least one) underscore, but
294 does not both begin and end with (at least) two underscores.
295
296 >>> is_private("a.b", "my_func")
Guido van Rossum77f6a652002-04-03 22:41:51 +0000297 False
Tim Peters8a7d2d52001-01-16 07:10:57 +0000298 >>> is_private("____", "_my_func")
Guido van Rossum77f6a652002-04-03 22:41:51 +0000299 True
Tim Peters8a7d2d52001-01-16 07:10:57 +0000300 >>> is_private("someclass", "__init__")
Guido van Rossum77f6a652002-04-03 22:41:51 +0000301 False
Tim Peters8a7d2d52001-01-16 07:10:57 +0000302 >>> is_private("sometypo", "__init_")
Guido van Rossum77f6a652002-04-03 22:41:51 +0000303 True
Tim Peters8a7d2d52001-01-16 07:10:57 +0000304 >>> is_private("x.y.z", "_")
Guido van Rossum77f6a652002-04-03 22:41:51 +0000305 True
Tim Peters8a7d2d52001-01-16 07:10:57 +0000306 >>> is_private("_x.y.z", "__")
Guido van Rossum77f6a652002-04-03 22:41:51 +0000307 False
Tim Peters8a7d2d52001-01-16 07:10:57 +0000308 >>> is_private("", "") # senseless but consistent
Guido van Rossum77f6a652002-04-03 22:41:51 +0000309 False
Tim Peters8a7d2d52001-01-16 07:10:57 +0000310 """
Tim Petersbafb1fe2004-08-08 01:52:57 +0000311 warnings.warn("is_private is deprecated; it wasn't useful; "
312 "examine DocTestFinder.find() lists instead",
Tim Peters3ddd60a2004-08-08 02:43:33 +0000313 DeprecationWarning, stacklevel=2)
Tim Peters8a7d2d52001-01-16 07:10:57 +0000314 return base[:1] == "_" and not base[:2] == "__" == base[-2:]
315
Tim Peters8485b562004-08-04 18:46:34 +0000316def _extract_future_flags(globs):
317 """
318 Return the compiler-flags associated with the future features that
319 have been imported into the given namespace (globs).
320 """
321 flags = 0
322 for fname in __future__.all_feature_names:
323 feature = globs.get(fname, None)
324 if feature is getattr(__future__, fname):
325 flags |= feature.compiler_flag
326 return flags
Tim Peters7402f792001-10-02 03:53:41 +0000327
Tim Peters8485b562004-08-04 18:46:34 +0000328def _normalize_module(module, depth=2):
329 """
330 Return the module specified by `module`. In particular:
331 - If `module` is a module, then return module.
332 - If `module` is a string, then import and return the
333 module with that name.
334 - If `module` is None, then return the calling module.
335 The calling module is assumed to be the module of
336 the stack frame at the given depth in the call stack.
337 """
338 if inspect.ismodule(module):
339 return module
340 elif isinstance(module, (str, unicode)):
341 return __import__(module, globals(), locals(), ["*"])
342 elif module is None:
343 return sys.modules[sys._getframe(depth).f_globals['__name__']]
344 else:
345 raise TypeError("Expected a module, string, or None")
Tim Peters7402f792001-10-02 03:53:41 +0000346
Edward Loperaacf0832004-08-26 01:19:50 +0000347def _indent(s, indent=4):
Tim Peters8485b562004-08-04 18:46:34 +0000348 """
Edward Loperaacf0832004-08-26 01:19:50 +0000349 Add the given number of space characters to the beginning every
350 non-blank line in `s`, and return the result.
Tim Peters8485b562004-08-04 18:46:34 +0000351 """
Edward Loperaacf0832004-08-26 01:19:50 +0000352 # This regexp matches the start of non-blank lines:
353 return re.sub('(?m)^(?!$)', indent*' ', s)
Tim Peters8a7d2d52001-01-16 07:10:57 +0000354
Edward Loper8e4a34b2004-08-12 02:34:27 +0000355def _exception_traceback(exc_info):
356 """
357 Return a string containing a traceback message for the given
358 exc_info tuple (as returned by sys.exc_info()).
359 """
360 # Get a traceback message.
361 excout = StringIO()
362 exc_type, exc_val, exc_tb = exc_info
363 traceback.print_exception(exc_type, exc_val, exc_tb, file=excout)
364 return excout.getvalue()
365
Tim Peters8485b562004-08-04 18:46:34 +0000366# Override some StringIO methods.
367class _SpoofOut(StringIO):
368 def getvalue(self):
369 result = StringIO.getvalue(self)
370 # If anything at all was written, make sure there's a trailing
371 # newline. There's no way for the expected output to indicate
372 # that a trailing newline is missing.
373 if result and not result.endswith("\n"):
374 result += "\n"
375 # Prevent softspace from screwing up the next test case, in
376 # case they used print with a trailing comma in an example.
377 if hasattr(self, "softspace"):
378 del self.softspace
379 return result
Tim Peters8a7d2d52001-01-16 07:10:57 +0000380
Tim Peters8485b562004-08-04 18:46:34 +0000381 def truncate(self, size=None):
382 StringIO.truncate(self, size)
383 if hasattr(self, "softspace"):
384 del self.softspace
Tim Peters8a7d2d52001-01-16 07:10:57 +0000385
Tim Peters26b3ebb2004-08-19 08:10:08 +0000386# Worst-case linear-time ellipsis matching.
Tim Petersb0a04e12004-08-20 02:08:04 +0000387def _ellipsis_match(want, got):
Tim Petersdc5de3b2004-08-19 14:06:20 +0000388 """
389 Essentially the only subtle case:
Tim Petersb0a04e12004-08-20 02:08:04 +0000390 >>> _ellipsis_match('aa...aa', 'aaa')
Tim Petersdc5de3b2004-08-19 14:06:20 +0000391 False
392 """
Tim Peters26b3ebb2004-08-19 08:10:08 +0000393 if ELLIPSIS_MARKER not in want:
394 return want == got
Tim Petersdc5de3b2004-08-19 14:06:20 +0000395
Tim Peters26b3ebb2004-08-19 08:10:08 +0000396 # Find "the real" strings.
397 ws = want.split(ELLIPSIS_MARKER)
398 assert len(ws) >= 2
Tim Peters26b3ebb2004-08-19 08:10:08 +0000399
Tim Petersdc5de3b2004-08-19 14:06:20 +0000400 # Deal with exact matches possibly needed at one or both ends.
401 startpos, endpos = 0, len(got)
402 w = ws[0]
403 if w: # starts with exact match
404 if got.startswith(w):
405 startpos = len(w)
406 del ws[0]
407 else:
408 return False
409 w = ws[-1]
410 if w: # ends with exact match
411 if got.endswith(w):
412 endpos -= len(w)
413 del ws[-1]
414 else:
415 return False
416
417 if startpos > endpos:
418 # Exact end matches required more characters than we have, as in
Tim Petersb0a04e12004-08-20 02:08:04 +0000419 # _ellipsis_match('aa...aa', 'aaa')
Tim Petersdc5de3b2004-08-19 14:06:20 +0000420 return False
421
422 # For the rest, we only need to find the leftmost non-overlapping
423 # match for each piece. If there's no overall match that way alone,
424 # there's no overall match period.
Tim Peters26b3ebb2004-08-19 08:10:08 +0000425 for w in ws:
426 # w may be '' at times, if there are consecutive ellipses, or
427 # due to an ellipsis at the start or end of `want`. That's OK.
Tim Petersdc5de3b2004-08-19 14:06:20 +0000428 # Search for an empty string succeeds, and doesn't change startpos.
429 startpos = got.find(w, startpos, endpos)
430 if startpos < 0:
Tim Peters26b3ebb2004-08-19 08:10:08 +0000431 return False
Tim Petersdc5de3b2004-08-19 14:06:20 +0000432 startpos += len(w)
Tim Peters26b3ebb2004-08-19 08:10:08 +0000433
Tim Petersdc5de3b2004-08-19 14:06:20 +0000434 return True
Tim Peters26b3ebb2004-08-19 08:10:08 +0000435
Tim Peters8485b562004-08-04 18:46:34 +0000436######################################################################
437## 2. Example & DocTest
438######################################################################
439## - An "example" is a <source, want> pair, where "source" is a
440## fragment of source code, and "want" is the expected output for
441## "source." The Example class also includes information about
442## where the example was extracted from.
443##
Edward Lopera1ef6112004-08-09 16:14:41 +0000444## - A "doctest" is a collection of examples, typically extracted from
445## a string (such as an object's docstring). The DocTest class also
446## includes information about where the string was extracted from.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000447
Tim Peters8485b562004-08-04 18:46:34 +0000448class Example:
449 """
450 A single doctest example, consisting of source code and expected
Edward Lopera1ef6112004-08-09 16:14:41 +0000451 output. `Example` defines the following attributes:
Tim Peters8a7d2d52001-01-16 07:10:57 +0000452
Edward Loper74bca7a2004-08-12 02:27:44 +0000453 - source: A single Python statement, always ending with a newline.
Tim Petersbb431472004-08-09 03:51:46 +0000454 The constructor adds a newline if needed.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000455
Edward Loper74bca7a2004-08-12 02:27:44 +0000456 - want: The expected output from running the source code (either
Tim Petersbb431472004-08-09 03:51:46 +0000457 from stdout, or a traceback in case of exception). `want` ends
458 with a newline unless it's empty, in which case it's an empty
459 string. The constructor adds a newline if needed.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000460
Edward Lopera6b68322004-08-26 00:05:43 +0000461 - exc_msg: The exception message generated by the example, if
462 the example is expected to generate an exception; or `None` if
463 it is not expected to generate an exception. This exception
464 message is compared against the return value of
465 `traceback.format_exception_only()`. `exc_msg` ends with a
466 newline unless it's `None`. The constructor adds a newline
467 if needed.
468
Edward Loper74bca7a2004-08-12 02:27:44 +0000469 - lineno: The line number within the DocTest string containing
Tim Peters8485b562004-08-04 18:46:34 +0000470 this Example where the Example begins. This line number is
471 zero-based, with respect to the beginning of the DocTest.
Edward Loper74bca7a2004-08-12 02:27:44 +0000472
473 - indent: The example's indentation in the DocTest string.
474 I.e., the number of space characters that preceed the
475 example's first prompt.
476
477 - options: A dictionary mapping from option flags to True or
478 False, which is used to override default options for this
479 example. Any option flags not contained in this dictionary
480 are left at their default value (as specified by the
481 DocTestRunner's optionflags). By default, no options are set.
Tim Peters8485b562004-08-04 18:46:34 +0000482 """
Edward Lopera6b68322004-08-26 00:05:43 +0000483 def __init__(self, source, want, exc_msg=None, lineno=0, indent=0,
484 options=None):
Tim Petersbb431472004-08-09 03:51:46 +0000485 # Normalize inputs.
486 if not source.endswith('\n'):
487 source += '\n'
488 if want and not want.endswith('\n'):
489 want += '\n'
Edward Lopera6b68322004-08-26 00:05:43 +0000490 if exc_msg is not None and not exc_msg.endswith('\n'):
491 exc_msg += '\n'
Tim Peters8485b562004-08-04 18:46:34 +0000492 # Store properties.
493 self.source = source
494 self.want = want
495 self.lineno = lineno
Edward Loper74bca7a2004-08-12 02:27:44 +0000496 self.indent = indent
497 if options is None: options = {}
498 self.options = options
Edward Lopera6b68322004-08-26 00:05:43 +0000499 self.exc_msg = exc_msg
Tim Peters8a7d2d52001-01-16 07:10:57 +0000500
Tim Peters8485b562004-08-04 18:46:34 +0000501class DocTest:
502 """
503 A collection of doctest examples that should be run in a single
Edward Lopera1ef6112004-08-09 16:14:41 +0000504 namespace. Each `DocTest` defines the following attributes:
Tim Peters8a7d2d52001-01-16 07:10:57 +0000505
Tim Peters8485b562004-08-04 18:46:34 +0000506 - examples: the list of examples.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000507
Tim Peters8485b562004-08-04 18:46:34 +0000508 - globs: The namespace (aka globals) that the examples should
509 be run in.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000510
Tim Peters8485b562004-08-04 18:46:34 +0000511 - name: A name identifying the DocTest (typically, the name of
512 the object whose docstring this DocTest was extracted from).
Tim Peters8a7d2d52001-01-16 07:10:57 +0000513
Tim Peters8485b562004-08-04 18:46:34 +0000514 - filename: The name of the file that this DocTest was extracted
Edward Lopera1ef6112004-08-09 16:14:41 +0000515 from, or `None` if the filename is unknown.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000516
Tim Peters8485b562004-08-04 18:46:34 +0000517 - lineno: The line number within filename where this DocTest
Edward Lopera1ef6112004-08-09 16:14:41 +0000518 begins, or `None` if the line number is unavailable. This
519 line number is zero-based, with respect to the beginning of
520 the file.
521
522 - docstring: The string that the examples were extracted from,
523 or `None` if the string is unavailable.
Tim Peters8485b562004-08-04 18:46:34 +0000524 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000525 def __init__(self, examples, globs, name, filename, lineno, docstring):
Tim Peters8485b562004-08-04 18:46:34 +0000526 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000527 Create a new DocTest containing the given examples. The
528 DocTest's globals are initialized with a copy of `globs`.
Tim Peters8485b562004-08-04 18:46:34 +0000529 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000530 assert not isinstance(examples, basestring), \
531 "DocTest no longer accepts str; use DocTestParser instead"
532 self.examples = examples
533 self.docstring = docstring
Tim Peters8485b562004-08-04 18:46:34 +0000534 self.globs = globs.copy()
Tim Peters8485b562004-08-04 18:46:34 +0000535 self.name = name
536 self.filename = filename
537 self.lineno = lineno
Tim Peters8485b562004-08-04 18:46:34 +0000538
539 def __repr__(self):
540 if len(self.examples) == 0:
541 examples = 'no examples'
542 elif len(self.examples) == 1:
543 examples = '1 example'
544 else:
545 examples = '%d examples' % len(self.examples)
546 return ('<DocTest %s from %s:%s (%s)>' %
547 (self.name, self.filename, self.lineno, examples))
548
549
550 # This lets us sort tests by name:
551 def __cmp__(self, other):
552 if not isinstance(other, DocTest):
553 return -1
554 return cmp((self.name, self.filename, self.lineno, id(self)),
555 (other.name, other.filename, other.lineno, id(other)))
556
557######################################################################
Edward Loperb7503ff2004-08-19 19:19:03 +0000558## 3. DocTestParser
Edward Loper7c748462004-08-09 02:06:06 +0000559######################################################################
560
Edward Lopera1ef6112004-08-09 16:14:41 +0000561class DocTestParser:
Edward Loper7c748462004-08-09 02:06:06 +0000562 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000563 A class used to parse strings containing doctest examples.
Edward Loper7c748462004-08-09 02:06:06 +0000564 """
Edward Loper8e4a34b2004-08-12 02:34:27 +0000565 # This regular expression is used to find doctest examples in a
566 # string. It defines three groups: `source` is the source code
567 # (including leading indentation and prompts); `indent` is the
568 # indentation of the first (PS1) line of the source code; and
569 # `want` is the expected output (including leading indentation).
Edward Loper7c748462004-08-09 02:06:06 +0000570 _EXAMPLE_RE = re.compile(r'''
Tim Petersd40a92b2004-08-09 03:28:45 +0000571 # Source consists of a PS1 line followed by zero or more PS2 lines.
572 (?P<source>
573 (?:^(?P<indent> [ ]*) >>> .*) # PS1 line
574 (?:\n [ ]* \.\.\. .*)*) # PS2 lines
575 \n?
576 # Want consists of any non-blank lines that do not start with PS1.
577 (?P<want> (?:(?![ ]*$) # Not a blank line
578 (?![ ]*>>>) # Not a line starting with PS1
579 .*$\n? # But any other line
580 )*)
581 ''', re.MULTILINE | re.VERBOSE)
Edward Loper8e4a34b2004-08-12 02:34:27 +0000582
Edward Lopera6b68322004-08-26 00:05:43 +0000583 # A regular expression for handling `want` strings that contain
584 # expected exceptions. It divides `want` into three pieces:
585 # - the traceback header line (`hdr`)
586 # - the traceback stack (`stack`)
587 # - the exception message (`msg`), as generated by
588 # traceback.format_exception_only()
589 # `msg` may have multiple lines. We assume/require that the
590 # exception message is the first non-indented line starting with a word
591 # character following the traceback header line.
592 _EXCEPTION_RE = re.compile(r"""
593 # Grab the traceback header. Different versions of Python have
594 # said different things on the first traceback line.
595 ^(?P<hdr> Traceback\ \(
596 (?: most\ recent\ call\ last
597 | innermost\ last
598 ) \) :
599 )
600 \s* $ # toss trailing whitespace on the header.
601 (?P<stack> .*?) # don't blink: absorb stuff until...
602 ^ (?P<msg> \w+ .*) # a line *starts* with alphanum.
603 """, re.VERBOSE | re.MULTILINE | re.DOTALL)
604
Tim Peters7ea48dd2004-08-13 01:52:59 +0000605 # A callable returning a true value iff its argument is a blank line
606 # or contains a single comment.
Edward Loper8e4a34b2004-08-12 02:34:27 +0000607 _IS_BLANK_OR_COMMENT = re.compile(r'^[ ]*(#.*)?$').match
Edward Loper7c748462004-08-09 02:06:06 +0000608
Edward Lopera1ef6112004-08-09 16:14:41 +0000609 def get_doctest(self, string, globs, name, filename, lineno):
Edward Loper7c748462004-08-09 02:06:06 +0000610 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000611 Extract all doctest examples from the given string, and
612 collect them into a `DocTest` object.
613
614 `globs`, `name`, `filename`, and `lineno` are attributes for
615 the new `DocTest` object. See the documentation for `DocTest`
616 for more information.
617 """
618 return DocTest(self.get_examples(string, name), globs,
619 name, filename, lineno, string)
620
621 def get_examples(self, string, name='<string>'):
622 """
623 Extract all doctest examples from the given string, and return
624 them as a list of `Example` objects. Line numbers are
625 0-based, because it's most common in doctests that nothing
626 interesting appears on the same line as opening triple-quote,
627 and so the first interesting line is called \"line 1\" then.
628
629 The optional argument `name` is a name identifying this
630 string, and is only used for error messages.
Edward Loper7c748462004-08-09 02:06:06 +0000631
632 >>> text = '''
633 ... >>> x, y = 2, 3 # no output expected
634 ... >>> if 1:
635 ... ... print x
636 ... ... print y
637 ... 2
638 ... 3
639 ...
640 ... Some text.
641 ... >>> x+y
642 ... 5
643 ... '''
Edward Lopera1ef6112004-08-09 16:14:41 +0000644 >>> for x in DocTestParser().get_examples(text):
Edward Loper78b58f32004-08-09 02:56:02 +0000645 ... print (x.source, x.want, x.lineno)
Tim Petersbb431472004-08-09 03:51:46 +0000646 ('x, y = 2, 3 # no output expected\\n', '', 1)
Edward Loper7c748462004-08-09 02:06:06 +0000647 ('if 1:\\n print x\\n print y\\n', '2\\n3\\n', 2)
Tim Petersbb431472004-08-09 03:51:46 +0000648 ('x+y\\n', '5\\n', 9)
Edward Loper7c748462004-08-09 02:06:06 +0000649 """
650 examples = []
651 charno, lineno = 0, 0
652 # Find all doctest examples in the string:
Edward Lopera1ef6112004-08-09 16:14:41 +0000653 for m in self._EXAMPLE_RE.finditer(string.expandtabs()):
Edward Loper7c748462004-08-09 02:06:06 +0000654 # Update lineno (lines before this example)
Edward Lopera1ef6112004-08-09 16:14:41 +0000655 lineno += string.count('\n', charno, m.start())
Edward Loper7c748462004-08-09 02:06:06 +0000656 # Extract source/want from the regexp match.
Edward Lopera6b68322004-08-26 00:05:43 +0000657 (source, want, exc_msg) = self._parse_example(m, name, lineno)
Edward Loper74bca7a2004-08-12 02:27:44 +0000658 # Extract extra options from the source.
659 options = self._find_options(source, name, lineno)
Edward Loper74bca7a2004-08-12 02:27:44 +0000660 # Create an Example, and add it to the list.
Edward Loperb51b2342004-08-17 16:37:12 +0000661 if not self._IS_BLANK_OR_COMMENT(source):
Edward Lopera6b68322004-08-26 00:05:43 +0000662 examples.append( Example(source, want, exc_msg,
663 lineno=lineno,
664 indent=len(m.group('indent')),
665 options=options) )
Edward Loper7c748462004-08-09 02:06:06 +0000666 # Update lineno (lines inside this example)
Edward Lopera1ef6112004-08-09 16:14:41 +0000667 lineno += string.count('\n', m.start(), m.end())
Edward Loper7c748462004-08-09 02:06:06 +0000668 # Update charno.
669 charno = m.end()
670 return examples
671
Edward Lopera1ef6112004-08-09 16:14:41 +0000672 def get_program(self, string, name="<string>"):
Edward Loper7c748462004-08-09 02:06:06 +0000673 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000674 Return an executable program from the given string, as a string.
Edward Loper7c748462004-08-09 02:06:06 +0000675
676 The format of this isn't rigidly defined. In general, doctest
677 examples become the executable statements in the result, and
678 their expected outputs become comments, preceded by an \"#Expected:\"
679 comment. Everything else (text, comments, everything not part of
680 a doctest test) is also placed in comments.
681
Edward Lopera1ef6112004-08-09 16:14:41 +0000682 The optional argument `name` is a name identifying this
683 string, and is only used for error messages.
684
Edward Loper7c748462004-08-09 02:06:06 +0000685 >>> text = '''
686 ... >>> x, y = 2, 3 # no output expected
687 ... >>> if 1:
688 ... ... print x
689 ... ... print y
690 ... 2
691 ... 3
692 ...
693 ... Some text.
694 ... >>> x+y
695 ... 5
696 ... '''
Edward Lopera1ef6112004-08-09 16:14:41 +0000697 >>> print DocTestParser().get_program(text)
Edward Loper7c748462004-08-09 02:06:06 +0000698 x, y = 2, 3 # no output expected
699 if 1:
700 print x
701 print y
702 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +0000703 ## 2
704 ## 3
Edward Loper7c748462004-08-09 02:06:06 +0000705 #
Edward Lopera5db6002004-08-12 02:41:30 +0000706 # Some text.
Edward Loper7c748462004-08-09 02:06:06 +0000707 x+y
708 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +0000709 ## 5
Edward Loper7c748462004-08-09 02:06:06 +0000710 """
Edward Lopera5db6002004-08-12 02:41:30 +0000711 string = string.expandtabs()
712 # If all lines begin with the same indentation, then strip it.
713 min_indent = self._min_indent(string)
714 if min_indent > 0:
715 string = '\n'.join([l[min_indent:] for l in string.split('\n')])
716
Edward Loper7c748462004-08-09 02:06:06 +0000717 output = []
718 charnum, lineno = 0, 0
719 # Find all doctest examples in the string:
Edward Lopera1ef6112004-08-09 16:14:41 +0000720 for m in self._EXAMPLE_RE.finditer(string.expandtabs()):
Edward Loper7c748462004-08-09 02:06:06 +0000721 # Add any text before this example, as a comment.
722 if m.start() > charnum:
Edward Lopera1ef6112004-08-09 16:14:41 +0000723 lines = string[charnum:m.start()-1].split('\n')
Edward Loper7c748462004-08-09 02:06:06 +0000724 output.extend([self._comment_line(l) for l in lines])
725 lineno += len(lines)
726
727 # Extract source/want from the regexp match.
Edward Lopera6b68322004-08-26 00:05:43 +0000728 (source, want, exc_msg) = self._parse_example(m, name, lineno)
Edward Loper7c748462004-08-09 02:06:06 +0000729 # Display the source
730 output.append(source)
731 # Display the expected output, if any
732 if want:
733 output.append('# Expected:')
Edward Lopera5db6002004-08-12 02:41:30 +0000734 output.extend(['## '+l for l in want.split('\n')])
Edward Loper7c748462004-08-09 02:06:06 +0000735
736 # Update the line number & char number.
Edward Lopera1ef6112004-08-09 16:14:41 +0000737 lineno += string.count('\n', m.start(), m.end())
Edward Loper7c748462004-08-09 02:06:06 +0000738 charnum = m.end()
739 # Add any remaining text, as comments.
740 output.extend([self._comment_line(l)
Edward Lopera1ef6112004-08-09 16:14:41 +0000741 for l in string[charnum:].split('\n')])
Edward Loper7c748462004-08-09 02:06:06 +0000742 # Trim junk on both ends.
743 while output and output[-1] == '#':
744 output.pop()
745 while output and output[0] == '#':
746 output.pop(0)
747 # Combine the output, and return it.
748 return '\n'.join(output)
749
Edward Loper74bca7a2004-08-12 02:27:44 +0000750 def _parse_example(self, m, name, lineno):
751 """
752 Given a regular expression match from `_EXAMPLE_RE` (`m`),
753 return a pair `(source, want)`, where `source` is the matched
754 example's source code (with prompts and indentation stripped);
755 and `want` is the example's expected output (with indentation
756 stripped).
757
758 `name` is the string's name, and `lineno` is the line number
759 where the example starts; both are used for error messages.
760 """
Edward Loper7c748462004-08-09 02:06:06 +0000761 # Get the example's indentation level.
762 indent = len(m.group('indent'))
763
764 # Divide source into lines; check that they're properly
765 # indented; and then strip their indentation & prompts.
766 source_lines = m.group('source').split('\n')
Edward Lopera1ef6112004-08-09 16:14:41 +0000767 self._check_prompt_blank(source_lines, indent, name, lineno)
Tim Petersc5049152004-08-22 17:34:58 +0000768 self._check_prefix(source_lines[1:], ' '*indent + '.', name, lineno)
Edward Loper7c748462004-08-09 02:06:06 +0000769 source = '\n'.join([sl[indent+4:] for sl in source_lines])
Edward Loper7c748462004-08-09 02:06:06 +0000770
Tim Petersc5049152004-08-22 17:34:58 +0000771 # Divide want into lines; check that it's properly indented; and
772 # then strip the indentation. Spaces before the last newline should
773 # be preserved, so plain rstrip() isn't good enough.
Jim Fulton07a349c2004-08-22 14:10:00 +0000774 want = m.group('want')
Jim Fulton07a349c2004-08-22 14:10:00 +0000775 want_lines = want.split('\n')
Tim Petersc5049152004-08-22 17:34:58 +0000776 if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]):
777 del want_lines[-1] # forget final newline & spaces after it
Edward Lopera1ef6112004-08-09 16:14:41 +0000778 self._check_prefix(want_lines, ' '*indent, name,
Tim Petersc5049152004-08-22 17:34:58 +0000779 lineno + len(source_lines))
Edward Loper7c748462004-08-09 02:06:06 +0000780 want = '\n'.join([wl[indent:] for wl in want_lines])
Edward Loper7c748462004-08-09 02:06:06 +0000781
Edward Lopera6b68322004-08-26 00:05:43 +0000782 # If `want` contains a traceback message, then extract it.
783 m = self._EXCEPTION_RE.match(want)
784 if m:
785 exc_msg = m.group('msg')
786 else:
787 exc_msg = None
788
789 return source, want, exc_msg
Edward Loper7c748462004-08-09 02:06:06 +0000790
Edward Loper74bca7a2004-08-12 02:27:44 +0000791 # This regular expression looks for option directives in the
792 # source code of an example. Option directives are comments
793 # starting with "doctest:". Warning: this may give false
794 # positives for string-literals that contain the string
795 # "#doctest:". Eliminating these false positives would require
796 # actually parsing the string; but we limit them by ignoring any
797 # line containing "#doctest:" that is *followed* by a quote mark.
798 _OPTION_DIRECTIVE_RE = re.compile(r'#\s*doctest:\s*([^\n\'"]*)$',
799 re.MULTILINE)
800
801 def _find_options(self, source, name, lineno):
802 """
803 Return a dictionary containing option overrides extracted from
804 option directives in the given source string.
805
806 `name` is the string's name, and `lineno` is the line number
807 where the example starts; both are used for error messages.
808 """
809 options = {}
810 # (note: with the current regexp, this will match at most once:)
811 for m in self._OPTION_DIRECTIVE_RE.finditer(source):
812 option_strings = m.group(1).replace(',', ' ').split()
813 for option in option_strings:
814 if (option[0] not in '+-' or
815 option[1:] not in OPTIONFLAGS_BY_NAME):
816 raise ValueError('line %r of the doctest for %s '
817 'has an invalid option: %r' %
818 (lineno+1, name, option))
819 flag = OPTIONFLAGS_BY_NAME[option[1:]]
820 options[flag] = (option[0] == '+')
821 if options and self._IS_BLANK_OR_COMMENT(source):
822 raise ValueError('line %r of the doctest for %s has an option '
823 'directive on a line with no example: %r' %
824 (lineno, name, source))
825 return options
826
Edward Lopera5db6002004-08-12 02:41:30 +0000827 # This regular expression finds the indentation of every non-blank
828 # line in a string.
829 _INDENT_RE = re.compile('^([ ]+)(?=\S)', re.MULTILINE)
830
831 def _min_indent(self, s):
832 "Return the minimum indentation of any non-blank line in `s`"
833 return min([len(indent) for indent in self._INDENT_RE.findall(s)])
834
Edward Loper7c748462004-08-09 02:06:06 +0000835 def _comment_line(self, line):
Edward Loper74bca7a2004-08-12 02:27:44 +0000836 "Return a commented form of the given line"
Edward Loper7c748462004-08-09 02:06:06 +0000837 line = line.rstrip()
Tim Petersdd0e4752004-08-09 03:31:56 +0000838 if line:
Edward Lopera5db6002004-08-12 02:41:30 +0000839 return '# '+line
Tim Petersdd0e4752004-08-09 03:31:56 +0000840 else:
841 return '#'
Edward Loper7c748462004-08-09 02:06:06 +0000842
Edward Lopera1ef6112004-08-09 16:14:41 +0000843 def _check_prompt_blank(self, lines, indent, name, lineno):
Edward Loper74bca7a2004-08-12 02:27:44 +0000844 """
845 Given the lines of a source string (including prompts and
846 leading indentation), check to make sure that every prompt is
847 followed by a space character. If any line is not followed by
848 a space character, then raise ValueError.
849 """
Edward Loper7c748462004-08-09 02:06:06 +0000850 for i, line in enumerate(lines):
851 if len(line) >= indent+4 and line[indent+3] != ' ':
852 raise ValueError('line %r of the docstring for %s '
853 'lacks blank after %s: %r' %
Edward Lopera1ef6112004-08-09 16:14:41 +0000854 (lineno+i+1, name,
Edward Loper7c748462004-08-09 02:06:06 +0000855 line[indent:indent+3], line))
856
Edward Lopera1ef6112004-08-09 16:14:41 +0000857 def _check_prefix(self, lines, prefix, name, lineno):
Edward Loper74bca7a2004-08-12 02:27:44 +0000858 """
859 Check that every line in the given list starts with the given
860 prefix; if any line does not, then raise a ValueError.
861 """
Edward Loper7c748462004-08-09 02:06:06 +0000862 for i, line in enumerate(lines):
863 if line and not line.startswith(prefix):
864 raise ValueError('line %r of the docstring for %s has '
865 'inconsistent leading whitespace: %r' %
Edward Lopera1ef6112004-08-09 16:14:41 +0000866 (lineno+i+1, name, line))
Edward Loper7c748462004-08-09 02:06:06 +0000867
868
869######################################################################
870## 4. DocTest Finder
Tim Peters8485b562004-08-04 18:46:34 +0000871######################################################################
872
873class DocTestFinder:
874 """
875 A class used to extract the DocTests that are relevant to a given
876 object, from its docstring and the docstrings of its contained
877 objects. Doctests can currently be extracted from the following
878 object types: modules, functions, classes, methods, staticmethods,
879 classmethods, and properties.
Tim Peters8485b562004-08-04 18:46:34 +0000880 """
881
Edward Lopera1ef6112004-08-09 16:14:41 +0000882 def __init__(self, verbose=False, parser=DocTestParser(),
Tim Petersf727c6c2004-08-08 01:48:59 +0000883 recurse=True, _namefilter=None):
Tim Peters8485b562004-08-04 18:46:34 +0000884 """
885 Create a new doctest finder.
886
Edward Lopera1ef6112004-08-09 16:14:41 +0000887 The optional argument `parser` specifies a class or
Tim Peters19397e52004-08-06 22:02:59 +0000888 function that should be used to create new DocTest objects (or
Tim Peters161c9632004-08-08 03:38:33 +0000889 objects that implement the same interface as DocTest). The
Tim Peters19397e52004-08-06 22:02:59 +0000890 signature for this factory function should match the signature
891 of the DocTest constructor.
892
Tim Peters8485b562004-08-04 18:46:34 +0000893 If the optional argument `recurse` is false, then `find` will
894 only examine the given object, and not any contained objects.
895 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000896 self._parser = parser
Tim Peters8485b562004-08-04 18:46:34 +0000897 self._verbose = verbose
Tim Peters8485b562004-08-04 18:46:34 +0000898 self._recurse = recurse
Tim Petersf727c6c2004-08-08 01:48:59 +0000899 # _namefilter is undocumented, and exists only for temporary backward-
900 # compatibility support of testmod's deprecated isprivate mess.
901 self._namefilter = _namefilter
Tim Peters8485b562004-08-04 18:46:34 +0000902
903 def find(self, obj, name=None, module=None, globs=None,
Tim Petersf3f57472004-08-08 06:11:48 +0000904 extraglobs=None):
Tim Peters8485b562004-08-04 18:46:34 +0000905 """
906 Return a list of the DocTests that are defined by the given
907 object's docstring, or by any of its contained objects'
908 docstrings.
909
910 The optional parameter `module` is the module that contains
Tim Petersf3f57472004-08-08 06:11:48 +0000911 the given object. If the module is not specified or is None, then
912 the test finder will attempt to automatically determine the
Tim Peters8485b562004-08-04 18:46:34 +0000913 correct module. The object's module is used:
914
915 - As a default namespace, if `globs` is not specified.
916 - To prevent the DocTestFinder from extracting DocTests
Tim Petersf3f57472004-08-08 06:11:48 +0000917 from objects that are imported from other modules.
Tim Peters8485b562004-08-04 18:46:34 +0000918 - To find the name of the file containing the object.
919 - To help find the line number of the object within its
920 file.
921
Tim Petersf3f57472004-08-08 06:11:48 +0000922 Contained objects whose module does not match `module` are ignored.
923
924 If `module` is False, no attempt to find the module will be made.
925 This is obscure, of use mostly in tests: if `module` is False, or
926 is None but cannot be found automatically, then all objects are
927 considered to belong to the (non-existent) module, so all contained
928 objects will (recursively) be searched for doctests.
929
Tim Peters8485b562004-08-04 18:46:34 +0000930 The globals for each DocTest is formed by combining `globs`
931 and `extraglobs` (bindings in `extraglobs` override bindings
932 in `globs`). A new copy of the globals dictionary is created
933 for each DocTest. If `globs` is not specified, then it
934 defaults to the module's `__dict__`, if specified, or {}
935 otherwise. If `extraglobs` is not specified, then it defaults
936 to {}.
937
Tim Peters8485b562004-08-04 18:46:34 +0000938 """
939 # If name was not specified, then extract it from the object.
940 if name is None:
941 name = getattr(obj, '__name__', None)
942 if name is None:
943 raise ValueError("DocTestFinder.find: name must be given "
944 "when obj.__name__ doesn't exist: %r" %
945 (type(obj),))
946
947 # Find the module that contains the given object (if obj is
948 # a module, then module=obj.). Note: this may fail, in which
949 # case module will be None.
Tim Petersf3f57472004-08-08 06:11:48 +0000950 if module is False:
951 module = None
952 elif module is None:
Tim Peters8485b562004-08-04 18:46:34 +0000953 module = inspect.getmodule(obj)
954
955 # Read the module's source code. This is used by
956 # DocTestFinder._find_lineno to find the line number for a
957 # given object's docstring.
958 try:
959 file = inspect.getsourcefile(obj) or inspect.getfile(obj)
960 source_lines = linecache.getlines(file)
961 if not source_lines:
962 source_lines = None
963 except TypeError:
964 source_lines = None
965
966 # Initialize globals, and merge in extraglobs.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000967 if globs is None:
Tim Peters8485b562004-08-04 18:46:34 +0000968 if module is None:
969 globs = {}
970 else:
971 globs = module.__dict__.copy()
972 else:
973 globs = globs.copy()
974 if extraglobs is not None:
975 globs.update(extraglobs)
Tim Peters8a7d2d52001-01-16 07:10:57 +0000976
Tim Peters8485b562004-08-04 18:46:34 +0000977 # Recursively expore `obj`, extracting DocTests.
978 tests = []
Tim Petersf3f57472004-08-08 06:11:48 +0000979 self._find(tests, obj, name, module, source_lines, globs, {})
Tim Peters8485b562004-08-04 18:46:34 +0000980 return tests
981
982 def _filter(self, obj, prefix, base):
983 """
984 Return true if the given object should not be examined.
985 """
Tim Petersf727c6c2004-08-08 01:48:59 +0000986 return (self._namefilter is not None and
987 self._namefilter(prefix, base))
Tim Peters8485b562004-08-04 18:46:34 +0000988
989 def _from_module(self, module, object):
990 """
991 Return true if the given object is defined in the given
992 module.
993 """
994 if module is None:
995 return True
996 elif inspect.isfunction(object):
997 return module.__dict__ is object.func_globals
998 elif inspect.isclass(object):
999 return module.__name__ == object.__module__
1000 elif inspect.getmodule(object) is not None:
1001 return module is inspect.getmodule(object)
1002 elif hasattr(object, '__module__'):
1003 return module.__name__ == object.__module__
1004 elif isinstance(object, property):
1005 return True # [XX] no way not be sure.
1006 else:
1007 raise ValueError("object must be a class or function")
1008
Tim Petersf3f57472004-08-08 06:11:48 +00001009 def _find(self, tests, obj, name, module, source_lines, globs, seen):
Tim Peters8485b562004-08-04 18:46:34 +00001010 """
1011 Find tests for the given object and any contained objects, and
1012 add them to `tests`.
1013 """
1014 if self._verbose:
1015 print 'Finding tests in %s' % name
1016
1017 # If we've already processed this object, then ignore it.
1018 if id(obj) in seen:
1019 return
1020 seen[id(obj)] = 1
1021
1022 # Find a test for this object, and add it to the list of tests.
1023 test = self._get_test(obj, name, module, globs, source_lines)
1024 if test is not None:
1025 tests.append(test)
1026
1027 # Look for tests in a module's contained objects.
1028 if inspect.ismodule(obj) and self._recurse:
1029 for valname, val in obj.__dict__.items():
1030 # Check if this contained object should be ignored.
1031 if self._filter(val, name, valname):
1032 continue
1033 valname = '%s.%s' % (name, valname)
1034 # Recurse to functions & classes.
1035 if ((inspect.isfunction(val) or inspect.isclass(val)) and
Tim Petersf3f57472004-08-08 06:11:48 +00001036 self._from_module(module, val)):
Tim Peters8485b562004-08-04 18:46:34 +00001037 self._find(tests, val, valname, module, source_lines,
Tim Petersf3f57472004-08-08 06:11:48 +00001038 globs, seen)
Tim Peters8485b562004-08-04 18:46:34 +00001039
1040 # Look for tests in a module's __test__ dictionary.
1041 if inspect.ismodule(obj) and self._recurse:
1042 for valname, val in getattr(obj, '__test__', {}).items():
1043 if not isinstance(valname, basestring):
1044 raise ValueError("DocTestFinder.find: __test__ keys "
1045 "must be strings: %r" %
1046 (type(valname),))
1047 if not (inspect.isfunction(val) or inspect.isclass(val) or
1048 inspect.ismethod(val) or inspect.ismodule(val) or
1049 isinstance(val, basestring)):
1050 raise ValueError("DocTestFinder.find: __test__ values "
1051 "must be strings, functions, methods, "
1052 "classes, or modules: %r" %
1053 (type(val),))
1054 valname = '%s.%s' % (name, valname)
1055 self._find(tests, val, valname, module, source_lines,
Tim Petersf3f57472004-08-08 06:11:48 +00001056 globs, seen)
Tim Peters8485b562004-08-04 18:46:34 +00001057
1058 # Look for tests in a class's contained objects.
1059 if inspect.isclass(obj) and self._recurse:
1060 for valname, val in obj.__dict__.items():
1061 # Check if this contained object should be ignored.
1062 if self._filter(val, name, valname):
1063 continue
1064 # Special handling for staticmethod/classmethod.
1065 if isinstance(val, staticmethod):
1066 val = getattr(obj, valname)
1067 if isinstance(val, classmethod):
1068 val = getattr(obj, valname).im_func
1069
1070 # Recurse to methods, properties, and nested classes.
1071 if ((inspect.isfunction(val) or inspect.isclass(val) or
Tim Petersf3f57472004-08-08 06:11:48 +00001072 isinstance(val, property)) and
1073 self._from_module(module, val)):
Tim Peters8485b562004-08-04 18:46:34 +00001074 valname = '%s.%s' % (name, valname)
1075 self._find(tests, val, valname, module, source_lines,
Tim Petersf3f57472004-08-08 06:11:48 +00001076 globs, seen)
Tim Peters8485b562004-08-04 18:46:34 +00001077
1078 def _get_test(self, obj, name, module, globs, source_lines):
1079 """
1080 Return a DocTest for the given object, if it defines a docstring;
1081 otherwise, return None.
1082 """
1083 # Extract the object's docstring. If it doesn't have one,
1084 # then return None (no test for this object).
1085 if isinstance(obj, basestring):
1086 docstring = obj
1087 else:
1088 try:
1089 if obj.__doc__ is None:
1090 return None
1091 docstring = str(obj.__doc__)
1092 except (TypeError, AttributeError):
1093 return None
1094
1095 # Don't bother if the docstring is empty.
1096 if not docstring:
1097 return None
1098
1099 # Find the docstring's location in the file.
1100 lineno = self._find_lineno(obj, source_lines)
1101
1102 # Return a DocTest for this object.
1103 if module is None:
1104 filename = None
1105 else:
1106 filename = getattr(module, '__file__', module.__name__)
Jim Fulton07a349c2004-08-22 14:10:00 +00001107 if filename[-4:] in (".pyc", ".pyo"):
1108 filename = filename[:-1]
Edward Lopera1ef6112004-08-09 16:14:41 +00001109 return self._parser.get_doctest(docstring, globs, name,
1110 filename, lineno)
Tim Peters8485b562004-08-04 18:46:34 +00001111
1112 def _find_lineno(self, obj, source_lines):
1113 """
1114 Return a line number of the given object's docstring. Note:
1115 this method assumes that the object has a docstring.
1116 """
1117 lineno = None
1118
1119 # Find the line number for modules.
1120 if inspect.ismodule(obj):
1121 lineno = 0
1122
1123 # Find the line number for classes.
1124 # Note: this could be fooled if a class is defined multiple
1125 # times in a single file.
1126 if inspect.isclass(obj):
1127 if source_lines is None:
1128 return None
1129 pat = re.compile(r'^\s*class\s*%s\b' %
1130 getattr(obj, '__name__', '-'))
1131 for i, line in enumerate(source_lines):
1132 if pat.match(line):
1133 lineno = i
1134 break
1135
1136 # Find the line number for functions & methods.
1137 if inspect.ismethod(obj): obj = obj.im_func
1138 if inspect.isfunction(obj): obj = obj.func_code
1139 if inspect.istraceback(obj): obj = obj.tb_frame
1140 if inspect.isframe(obj): obj = obj.f_code
1141 if inspect.iscode(obj):
1142 lineno = getattr(obj, 'co_firstlineno', None)-1
1143
1144 # Find the line number where the docstring starts. Assume
1145 # that it's the first line that begins with a quote mark.
1146 # Note: this could be fooled by a multiline function
1147 # signature, where a continuation line begins with a quote
1148 # mark.
1149 if lineno is not None:
1150 if source_lines is None:
1151 return lineno+1
1152 pat = re.compile('(^|.*:)\s*\w*("|\')')
1153 for lineno in range(lineno, len(source_lines)):
1154 if pat.match(source_lines[lineno]):
1155 return lineno
1156
1157 # We couldn't find the line number.
1158 return None
1159
1160######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00001161## 5. DocTest Runner
Tim Peters8485b562004-08-04 18:46:34 +00001162######################################################################
1163
Tim Peters8485b562004-08-04 18:46:34 +00001164class DocTestRunner:
1165 """
1166 A class used to run DocTest test cases, and accumulate statistics.
1167 The `run` method is used to process a single DocTest case. It
1168 returns a tuple `(f, t)`, where `t` is the number of test cases
1169 tried, and `f` is the number of test cases that failed.
1170
1171 >>> tests = DocTestFinder().find(_TestClass)
1172 >>> runner = DocTestRunner(verbose=False)
1173 >>> for test in tests:
1174 ... print runner.run(test)
1175 (0, 2)
1176 (0, 1)
1177 (0, 2)
1178 (0, 2)
1179
1180 The `summarize` method prints a summary of all the test cases that
1181 have been run by the runner, and returns an aggregated `(f, t)`
1182 tuple:
1183
1184 >>> runner.summarize(verbose=1)
1185 4 items passed all tests:
1186 2 tests in _TestClass
1187 2 tests in _TestClass.__init__
1188 2 tests in _TestClass.get
1189 1 tests in _TestClass.square
1190 7 tests in 4 items.
1191 7 passed and 0 failed.
1192 Test passed.
1193 (0, 7)
1194
1195 The aggregated number of tried examples and failed examples is
1196 also available via the `tries` and `failures` attributes:
1197
1198 >>> runner.tries
1199 7
1200 >>> runner.failures
1201 0
1202
1203 The comparison between expected outputs and actual outputs is done
Edward Loper34fcb142004-08-09 02:45:41 +00001204 by an `OutputChecker`. This comparison may be customized with a
1205 number of option flags; see the documentation for `testmod` for
1206 more information. If the option flags are insufficient, then the
1207 comparison may also be customized by passing a subclass of
1208 `OutputChecker` to the constructor.
Tim Peters8485b562004-08-04 18:46:34 +00001209
1210 The test runner's display output can be controlled in two ways.
1211 First, an output function (`out) can be passed to
1212 `TestRunner.run`; this function will be called with strings that
1213 should be displayed. It defaults to `sys.stdout.write`. If
1214 capturing the output is not sufficient, then the display output
1215 can be also customized by subclassing DocTestRunner, and
1216 overriding the methods `report_start`, `report_success`,
1217 `report_unexpected_exception`, and `report_failure`.
1218 """
1219 # This divider string is used to separate failure messages, and to
1220 # separate sections of the summary.
1221 DIVIDER = "*" * 70
1222
Edward Loper34fcb142004-08-09 02:45:41 +00001223 def __init__(self, checker=None, verbose=None, optionflags=0):
Tim Peters8485b562004-08-04 18:46:34 +00001224 """
1225 Create a new test runner.
1226
Edward Loper34fcb142004-08-09 02:45:41 +00001227 Optional keyword arg `checker` is the `OutputChecker` that
1228 should be used to compare the expected outputs and actual
1229 outputs of doctest examples.
1230
Tim Peters8485b562004-08-04 18:46:34 +00001231 Optional keyword arg 'verbose' prints lots of stuff if true,
1232 only failures if false; by default, it's true iff '-v' is in
1233 sys.argv.
1234
1235 Optional argument `optionflags` can be used to control how the
1236 test runner compares expected output to actual output, and how
1237 it displays failures. See the documentation for `testmod` for
1238 more information.
1239 """
Edward Loper34fcb142004-08-09 02:45:41 +00001240 self._checker = checker or OutputChecker()
Tim Peters8a7d2d52001-01-16 07:10:57 +00001241 if verbose is None:
Tim Peters8485b562004-08-04 18:46:34 +00001242 verbose = '-v' in sys.argv
1243 self._verbose = verbose
Tim Peters6ebe61f2003-06-27 20:48:05 +00001244 self.optionflags = optionflags
Jim Fulton07a349c2004-08-22 14:10:00 +00001245 self.original_optionflags = optionflags
Tim Peters6ebe61f2003-06-27 20:48:05 +00001246
Tim Peters8485b562004-08-04 18:46:34 +00001247 # Keep track of the examples we've run.
1248 self.tries = 0
1249 self.failures = 0
1250 self._name2ft = {}
Tim Peters8a7d2d52001-01-16 07:10:57 +00001251
Tim Peters8485b562004-08-04 18:46:34 +00001252 # Create a fake output target for capturing doctest output.
1253 self._fakeout = _SpoofOut()
Tim Peters4fd9e2f2001-08-18 00:05:50 +00001254
Tim Peters8485b562004-08-04 18:46:34 +00001255 #/////////////////////////////////////////////////////////////////
Tim Peters8485b562004-08-04 18:46:34 +00001256 # Reporting methods
1257 #/////////////////////////////////////////////////////////////////
Tim Peters17111f32001-10-03 04:08:26 +00001258
Tim Peters8485b562004-08-04 18:46:34 +00001259 def report_start(self, out, test, example):
Tim Peters8a7d2d52001-01-16 07:10:57 +00001260 """
Tim Peters8485b562004-08-04 18:46:34 +00001261 Report that the test runner is about to process the given
1262 example. (Only displays a message if verbose=True)
1263 """
1264 if self._verbose:
Edward Loperaacf0832004-08-26 01:19:50 +00001265 if example.want:
1266 out('Trying:\n' + _indent(example.source) +
1267 'Expecting:\n' + _indent(example.want))
1268 else:
1269 out('Trying:\n' + _indent(example.source) +
1270 'Expecting nothing\n')
Tim Peters8a7d2d52001-01-16 07:10:57 +00001271
Tim Peters8485b562004-08-04 18:46:34 +00001272 def report_success(self, out, test, example, got):
1273 """
1274 Report that the given example ran successfully. (Only
1275 displays a message if verbose=True)
1276 """
1277 if self._verbose:
1278 out("ok\n")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001279
Tim Peters8485b562004-08-04 18:46:34 +00001280 def report_failure(self, out, test, example, got):
1281 """
1282 Report that the given example failed.
1283 """
Edward Loper8e4a34b2004-08-12 02:34:27 +00001284 out(self._failure_header(test, example) +
Edward Loperca9111e2004-08-26 03:00:24 +00001285 self._checker.output_difference(example, got, self.optionflags))
Tim Peters7402f792001-10-02 03:53:41 +00001286
Tim Peters8485b562004-08-04 18:46:34 +00001287 def report_unexpected_exception(self, out, test, example, exc_info):
1288 """
1289 Report that the given example raised an unexpected exception.
1290 """
Edward Loper8e4a34b2004-08-12 02:34:27 +00001291 out(self._failure_header(test, example) +
Edward Loperaacf0832004-08-26 01:19:50 +00001292 'Exception raised:\n' + _indent(_exception_traceback(exc_info)))
Tim Peters7402f792001-10-02 03:53:41 +00001293
Edward Loper8e4a34b2004-08-12 02:34:27 +00001294 def _failure_header(self, test, example):
Jim Fulton07a349c2004-08-22 14:10:00 +00001295 out = [self.DIVIDER]
1296 if test.filename:
1297 if test.lineno is not None and example.lineno is not None:
1298 lineno = test.lineno + example.lineno + 1
1299 else:
1300 lineno = '?'
1301 out.append('File "%s", line %s, in %s' %
1302 (test.filename, lineno, test.name))
Tim Peters8485b562004-08-04 18:46:34 +00001303 else:
Jim Fulton07a349c2004-08-22 14:10:00 +00001304 out.append('Line %s, in %s' % (example.lineno+1, test.name))
1305 out.append('Failed example:')
1306 source = example.source
Edward Loperaacf0832004-08-26 01:19:50 +00001307 out.append(_indent(source))
1308 return '\n'.join(out)
Tim Peters7402f792001-10-02 03:53:41 +00001309
Tim Peters8485b562004-08-04 18:46:34 +00001310 #/////////////////////////////////////////////////////////////////
1311 # DocTest Running
1312 #/////////////////////////////////////////////////////////////////
Tim Peters7402f792001-10-02 03:53:41 +00001313
Tim Peters8485b562004-08-04 18:46:34 +00001314 def __run(self, test, compileflags, out):
Tim Peters8a7d2d52001-01-16 07:10:57 +00001315 """
Tim Peters8485b562004-08-04 18:46:34 +00001316 Run the examples in `test`. Write the outcome of each example
1317 with one of the `DocTestRunner.report_*` methods, using the
1318 writer function `out`. `compileflags` is the set of compiler
1319 flags that should be used to execute examples. Return a tuple
1320 `(f, t)`, where `t` is the number of examples tried, and `f`
1321 is the number of examples that failed. The examples are run
1322 in the namespace `test.globs`.
1323 """
1324 # Keep track of the number of failures and tries.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001325 failures = tries = 0
Tim Peters8485b562004-08-04 18:46:34 +00001326
1327 # Save the option flags (since option directives can be used
1328 # to modify them).
1329 original_optionflags = self.optionflags
1330
1331 # Process each example.
1332 for example in test.examples:
Edward Lopera89f88d2004-08-26 02:45:51 +00001333 # If REPORT_ONLY_FIRST_FAILURE is set, then supress
1334 # reporting after the first failure.
1335 quiet = (self.optionflags & REPORT_ONLY_FIRST_FAILURE and
1336 failures > 0)
1337
Edward Loper74bca7a2004-08-12 02:27:44 +00001338 # Merge in the example's options.
1339 self.optionflags = original_optionflags
1340 if example.options:
1341 for (optionflag, val) in example.options.items():
1342 if val:
1343 self.optionflags |= optionflag
1344 else:
1345 self.optionflags &= ~optionflag
Tim Peters8485b562004-08-04 18:46:34 +00001346
1347 # Record that we started this example.
1348 tries += 1
Edward Lopera89f88d2004-08-26 02:45:51 +00001349 if not quiet:
1350 self.report_start(out, test, example)
Tim Peters8485b562004-08-04 18:46:34 +00001351
1352 # Run the example in the given context (globs), and record
1353 # any exception that gets raised. (But don't intercept
1354 # keyboard interrupts.)
1355 try:
Tim Peters208ca702004-08-09 04:12:36 +00001356 # Don't blink! This is where the user's code gets run.
Tim Petersbb431472004-08-09 03:51:46 +00001357 exec compile(example.source, "<string>", "single",
Tim Peters8485b562004-08-04 18:46:34 +00001358 compileflags, 1) in test.globs
1359 exception = None
1360 except KeyboardInterrupt:
1361 raise
1362 except:
1363 exception = sys.exc_info()
1364
Tim Peters208ca702004-08-09 04:12:36 +00001365 got = self._fakeout.getvalue() # the actual output
Tim Peters8485b562004-08-04 18:46:34 +00001366 self._fakeout.truncate(0)
1367
1368 # If the example executed without raising any exceptions,
1369 # then verify its output and report its outcome.
1370 if exception is None:
Edward Loper34fcb142004-08-09 02:45:41 +00001371 if self._checker.check_output(example.want, got,
1372 self.optionflags):
Edward Lopera89f88d2004-08-26 02:45:51 +00001373 if not quiet:
1374 self.report_success(out, test, example, got)
Tim Peters8a7d2d52001-01-16 07:10:57 +00001375 else:
Edward Lopera89f88d2004-08-26 02:45:51 +00001376 if not quiet:
1377 self.report_failure(out, test, example, got)
Tim Peters8485b562004-08-04 18:46:34 +00001378 failures += 1
1379
1380 # If the example raised an exception, then check if it was
1381 # expected.
1382 else:
1383 exc_info = sys.exc_info()
1384 exc_msg = traceback.format_exception_only(*exc_info[:2])[-1]
1385
Edward Lopera6b68322004-08-26 00:05:43 +00001386 # If `example.exc_msg` is None, then we weren't
1387 # expecting an exception.
1388 if example.exc_msg is None:
Edward Lopera89f88d2004-08-26 02:45:51 +00001389 if not quiet:
1390 self.report_unexpected_exception(out, test, example,
1391 exc_info)
Tim Peters8485b562004-08-04 18:46:34 +00001392 failures += 1
Edward Lopera6b68322004-08-26 00:05:43 +00001393 # If `example.exc_msg` matches the actual exception
1394 # message (`exc_msg`), then the example succeeds.
1395 elif (self._checker.check_output(example.exc_msg, exc_msg,
1396 self.optionflags)):
Edward Lopera89f88d2004-08-26 02:45:51 +00001397 if not quiet:
1398 got += _exception_traceback(exc_info)
1399 self.report_success(out, test, example, got)
Edward Lopera6b68322004-08-26 00:05:43 +00001400 # Otherwise, the example fails.
Tim Peters8485b562004-08-04 18:46:34 +00001401 else:
Edward Lopera89f88d2004-08-26 02:45:51 +00001402 if not quiet:
1403 got += _exception_traceback(exc_info)
1404 self.report_failure(out, test, example, got)
Edward Lopera6b68322004-08-26 00:05:43 +00001405 failures += 1
Tim Peters8485b562004-08-04 18:46:34 +00001406
1407 # Restore the option flags (in case they were modified)
1408 self.optionflags = original_optionflags
1409
1410 # Record and return the number of failures and tries.
1411 self.__record_outcome(test, failures, tries)
Tim Peters8a7d2d52001-01-16 07:10:57 +00001412 return failures, tries
1413
Tim Peters8485b562004-08-04 18:46:34 +00001414 def __record_outcome(self, test, f, t):
1415 """
1416 Record the fact that the given DocTest (`test`) generated `f`
1417 failures out of `t` tried examples.
1418 """
1419 f2, t2 = self._name2ft.get(test.name, (0,0))
1420 self._name2ft[test.name] = (f+f2, t+t2)
1421 self.failures += f
1422 self.tries += t
1423
1424 def run(self, test, compileflags=None, out=None, clear_globs=True):
1425 """
1426 Run the examples in `test`, and display the results using the
1427 writer function `out`.
1428
1429 The examples are run in the namespace `test.globs`. If
1430 `clear_globs` is true (the default), then this namespace will
1431 be cleared after the test runs, to help with garbage
1432 collection. If you would like to examine the namespace after
1433 the test completes, then use `clear_globs=False`.
1434
1435 `compileflags` gives the set of flags that should be used by
1436 the Python compiler when running the examples. If not
1437 specified, then it will default to the set of future-import
1438 flags that apply to `globs`.
1439
1440 The output of each example is checked using
1441 `DocTestRunner.check_output`, and the results are formatted by
1442 the `DocTestRunner.report_*` methods.
1443 """
1444 if compileflags is None:
1445 compileflags = _extract_future_flags(test.globs)
Jim Fulton356fd192004-08-09 11:34:47 +00001446
Tim Peters6c542b72004-08-09 16:43:36 +00001447 save_stdout = sys.stdout
Tim Peters8485b562004-08-04 18:46:34 +00001448 if out is None:
Tim Peters6c542b72004-08-09 16:43:36 +00001449 out = save_stdout.write
1450 sys.stdout = self._fakeout
Tim Peters8485b562004-08-04 18:46:34 +00001451
Tim Peters6c542b72004-08-09 16:43:36 +00001452 # Patch pdb.set_trace to restore sys.stdout, so that interactive
1453 # debugging output is visible (not still redirected to self._fakeout).
1454 # Note that we run "the real" pdb.set_trace (captured at doctest
1455 # import time) in our replacement. Because the current run() may
1456 # run another doctest (and so on), the current pdb.set_trace may be
1457 # our set_trace function, which changes sys.stdout. If we called
1458 # a chain of those, we wouldn't be left with the save_stdout
1459 # *this* run() invocation wants.
Jim Fulton356fd192004-08-09 11:34:47 +00001460 def set_trace():
Tim Peters6c542b72004-08-09 16:43:36 +00001461 sys.stdout = save_stdout
Jim Fulton356fd192004-08-09 11:34:47 +00001462 real_pdb_set_trace()
1463
Tim Peters6c542b72004-08-09 16:43:36 +00001464 save_set_trace = pdb.set_trace
1465 pdb.set_trace = set_trace
Tim Peters8485b562004-08-04 18:46:34 +00001466 try:
Tim Peters8485b562004-08-04 18:46:34 +00001467 return self.__run(test, compileflags, out)
1468 finally:
Tim Peters6c542b72004-08-09 16:43:36 +00001469 sys.stdout = save_stdout
1470 pdb.set_trace = save_set_trace
Tim Peters8485b562004-08-04 18:46:34 +00001471 if clear_globs:
1472 test.globs.clear()
1473
1474 #/////////////////////////////////////////////////////////////////
1475 # Summarization
1476 #/////////////////////////////////////////////////////////////////
Tim Peters8a7d2d52001-01-16 07:10:57 +00001477 def summarize(self, verbose=None):
1478 """
Tim Peters8485b562004-08-04 18:46:34 +00001479 Print a summary of all the test cases that have been run by
1480 this DocTestRunner, and return a tuple `(f, t)`, where `f` is
1481 the total number of failed examples, and `t` is the total
1482 number of tried examples.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001483
Tim Peters8485b562004-08-04 18:46:34 +00001484 The optional `verbose` argument controls how detailed the
1485 summary is. If the verbosity is not specified, then the
1486 DocTestRunner's verbosity is used.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001487 """
Tim Peters8a7d2d52001-01-16 07:10:57 +00001488 if verbose is None:
Tim Peters8485b562004-08-04 18:46:34 +00001489 verbose = self._verbose
Tim Peters8a7d2d52001-01-16 07:10:57 +00001490 notests = []
1491 passed = []
1492 failed = []
1493 totalt = totalf = 0
Tim Peters8485b562004-08-04 18:46:34 +00001494 for x in self._name2ft.items():
Tim Peters8a7d2d52001-01-16 07:10:57 +00001495 name, (f, t) = x
1496 assert f <= t
Tim Peters8485b562004-08-04 18:46:34 +00001497 totalt += t
1498 totalf += f
Tim Peters8a7d2d52001-01-16 07:10:57 +00001499 if t == 0:
1500 notests.append(name)
1501 elif f == 0:
1502 passed.append( (name, t) )
1503 else:
1504 failed.append(x)
1505 if verbose:
1506 if notests:
1507 print len(notests), "items had no tests:"
1508 notests.sort()
1509 for thing in notests:
1510 print " ", thing
1511 if passed:
1512 print len(passed), "items passed all tests:"
1513 passed.sort()
1514 for thing, count in passed:
1515 print " %3d tests in %s" % (count, thing)
1516 if failed:
Tim Peters8485b562004-08-04 18:46:34 +00001517 print self.DIVIDER
Tim Peters8a7d2d52001-01-16 07:10:57 +00001518 print len(failed), "items had failures:"
1519 failed.sort()
1520 for thing, (f, t) in failed:
1521 print " %3d of %3d in %s" % (f, t, thing)
1522 if verbose:
Tim Peters8485b562004-08-04 18:46:34 +00001523 print totalt, "tests in", len(self._name2ft), "items."
Tim Peters8a7d2d52001-01-16 07:10:57 +00001524 print totalt - totalf, "passed and", totalf, "failed."
1525 if totalf:
1526 print "***Test Failed***", totalf, "failures."
1527 elif verbose:
1528 print "Test passed."
1529 return totalf, totalt
1530
Edward Loper34fcb142004-08-09 02:45:41 +00001531class OutputChecker:
1532 """
1533 A class used to check the whether the actual output from a doctest
1534 example matches the expected output. `OutputChecker` defines two
1535 methods: `check_output`, which compares a given pair of outputs,
1536 and returns true if they match; and `output_difference`, which
1537 returns a string describing the differences between two outputs.
1538 """
1539 def check_output(self, want, got, optionflags):
1540 """
Edward Loper74bca7a2004-08-12 02:27:44 +00001541 Return True iff the actual output from an example (`got`)
1542 matches the expected output (`want`). These strings are
1543 always considered to match if they are identical; but
1544 depending on what option flags the test runner is using,
1545 several non-exact match types are also possible. See the
1546 documentation for `TestRunner` for more information about
1547 option flags.
Edward Loper34fcb142004-08-09 02:45:41 +00001548 """
1549 # Handle the common case first, for efficiency:
1550 # if they're string-identical, always return true.
1551 if got == want:
1552 return True
1553
1554 # The values True and False replaced 1 and 0 as the return
1555 # value for boolean comparisons in Python 2.3.
1556 if not (optionflags & DONT_ACCEPT_TRUE_FOR_1):
1557 if (got,want) == ("True\n", "1\n"):
1558 return True
1559 if (got,want) == ("False\n", "0\n"):
1560 return True
1561
1562 # <BLANKLINE> can be used as a special sequence to signify a
1563 # blank line, unless the DONT_ACCEPT_BLANKLINE flag is used.
1564 if not (optionflags & DONT_ACCEPT_BLANKLINE):
1565 # Replace <BLANKLINE> in want with a blank line.
1566 want = re.sub('(?m)^%s\s*?$' % re.escape(BLANKLINE_MARKER),
1567 '', want)
1568 # If a line in got contains only spaces, then remove the
1569 # spaces.
1570 got = re.sub('(?m)^\s*?$', '', got)
1571 if got == want:
1572 return True
1573
1574 # This flag causes doctest to ignore any differences in the
1575 # contents of whitespace strings. Note that this can be used
Tim Peters3fa8c202004-08-23 21:43:39 +00001576 # in conjunction with the ELLIPSIS flag.
Tim Peters1cf3aa62004-08-19 06:49:33 +00001577 if optionflags & NORMALIZE_WHITESPACE:
Edward Loper34fcb142004-08-09 02:45:41 +00001578 got = ' '.join(got.split())
1579 want = ' '.join(want.split())
1580 if got == want:
1581 return True
1582
1583 # The ELLIPSIS flag says to let the sequence "..." in `want`
Tim Peters26b3ebb2004-08-19 08:10:08 +00001584 # match any substring in `got`.
Tim Peters1cf3aa62004-08-19 06:49:33 +00001585 if optionflags & ELLIPSIS:
Tim Petersb0a04e12004-08-20 02:08:04 +00001586 if _ellipsis_match(want, got):
Edward Loper34fcb142004-08-09 02:45:41 +00001587 return True
1588
1589 # We didn't find any match; return false.
1590 return False
1591
Tim Petersc6cbab02004-08-22 19:43:28 +00001592 # Should we do a fancy diff?
1593 def _do_a_fancy_diff(self, want, got, optionflags):
1594 # Not unless they asked for a fancy diff.
Edward Loper71f55af2004-08-26 01:41:51 +00001595 if not optionflags & (REPORT_UDIFF |
1596 REPORT_CDIFF |
1597 REPORT_NDIFF):
Tim Petersc6cbab02004-08-22 19:43:28 +00001598 return False
Tim Peters5b799c12004-08-26 05:21:59 +00001599
Tim Petersc6cbab02004-08-22 19:43:28 +00001600 # If expected output uses ellipsis, a meaningful fancy diff is
Tim Peters5b799c12004-08-26 05:21:59 +00001601 # too hard ... or maybe not. In two real-life failures Tim saw,
1602 # a diff was a major help anyway, so this is commented out.
1603 # [todo] _ellipsis_match() knows which pieces do and don't match,
1604 # and could be the basis for a kick-ass diff in this case.
1605 ##if optionflags & ELLIPSIS and ELLIPSIS_MARKER in want:
1606 ## return False
1607
Tim Petersc6cbab02004-08-22 19:43:28 +00001608 # ndiff does intraline difference marking, so can be useful even
Tim Peters5b799c12004-08-26 05:21:59 +00001609 # for 1-line differences.
Edward Loper71f55af2004-08-26 01:41:51 +00001610 if optionflags & REPORT_NDIFF:
Tim Petersc6cbab02004-08-22 19:43:28 +00001611 return True
Tim Peters5b799c12004-08-26 05:21:59 +00001612
Tim Petersc6cbab02004-08-22 19:43:28 +00001613 # The other diff types need at least a few lines to be helpful.
1614 return want.count('\n') > 2 and got.count('\n') > 2
1615
Edward Loperca9111e2004-08-26 03:00:24 +00001616 def output_difference(self, example, got, optionflags):
Edward Loper34fcb142004-08-09 02:45:41 +00001617 """
1618 Return a string describing the differences between the
Edward Loperca9111e2004-08-26 03:00:24 +00001619 expected output for a given example (`example`) and the actual
1620 output (`got`). `optionflags` is the set of option flags used
1621 to compare `want` and `got`.
Edward Loper34fcb142004-08-09 02:45:41 +00001622 """
Edward Loperca9111e2004-08-26 03:00:24 +00001623 want = example.want
Edward Loper68ba9a62004-08-12 02:43:49 +00001624 # If <BLANKLINE>s are being used, then replace blank lines
1625 # with <BLANKLINE> in the actual output string.
Edward Loper34fcb142004-08-09 02:45:41 +00001626 if not (optionflags & DONT_ACCEPT_BLANKLINE):
Edward Loper68ba9a62004-08-12 02:43:49 +00001627 got = re.sub('(?m)^[ ]*(?=\n)', BLANKLINE_MARKER, got)
Edward Loper34fcb142004-08-09 02:45:41 +00001628
Tim Peters5b799c12004-08-26 05:21:59 +00001629 # Check if we should use diff.
Tim Petersc6cbab02004-08-22 19:43:28 +00001630 if self._do_a_fancy_diff(want, got, optionflags):
Edward Loper34fcb142004-08-09 02:45:41 +00001631 # Split want & got into lines.
1632 want_lines = [l+'\n' for l in want.split('\n')]
1633 got_lines = [l+'\n' for l in got.split('\n')]
1634 # Use difflib to find their differences.
Edward Loper71f55af2004-08-26 01:41:51 +00001635 if optionflags & REPORT_UDIFF:
Edward Loper56629292004-08-26 01:31:56 +00001636 diff = difflib.unified_diff(want_lines, got_lines, n=2)
1637 diff = list(diff)[2:] # strip the diff header
1638 kind = 'unified diff with -expected +actual'
Edward Loper71f55af2004-08-26 01:41:51 +00001639 elif optionflags & REPORT_CDIFF:
Edward Loper56629292004-08-26 01:31:56 +00001640 diff = difflib.context_diff(want_lines, got_lines, n=2)
1641 diff = list(diff)[2:] # strip the diff header
1642 kind = 'context diff with expected followed by actual'
Edward Loper71f55af2004-08-26 01:41:51 +00001643 elif optionflags & REPORT_NDIFF:
Tim Petersc6cbab02004-08-22 19:43:28 +00001644 engine = difflib.Differ(charjunk=difflib.IS_CHARACTER_JUNK)
1645 diff = list(engine.compare(want_lines, got_lines))
1646 kind = 'ndiff with -expected +actual'
Edward Loper34fcb142004-08-09 02:45:41 +00001647 else:
1648 assert 0, 'Bad diff option'
1649 # Remove trailing whitespace on diff output.
1650 diff = [line.rstrip() + '\n' for line in diff]
Edward Loperaacf0832004-08-26 01:19:50 +00001651 return 'Differences (%s):\n' % kind + _indent(''.join(diff))
Edward Loper34fcb142004-08-09 02:45:41 +00001652
1653 # If we're not using diff, then simply list the expected
1654 # output followed by the actual output.
Edward Loperaacf0832004-08-26 01:19:50 +00001655 if want and got:
1656 return 'Expected:\n%sGot:\n%s' % (_indent(want), _indent(got))
1657 elif want:
1658 return 'Expected:\n%sGot nothing\n' % _indent(want)
1659 elif got:
1660 return 'Expected nothing\nGot:\n%s' % _indent(got)
1661 else:
1662 return 'Expected nothing\nGot nothing\n'
Edward Loper34fcb142004-08-09 02:45:41 +00001663
Tim Peters19397e52004-08-06 22:02:59 +00001664class DocTestFailure(Exception):
1665 """A DocTest example has failed in debugging mode.
1666
1667 The exception instance has variables:
1668
1669 - test: the DocTest object being run
1670
1671 - excample: the Example object that failed
1672
1673 - got: the actual output
1674 """
1675 def __init__(self, test, example, got):
1676 self.test = test
1677 self.example = example
1678 self.got = got
1679
1680 def __str__(self):
1681 return str(self.test)
1682
1683class UnexpectedException(Exception):
1684 """A DocTest example has encountered an unexpected exception
1685
1686 The exception instance has variables:
1687
1688 - test: the DocTest object being run
1689
1690 - excample: the Example object that failed
1691
1692 - exc_info: the exception info
1693 """
1694 def __init__(self, test, example, exc_info):
1695 self.test = test
1696 self.example = example
1697 self.exc_info = exc_info
1698
1699 def __str__(self):
1700 return str(self.test)
Tim Petersd1b78272004-08-07 06:03:09 +00001701
Tim Peters19397e52004-08-06 22:02:59 +00001702class DebugRunner(DocTestRunner):
1703 r"""Run doc tests but raise an exception as soon as there is a failure.
1704
1705 If an unexpected exception occurs, an UnexpectedException is raised.
1706 It contains the test, the example, and the original exception:
1707
1708 >>> runner = DebugRunner(verbose=False)
Edward Lopera1ef6112004-08-09 16:14:41 +00001709 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
1710 ... {}, 'foo', 'foo.py', 0)
Tim Peters19397e52004-08-06 22:02:59 +00001711 >>> try:
1712 ... runner.run(test)
1713 ... except UnexpectedException, failure:
1714 ... pass
1715
1716 >>> failure.test is test
1717 True
1718
1719 >>> failure.example.want
1720 '42\n'
1721
1722 >>> exc_info = failure.exc_info
1723 >>> raise exc_info[0], exc_info[1], exc_info[2]
1724 Traceback (most recent call last):
1725 ...
1726 KeyError
1727
1728 We wrap the original exception to give the calling application
1729 access to the test and example information.
1730
1731 If the output doesn't match, then a DocTestFailure is raised:
1732
Edward Lopera1ef6112004-08-09 16:14:41 +00001733 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00001734 ... >>> x = 1
1735 ... >>> x
1736 ... 2
1737 ... ''', {}, 'foo', 'foo.py', 0)
1738
1739 >>> try:
1740 ... runner.run(test)
1741 ... except DocTestFailure, failure:
1742 ... pass
1743
1744 DocTestFailure objects provide access to the test:
1745
1746 >>> failure.test is test
1747 True
1748
1749 As well as to the example:
1750
1751 >>> failure.example.want
1752 '2\n'
1753
1754 and the actual output:
1755
1756 >>> failure.got
1757 '1\n'
1758
1759 If a failure or error occurs, the globals are left intact:
1760
1761 >>> del test.globs['__builtins__']
1762 >>> test.globs
1763 {'x': 1}
1764
Edward Lopera1ef6112004-08-09 16:14:41 +00001765 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00001766 ... >>> x = 2
1767 ... >>> raise KeyError
1768 ... ''', {}, 'foo', 'foo.py', 0)
1769
1770 >>> runner.run(test)
1771 Traceback (most recent call last):
1772 ...
1773 UnexpectedException: <DocTest foo from foo.py:0 (2 examples)>
Tim Petersd1b78272004-08-07 06:03:09 +00001774
Tim Peters19397e52004-08-06 22:02:59 +00001775 >>> del test.globs['__builtins__']
1776 >>> test.globs
1777 {'x': 2}
1778
1779 But the globals are cleared if there is no error:
1780
Edward Lopera1ef6112004-08-09 16:14:41 +00001781 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00001782 ... >>> x = 2
1783 ... ''', {}, 'foo', 'foo.py', 0)
1784
1785 >>> runner.run(test)
1786 (0, 1)
1787
1788 >>> test.globs
1789 {}
1790
1791 """
1792
1793 def run(self, test, compileflags=None, out=None, clear_globs=True):
1794 r = DocTestRunner.run(self, test, compileflags, out, False)
1795 if clear_globs:
1796 test.globs.clear()
1797 return r
1798
1799 def report_unexpected_exception(self, out, test, example, exc_info):
1800 raise UnexpectedException(test, example, exc_info)
1801
1802 def report_failure(self, out, test, example, got):
1803 raise DocTestFailure(test, example, got)
1804
Tim Peters8485b562004-08-04 18:46:34 +00001805######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00001806## 6. Test Functions
Tim Peters8485b562004-08-04 18:46:34 +00001807######################################################################
1808# These should be backwards compatible.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001809
Martin v. Löwis4581cfa2002-11-22 08:23:09 +00001810def testmod(m=None, name=None, globs=None, verbose=None, isprivate=None,
Tim Peters19397e52004-08-06 22:02:59 +00001811 report=True, optionflags=0, extraglobs=None,
1812 raise_on_error=False):
Tim Peters6ebe61f2003-06-27 20:48:05 +00001813 """m=None, name=None, globs=None, verbose=None, isprivate=None,
Tim Peters8485b562004-08-04 18:46:34 +00001814 report=True, optionflags=0, extraglobs=None
Tim Peters8a7d2d52001-01-16 07:10:57 +00001815
Martin v. Löwis4581cfa2002-11-22 08:23:09 +00001816 Test examples in docstrings in functions and classes reachable
1817 from module m (or the current module if m is not supplied), starting
Raymond Hettinger71adf7e2003-07-16 19:25:22 +00001818 with m.__doc__. Unless isprivate is specified, private names
1819 are not skipped.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001820
1821 Also test examples reachable from dict m.__test__ if it exists and is
Tim Petersc2388a22004-08-10 01:41:28 +00001822 not None. m.__test__ maps names to functions, classes and strings;
Tim Peters8a7d2d52001-01-16 07:10:57 +00001823 function and class docstrings are tested even if the name is private;
1824 strings are tested directly, as if they were docstrings.
1825
1826 Return (#failures, #tests).
1827
1828 See doctest.__doc__ for an overview.
1829
1830 Optional keyword arg "name" gives the name of the module; by default
1831 use m.__name__.
1832
1833 Optional keyword arg "globs" gives a dict to be used as the globals
1834 when executing examples; by default, use m.__dict__. A copy of this
1835 dict is actually used for each docstring, so that each docstring's
1836 examples start with a clean slate.
1837
Tim Peters8485b562004-08-04 18:46:34 +00001838 Optional keyword arg "extraglobs" gives a dictionary that should be
1839 merged into the globals that are used to execute examples. By
1840 default, no extra globals are used. This is new in 2.4.
1841
Tim Peters8a7d2d52001-01-16 07:10:57 +00001842 Optional keyword arg "verbose" prints lots of stuff if true, prints
1843 only failures if false; by default, it's true iff "-v" is in sys.argv.
1844
Tim Peters8a7d2d52001-01-16 07:10:57 +00001845 Optional keyword arg "report" prints a summary at the end when true,
1846 else prints nothing at the end. In verbose mode, the summary is
1847 detailed, else very brief (in fact, empty if all tests passed).
1848
Tim Peters6ebe61f2003-06-27 20:48:05 +00001849 Optional keyword arg "optionflags" or's together module constants,
Tim Petersf82a9de2004-08-22 20:51:53 +00001850 and defaults to 0. This is new in 2.3. Possible values (see the
1851 docs for details):
Tim Peters6ebe61f2003-06-27 20:48:05 +00001852
1853 DONT_ACCEPT_TRUE_FOR_1
Tim Peters8485b562004-08-04 18:46:34 +00001854 DONT_ACCEPT_BLANKLINE
Tim Peters8485b562004-08-04 18:46:34 +00001855 NORMALIZE_WHITESPACE
Tim Peters8485b562004-08-04 18:46:34 +00001856 ELLIPSIS
Edward Loper71f55af2004-08-26 01:41:51 +00001857 REPORT_UDIFF
1858 REPORT_CDIFF
1859 REPORT_NDIFF
Edward Lopera89f88d2004-08-26 02:45:51 +00001860 REPORT_ONLY_FIRST_FAILURE
Tim Peters19397e52004-08-06 22:02:59 +00001861
1862 Optional keyword arg "raise_on_error" raises an exception on the
1863 first unexpected exception or failure. This allows failures to be
1864 post-mortem debugged.
1865
Tim Petersf727c6c2004-08-08 01:48:59 +00001866 Deprecated in Python 2.4:
1867 Optional keyword arg "isprivate" specifies a function used to
1868 determine whether a name is private. The default function is
1869 treat all functions as public. Optionally, "isprivate" can be
1870 set to doctest.is_private to skip over functions marked as private
1871 using the underscore naming convention; see its docs for details.
Tim Peters8485b562004-08-04 18:46:34 +00001872 """
1873
1874 """ [XX] This is no longer true:
Tim Peters8a7d2d52001-01-16 07:10:57 +00001875 Advanced tomfoolery: testmod runs methods of a local instance of
1876 class doctest.Tester, then merges the results into (or creates)
1877 global Tester instance doctest.master. Methods of doctest.master
1878 can be called directly too, if you want to do something unusual.
1879 Passing report=0 to testmod is especially useful then, to delay
1880 displaying a summary. Invoke doctest.master.summarize(verbose)
1881 when you're done fiddling.
1882 """
Tim Petersf727c6c2004-08-08 01:48:59 +00001883 if isprivate is not None:
1884 warnings.warn("the isprivate argument is deprecated; "
1885 "examine DocTestFinder.find() lists instead",
1886 DeprecationWarning)
1887
Tim Peters8485b562004-08-04 18:46:34 +00001888 # If no module was given, then use __main__.
Martin v. Löwis4581cfa2002-11-22 08:23:09 +00001889 if m is None:
Martin v. Löwis4581cfa2002-11-22 08:23:09 +00001890 # DWA - m will still be None if this wasn't invoked from the command
1891 # line, in which case the following TypeError is about as good an error
1892 # as we should expect
1893 m = sys.modules.get('__main__')
1894
Tim Peters8485b562004-08-04 18:46:34 +00001895 # Check that we were actually given a module.
1896 if not inspect.ismodule(m):
Walter Dörwald70a6b492004-02-12 17:35:32 +00001897 raise TypeError("testmod: module required; %r" % (m,))
Tim Peters8485b562004-08-04 18:46:34 +00001898
1899 # If no name was given, then use the module's name.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001900 if name is None:
1901 name = m.__name__
Tim Peters8485b562004-08-04 18:46:34 +00001902
1903 # Find, parse, and run all tests in the given module.
Tim Petersf727c6c2004-08-08 01:48:59 +00001904 finder = DocTestFinder(_namefilter=isprivate)
Tim Peters19397e52004-08-06 22:02:59 +00001905
1906 if raise_on_error:
1907 runner = DebugRunner(verbose=verbose, optionflags=optionflags)
1908 else:
1909 runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1910
Tim Peters8485b562004-08-04 18:46:34 +00001911 for test in finder.find(m, name, globs=globs, extraglobs=extraglobs):
1912 runner.run(test)
1913
Tim Peters8a7d2d52001-01-16 07:10:57 +00001914 if report:
Tim Peters8485b562004-08-04 18:46:34 +00001915 runner.summarize()
Tim Peters8a7d2d52001-01-16 07:10:57 +00001916
Tim Peters8485b562004-08-04 18:46:34 +00001917 return runner.failures, runner.tries
Tim Petersdb3756d2003-06-29 05:30:48 +00001918
Tim Peters8485b562004-08-04 18:46:34 +00001919def run_docstring_examples(f, globs, verbose=False, name="NoName",
1920 compileflags=None, optionflags=0):
1921 """
1922 Test examples in the given object's docstring (`f`), using `globs`
1923 as globals. Optional argument `name` is used in failure messages.
1924 If the optional argument `verbose` is true, then generate output
1925 even if there are no failures.
Tim Petersdb3756d2003-06-29 05:30:48 +00001926
Tim Peters8485b562004-08-04 18:46:34 +00001927 `compileflags` gives the set of flags that should be used by the
1928 Python compiler when running the examples. If not specified, then
1929 it will default to the set of future-import flags that apply to
1930 `globs`.
Tim Petersdb3756d2003-06-29 05:30:48 +00001931
Tim Peters8485b562004-08-04 18:46:34 +00001932 Optional keyword arg `optionflags` specifies options for the
1933 testing and output. See the documentation for `testmod` for more
1934 information.
1935 """
1936 # Find, parse, and run all tests in the given module.
1937 finder = DocTestFinder(verbose=verbose, recurse=False)
1938 runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1939 for test in finder.find(f, name, globs=globs):
1940 runner.run(test, compileflags=compileflags)
Tim Petersdb3756d2003-06-29 05:30:48 +00001941
Tim Peters8485b562004-08-04 18:46:34 +00001942######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00001943## 7. Tester
Tim Peters8485b562004-08-04 18:46:34 +00001944######################################################################
1945# This is provided only for backwards compatibility. It's not
1946# actually used in any way.
Tim Petersdb3756d2003-06-29 05:30:48 +00001947
Tim Peters8485b562004-08-04 18:46:34 +00001948class Tester:
1949 def __init__(self, mod=None, globs=None, verbose=None,
1950 isprivate=None, optionflags=0):
Tim Peters3ddd60a2004-08-08 02:43:33 +00001951
1952 warnings.warn("class Tester is deprecated; "
1953 "use class doctest.DocTestRunner instead",
1954 DeprecationWarning, stacklevel=2)
Tim Peters8485b562004-08-04 18:46:34 +00001955 if mod is None and globs is None:
1956 raise TypeError("Tester.__init__: must specify mod or globs")
1957 if mod is not None and not _ismodule(mod):
1958 raise TypeError("Tester.__init__: mod must be a module; %r" %
1959 (mod,))
1960 if globs is None:
1961 globs = mod.__dict__
1962 self.globs = globs
Tim Petersdb3756d2003-06-29 05:30:48 +00001963
Tim Peters8485b562004-08-04 18:46:34 +00001964 self.verbose = verbose
1965 self.isprivate = isprivate
1966 self.optionflags = optionflags
Tim Petersf727c6c2004-08-08 01:48:59 +00001967 self.testfinder = DocTestFinder(_namefilter=isprivate)
Tim Peters8485b562004-08-04 18:46:34 +00001968 self.testrunner = DocTestRunner(verbose=verbose,
1969 optionflags=optionflags)
Tim Petersdb3756d2003-06-29 05:30:48 +00001970
Tim Peters8485b562004-08-04 18:46:34 +00001971 def runstring(self, s, name):
Edward Lopera1ef6112004-08-09 16:14:41 +00001972 test = DocTestParser().get_doctest(s, self.globs, name, None, None)
Tim Peters8485b562004-08-04 18:46:34 +00001973 if self.verbose:
1974 print "Running string", name
1975 (f,t) = self.testrunner.run(test)
1976 if self.verbose:
1977 print f, "of", t, "examples failed in string", name
1978 return (f,t)
Tim Petersdb3756d2003-06-29 05:30:48 +00001979
Tim Petersf3f57472004-08-08 06:11:48 +00001980 def rundoc(self, object, name=None, module=None):
Tim Peters8485b562004-08-04 18:46:34 +00001981 f = t = 0
1982 tests = self.testfinder.find(object, name, module=module,
Tim Petersf3f57472004-08-08 06:11:48 +00001983 globs=self.globs)
Tim Peters8485b562004-08-04 18:46:34 +00001984 for test in tests:
1985 (f2, t2) = self.testrunner.run(test)
1986 (f,t) = (f+f2, t+t2)
1987 return (f,t)
Tim Petersdb3756d2003-06-29 05:30:48 +00001988
Tim Peters8485b562004-08-04 18:46:34 +00001989 def rundict(self, d, name, module=None):
1990 import new
1991 m = new.module(name)
1992 m.__dict__.update(d)
Tim Petersf3f57472004-08-08 06:11:48 +00001993 if module is None:
1994 module = False
1995 return self.rundoc(m, name, module)
Tim Petersdb3756d2003-06-29 05:30:48 +00001996
Tim Peters8485b562004-08-04 18:46:34 +00001997 def run__test__(self, d, name):
1998 import new
1999 m = new.module(name)
2000 m.__test__ = d
2001 return self.rundoc(m, name, module)
Tim Petersdb3756d2003-06-29 05:30:48 +00002002
Tim Peters8485b562004-08-04 18:46:34 +00002003 def summarize(self, verbose=None):
2004 return self.testrunner.summarize(verbose)
Tim Petersdb3756d2003-06-29 05:30:48 +00002005
Tim Peters8485b562004-08-04 18:46:34 +00002006 def merge(self, other):
2007 d = self.testrunner._name2ft
2008 for name, (f, t) in other.testrunner._name2ft.items():
2009 if name in d:
2010 print "*** Tester.merge: '" + name + "' in both" \
2011 " testers; summing outcomes."
2012 f2, t2 = d[name]
2013 f = f + f2
2014 t = t + t2
2015 d[name] = f, t
Tim Petersdb3756d2003-06-29 05:30:48 +00002016
Tim Peters8485b562004-08-04 18:46:34 +00002017######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00002018## 8. Unittest Support
Tim Peters8485b562004-08-04 18:46:34 +00002019######################################################################
Tim Petersdb3756d2003-06-29 05:30:48 +00002020
Tim Peters19397e52004-08-06 22:02:59 +00002021class DocTestCase(unittest.TestCase):
Tim Petersdb3756d2003-06-29 05:30:48 +00002022
Edward Loper34fcb142004-08-09 02:45:41 +00002023 def __init__(self, test, optionflags=0, setUp=None, tearDown=None,
2024 checker=None):
Jim Fulton07a349c2004-08-22 14:10:00 +00002025
Jim Fultona643b652004-07-14 19:06:50 +00002026 unittest.TestCase.__init__(self)
Tim Peters19397e52004-08-06 22:02:59 +00002027 self._dt_optionflags = optionflags
Edward Loper34fcb142004-08-09 02:45:41 +00002028 self._dt_checker = checker
Tim Peters19397e52004-08-06 22:02:59 +00002029 self._dt_test = test
2030 self._dt_setUp = setUp
2031 self._dt_tearDown = tearDown
Tim Petersdb3756d2003-06-29 05:30:48 +00002032
Jim Fultona643b652004-07-14 19:06:50 +00002033 def setUp(self):
Tim Peters19397e52004-08-06 22:02:59 +00002034 if self._dt_setUp is not None:
2035 self._dt_setUp()
Jim Fultona643b652004-07-14 19:06:50 +00002036
2037 def tearDown(self):
Tim Peters19397e52004-08-06 22:02:59 +00002038 if self._dt_tearDown is not None:
2039 self._dt_tearDown()
Jim Fultona643b652004-07-14 19:06:50 +00002040
2041 def runTest(self):
Tim Peters19397e52004-08-06 22:02:59 +00002042 test = self._dt_test
Jim Fultona643b652004-07-14 19:06:50 +00002043 old = sys.stdout
2044 new = StringIO()
Edward Loper34fcb142004-08-09 02:45:41 +00002045 runner = DocTestRunner(optionflags=self._dt_optionflags,
2046 checker=self._dt_checker, verbose=False)
Tim Peters19397e52004-08-06 22:02:59 +00002047
Jim Fultona643b652004-07-14 19:06:50 +00002048 try:
Tim Peters19397e52004-08-06 22:02:59 +00002049 runner.DIVIDER = "-"*70
2050 failures, tries = runner.run(test, out=new.write)
Jim Fultona643b652004-07-14 19:06:50 +00002051 finally:
2052 sys.stdout = old
2053
2054 if failures:
Tim Peters19397e52004-08-06 22:02:59 +00002055 raise self.failureException(self.format_failure(new.getvalue()))
Tim Peters8485b562004-08-04 18:46:34 +00002056
Tim Peters19397e52004-08-06 22:02:59 +00002057 def format_failure(self, err):
2058 test = self._dt_test
2059 if test.lineno is None:
2060 lineno = 'unknown line number'
2061 else:
Jim Fulton07a349c2004-08-22 14:10:00 +00002062 lineno = '%s' % test.lineno
Tim Peters19397e52004-08-06 22:02:59 +00002063 lname = '.'.join(test.name.split('.')[-1:])
2064 return ('Failed doctest test for %s\n'
2065 ' File "%s", line %s, in %s\n\n%s'
2066 % (test.name, test.filename, lineno, lname, err)
2067 )
2068
2069 def debug(self):
2070 r"""Run the test case without results and without catching exceptions
2071
2072 The unit test framework includes a debug method on test cases
2073 and test suites to support post-mortem debugging. The test code
2074 is run in such a way that errors are not caught. This way a
2075 caller can catch the errors and initiate post-mortem debugging.
2076
2077 The DocTestCase provides a debug method that raises
2078 UnexpectedException errors if there is an unexepcted
2079 exception:
2080
Edward Lopera1ef6112004-08-09 16:14:41 +00002081 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
Tim Peters19397e52004-08-06 22:02:59 +00002082 ... {}, 'foo', 'foo.py', 0)
2083 >>> case = DocTestCase(test)
2084 >>> try:
2085 ... case.debug()
2086 ... except UnexpectedException, failure:
2087 ... pass
2088
2089 The UnexpectedException contains the test, the example, and
2090 the original exception:
2091
2092 >>> failure.test is test
2093 True
2094
2095 >>> failure.example.want
2096 '42\n'
2097
2098 >>> exc_info = failure.exc_info
2099 >>> raise exc_info[0], exc_info[1], exc_info[2]
2100 Traceback (most recent call last):
2101 ...
2102 KeyError
2103
2104 If the output doesn't match, then a DocTestFailure is raised:
2105
Edward Lopera1ef6112004-08-09 16:14:41 +00002106 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00002107 ... >>> x = 1
2108 ... >>> x
2109 ... 2
2110 ... ''', {}, 'foo', 'foo.py', 0)
2111 >>> case = DocTestCase(test)
2112
2113 >>> try:
2114 ... case.debug()
2115 ... except DocTestFailure, failure:
2116 ... pass
2117
2118 DocTestFailure objects provide access to the test:
2119
2120 >>> failure.test is test
2121 True
2122
2123 As well as to the example:
2124
2125 >>> failure.example.want
2126 '2\n'
2127
2128 and the actual output:
2129
2130 >>> failure.got
2131 '1\n'
2132
2133 """
2134
Edward Loper34fcb142004-08-09 02:45:41 +00002135 runner = DebugRunner(optionflags=self._dt_optionflags,
2136 checker=self._dt_checker, verbose=False)
Edward Loper3a3817f2004-08-19 19:26:06 +00002137 runner.run(self._dt_test)
Jim Fultona643b652004-07-14 19:06:50 +00002138
2139 def id(self):
Tim Peters19397e52004-08-06 22:02:59 +00002140 return self._dt_test.name
Jim Fultona643b652004-07-14 19:06:50 +00002141
2142 def __repr__(self):
Tim Peters19397e52004-08-06 22:02:59 +00002143 name = self._dt_test.name.split('.')
Jim Fultona643b652004-07-14 19:06:50 +00002144 return "%s (%s)" % (name[-1], '.'.join(name[:-1]))
2145
2146 __str__ = __repr__
2147
2148 def shortDescription(self):
Tim Peters19397e52004-08-06 22:02:59 +00002149 return "Doctest: " + self._dt_test.name
Jim Fultona643b652004-07-14 19:06:50 +00002150
Tim Peters19397e52004-08-06 22:02:59 +00002151def DocTestSuite(module=None, globs=None, extraglobs=None,
2152 optionflags=0, test_finder=None,
Edward Loper34fcb142004-08-09 02:45:41 +00002153 setUp=lambda: None, tearDown=lambda: None,
2154 checker=None):
Tim Peters8485b562004-08-04 18:46:34 +00002155 """
Tim Peters75dc5e12004-08-22 17:50:45 +00002156 Convert doctest tests for a module to a unittest test suite.
Jim Fultona643b652004-07-14 19:06:50 +00002157
Tim Peters19397e52004-08-06 22:02:59 +00002158 This converts each documentation string in a module that
2159 contains doctest tests to a unittest test case. If any of the
2160 tests in a doc string fail, then the test case fails. An exception
2161 is raised showing the name of the file containing the test and a
Jim Fultona643b652004-07-14 19:06:50 +00002162 (sometimes approximate) line number.
2163
Tim Peters19397e52004-08-06 22:02:59 +00002164 The `module` argument provides the module to be tested. The argument
Jim Fultona643b652004-07-14 19:06:50 +00002165 can be either a module or a module name.
2166
2167 If no argument is given, the calling module is used.
Jim Fultona643b652004-07-14 19:06:50 +00002168 """
Jim Fultona643b652004-07-14 19:06:50 +00002169
Tim Peters8485b562004-08-04 18:46:34 +00002170 if test_finder is None:
2171 test_finder = DocTestFinder()
Tim Peters8485b562004-08-04 18:46:34 +00002172
Tim Peters19397e52004-08-06 22:02:59 +00002173 module = _normalize_module(module)
2174 tests = test_finder.find(module, globs=globs, extraglobs=extraglobs)
2175 if globs is None:
2176 globs = module.__dict__
2177 if not tests: # [XX] why do we want to do this?
2178 raise ValueError(module, "has no tests")
Tim Petersdb3756d2003-06-29 05:30:48 +00002179
2180 tests.sort()
2181 suite = unittest.TestSuite()
Tim Peters8485b562004-08-04 18:46:34 +00002182 for test in tests:
Tim Peters19397e52004-08-06 22:02:59 +00002183 if len(test.examples) == 0:
2184 continue
Tim Peters8485b562004-08-04 18:46:34 +00002185 if not test.filename:
Tim Petersdb3756d2003-06-29 05:30:48 +00002186 filename = module.__file__
Jim Fulton07a349c2004-08-22 14:10:00 +00002187 if filename[-4:] in (".pyc", ".pyo"):
Tim Petersdb3756d2003-06-29 05:30:48 +00002188 filename = filename[:-1]
Tim Peters8485b562004-08-04 18:46:34 +00002189 test.filename = filename
Edward Loper34fcb142004-08-09 02:45:41 +00002190 suite.addTest(DocTestCase(test, optionflags, setUp, tearDown,
2191 checker))
Tim Peters19397e52004-08-06 22:02:59 +00002192
2193 return suite
2194
2195class DocFileCase(DocTestCase):
2196
2197 def id(self):
2198 return '_'.join(self._dt_test.name.split('.'))
2199
2200 def __repr__(self):
2201 return self._dt_test.filename
2202 __str__ = __repr__
2203
2204 def format_failure(self, err):
2205 return ('Failed doctest test for %s\n File "%s", line 0\n\n%s'
2206 % (self._dt_test.name, self._dt_test.filename, err)
2207 )
2208
2209def DocFileTest(path, package=None, globs=None,
2210 setUp=None, tearDown=None,
2211 optionflags=0):
2212 package = _normalize_module(package)
2213 name = path.split('/')[-1]
2214 dir = os.path.split(package.__file__)[0]
2215 path = os.path.join(dir, *(path.split('/')))
2216 doc = open(path).read()
2217
2218 if globs is None:
2219 globs = {}
2220
Edward Lopera1ef6112004-08-09 16:14:41 +00002221 test = DocTestParser().get_doctest(doc, globs, name, path, 0)
Tim Peters19397e52004-08-06 22:02:59 +00002222
2223 return DocFileCase(test, optionflags, setUp, tearDown)
2224
2225def DocFileSuite(*paths, **kw):
2226 """Creates a suite of doctest files.
2227
2228 One or more text file paths are given as strings. These should
2229 use "/" characters to separate path segments. Paths are relative
2230 to the directory of the calling module, or relative to the package
2231 passed as a keyword argument.
2232
2233 A number of options may be provided as keyword arguments:
2234
2235 package
2236 The name of a Python package. Text-file paths will be
2237 interpreted relative to the directory containing this package.
2238 The package may be supplied as a package object or as a dotted
2239 package name.
2240
2241 setUp
2242 The name of a set-up function. This is called before running the
2243 tests in each file.
2244
2245 tearDown
2246 The name of a tear-down function. This is called after running the
2247 tests in each file.
2248
2249 globs
2250 A dictionary containing initial global variables for the tests.
2251 """
2252 suite = unittest.TestSuite()
2253
2254 # We do this here so that _normalize_module is called at the right
2255 # level. If it were called in DocFileTest, then this function
2256 # would be the caller and we might guess the package incorrectly.
2257 kw['package'] = _normalize_module(kw.get('package'))
2258
2259 for path in paths:
2260 suite.addTest(DocFileTest(path, **kw))
Jim Fultona643b652004-07-14 19:06:50 +00002261
Tim Petersdb3756d2003-06-29 05:30:48 +00002262 return suite
2263
Tim Peters8485b562004-08-04 18:46:34 +00002264######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00002265## 9. Debugging Support
Tim Peters8485b562004-08-04 18:46:34 +00002266######################################################################
Jim Fultona643b652004-07-14 19:06:50 +00002267
Tim Peters19397e52004-08-06 22:02:59 +00002268def script_from_examples(s):
2269 r"""Extract script from text with examples.
2270
2271 Converts text with examples to a Python script. Example input is
2272 converted to regular code. Example output and all other words
2273 are converted to comments:
2274
2275 >>> text = '''
2276 ... Here are examples of simple math.
2277 ...
2278 ... Python has super accurate integer addition
2279 ...
2280 ... >>> 2 + 2
2281 ... 5
2282 ...
2283 ... And very friendly error messages:
2284 ...
2285 ... >>> 1/0
2286 ... To Infinity
2287 ... And
2288 ... Beyond
2289 ...
2290 ... You can use logic if you want:
2291 ...
2292 ... >>> if 0:
2293 ... ... blah
2294 ... ... blah
2295 ... ...
2296 ...
2297 ... Ho hum
2298 ... '''
2299
2300 >>> print script_from_examples(text)
Edward Lopera5db6002004-08-12 02:41:30 +00002301 # Here are examples of simple math.
Tim Peters19397e52004-08-06 22:02:59 +00002302 #
Edward Lopera5db6002004-08-12 02:41:30 +00002303 # Python has super accurate integer addition
Tim Peters19397e52004-08-06 22:02:59 +00002304 #
2305 2 + 2
2306 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +00002307 ## 5
Tim Peters19397e52004-08-06 22:02:59 +00002308 #
Edward Lopera5db6002004-08-12 02:41:30 +00002309 # And very friendly error messages:
Tim Peters19397e52004-08-06 22:02:59 +00002310 #
2311 1/0
2312 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +00002313 ## To Infinity
2314 ## And
2315 ## Beyond
Tim Peters19397e52004-08-06 22:02:59 +00002316 #
Edward Lopera5db6002004-08-12 02:41:30 +00002317 # You can use logic if you want:
Tim Peters19397e52004-08-06 22:02:59 +00002318 #
2319 if 0:
2320 blah
2321 blah
2322 <BLANKLINE>
2323 #
Edward Lopera5db6002004-08-12 02:41:30 +00002324 # Ho hum
Tim Peters19397e52004-08-06 22:02:59 +00002325 """
2326
Edward Lopera1ef6112004-08-09 16:14:41 +00002327 return DocTestParser().get_program(s)
Tim Peters19397e52004-08-06 22:02:59 +00002328
Tim Peters8485b562004-08-04 18:46:34 +00002329def _want_comment(example):
2330 """
Tim Peters19397e52004-08-06 22:02:59 +00002331 Return a comment containing the expected output for the given example.
Tim Peters8485b562004-08-04 18:46:34 +00002332 """
Jim Fultona643b652004-07-14 19:06:50 +00002333 # Return the expected output, if any
Tim Peters8485b562004-08-04 18:46:34 +00002334 want = example.want
2335 if want:
Tim Peters19397e52004-08-06 22:02:59 +00002336 if want[-1] == '\n':
2337 want = want[:-1]
Tim Peters8485b562004-08-04 18:46:34 +00002338 want = "\n# ".join(want.split("\n"))
2339 want = "\n# Expected:\n# %s" % want
2340 return want
Tim Petersdb3756d2003-06-29 05:30:48 +00002341
2342def testsource(module, name):
Tim Peters19397e52004-08-06 22:02:59 +00002343 """Extract the test sources from a doctest docstring as a script.
Tim Petersdb3756d2003-06-29 05:30:48 +00002344
2345 Provide the module (or dotted name of the module) containing the
Jim Fultona643b652004-07-14 19:06:50 +00002346 test to be debugged and the name (within the module) of the object
2347 with the doc string with tests to be debugged.
Tim Petersdb3756d2003-06-29 05:30:48 +00002348 """
Tim Peters8485b562004-08-04 18:46:34 +00002349 module = _normalize_module(module)
2350 tests = DocTestFinder().find(module)
2351 test = [t for t in tests if t.name == name]
Tim Petersdb3756d2003-06-29 05:30:48 +00002352 if not test:
2353 raise ValueError(name, "not found in tests")
2354 test = test[0]
Tim Peters19397e52004-08-06 22:02:59 +00002355 testsrc = script_from_examples(test.docstring)
Jim Fultona643b652004-07-14 19:06:50 +00002356 return testsrc
Tim Petersdb3756d2003-06-29 05:30:48 +00002357
Jim Fultona643b652004-07-14 19:06:50 +00002358def debug_src(src, pm=False, globs=None):
Tim Peters19397e52004-08-06 22:02:59 +00002359 """Debug a single doctest docstring, in argument `src`'"""
2360 testsrc = script_from_examples(src)
Tim Peters8485b562004-08-04 18:46:34 +00002361 debug_script(testsrc, pm, globs)
Tim Petersdb3756d2003-06-29 05:30:48 +00002362
Jim Fultona643b652004-07-14 19:06:50 +00002363def debug_script(src, pm=False, globs=None):
Tim Peters19397e52004-08-06 22:02:59 +00002364 "Debug a test script. `src` is the script, as a string."
Tim Petersdb3756d2003-06-29 05:30:48 +00002365 import pdb
Tim Petersdb3756d2003-06-29 05:30:48 +00002366
Tim Petersb6a04d62004-08-23 21:37:56 +00002367 # Note that tempfile.NameTemporaryFile() cannot be used. As the
2368 # docs say, a file so created cannot be opened by name a second time
2369 # on modern Windows boxes, and execfile() needs to open it.
2370 srcfilename = tempfile.mktemp(".py", "doctestdebug")
Tim Peters8485b562004-08-04 18:46:34 +00002371 f = open(srcfilename, 'w')
2372 f.write(src)
2373 f.close()
2374
Tim Petersb6a04d62004-08-23 21:37:56 +00002375 try:
2376 if globs:
2377 globs = globs.copy()
2378 else:
2379 globs = {}
Tim Petersdb3756d2003-06-29 05:30:48 +00002380
Tim Petersb6a04d62004-08-23 21:37:56 +00002381 if pm:
2382 try:
2383 execfile(srcfilename, globs, globs)
2384 except:
2385 print sys.exc_info()[1]
2386 pdb.post_mortem(sys.exc_info()[2])
2387 else:
2388 # Note that %r is vital here. '%s' instead can, e.g., cause
2389 # backslashes to get treated as metacharacters on Windows.
2390 pdb.run("execfile(%r)" % srcfilename, globs, globs)
2391
2392 finally:
2393 os.remove(srcfilename)
Tim Petersdb3756d2003-06-29 05:30:48 +00002394
Jim Fultona643b652004-07-14 19:06:50 +00002395def debug(module, name, pm=False):
Tim Peters19397e52004-08-06 22:02:59 +00002396 """Debug a single doctest docstring.
Jim Fultona643b652004-07-14 19:06:50 +00002397
2398 Provide the module (or dotted name of the module) containing the
2399 test to be debugged and the name (within the module) of the object
Tim Peters19397e52004-08-06 22:02:59 +00002400 with the docstring with tests to be debugged.
Jim Fultona643b652004-07-14 19:06:50 +00002401 """
Tim Peters8485b562004-08-04 18:46:34 +00002402 module = _normalize_module(module)
Jim Fultona643b652004-07-14 19:06:50 +00002403 testsrc = testsource(module, name)
2404 debug_script(testsrc, pm, module.__dict__)
2405
Tim Peters8485b562004-08-04 18:46:34 +00002406######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00002407## 10. Example Usage
Tim Peters8485b562004-08-04 18:46:34 +00002408######################################################################
Tim Peters8a7d2d52001-01-16 07:10:57 +00002409class _TestClass:
2410 """
2411 A pointless class, for sanity-checking of docstring testing.
2412
2413 Methods:
2414 square()
2415 get()
2416
2417 >>> _TestClass(13).get() + _TestClass(-12).get()
2418 1
2419 >>> hex(_TestClass(13).square().get())
2420 '0xa9'
2421 """
2422
2423 def __init__(self, val):
2424 """val -> _TestClass object with associated value val.
2425
2426 >>> t = _TestClass(123)
2427 >>> print t.get()
2428 123
2429 """
2430
2431 self.val = val
2432
2433 def square(self):
2434 """square() -> square TestClass's associated value
2435
2436 >>> _TestClass(13).square().get()
2437 169
2438 """
2439
2440 self.val = self.val ** 2
2441 return self
2442
2443 def get(self):
2444 """get() -> return TestClass's associated value.
2445
2446 >>> x = _TestClass(-42)
2447 >>> print x.get()
2448 -42
2449 """
2450
2451 return self.val
2452
2453__test__ = {"_TestClass": _TestClass,
2454 "string": r"""
2455 Example of a string object, searched as-is.
2456 >>> x = 1; y = 2
2457 >>> x + y, x * y
2458 (3, 2)
Tim Peters6ebe61f2003-06-27 20:48:05 +00002459 """,
Tim Peters3fa8c202004-08-23 21:43:39 +00002460
Tim Peters6ebe61f2003-06-27 20:48:05 +00002461 "bool-int equivalence": r"""
2462 In 2.2, boolean expressions displayed
2463 0 or 1. By default, we still accept
2464 them. This can be disabled by passing
2465 DONT_ACCEPT_TRUE_FOR_1 to the new
2466 optionflags argument.
2467 >>> 4 == 4
2468 1
2469 >>> 4 == 4
2470 True
2471 >>> 4 > 4
2472 0
2473 >>> 4 > 4
2474 False
2475 """,
Tim Peters3fa8c202004-08-23 21:43:39 +00002476
Tim Peters8485b562004-08-04 18:46:34 +00002477 "blank lines": r"""
Tim Peters3fa8c202004-08-23 21:43:39 +00002478 Blank lines can be marked with <BLANKLINE>:
2479 >>> print 'foo\n\nbar\n'
2480 foo
2481 <BLANKLINE>
2482 bar
2483 <BLANKLINE>
Tim Peters8485b562004-08-04 18:46:34 +00002484 """,
Tim Peters3fa8c202004-08-23 21:43:39 +00002485
2486 "ellipsis": r"""
2487 If the ellipsis flag is used, then '...' can be used to
2488 elide substrings in the desired output:
2489 >>> print range(1000) #doctest: +ELLIPSIS
2490 [0, 1, 2, ..., 999]
2491 """,
2492
2493 "whitespace normalization": r"""
2494 If the whitespace normalization flag is used, then
2495 differences in whitespace are ignored.
2496 >>> print range(30) #doctest: +NORMALIZE_WHITESPACE
2497 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
2498 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,
2499 27, 28, 29]
2500 """,
2501 }
Tim Peters8485b562004-08-04 18:46:34 +00002502
Tim Peters8a7d2d52001-01-16 07:10:57 +00002503def _test():
Tim Peters8485b562004-08-04 18:46:34 +00002504 r = unittest.TextTestRunner()
2505 r.run(DocTestSuite())
Tim Peters8a7d2d52001-01-16 07:10:57 +00002506
2507if __name__ == "__main__":
2508 _test()