blob: fca2f98b8d71e9b216d8cec31866f2ee5909d4ac [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',
179 'UNIFIED_DIFF',
180 'CONTEXT_DIFF',
181 # 1. Utility Functions
Tim Peters8485b562004-08-04 18:46:34 +0000182 'is_private',
Edward Loperb7503ff2004-08-19 19:19:03 +0000183 # 2. Example & DocTest
Tim Peters8485b562004-08-04 18:46:34 +0000184 'Example',
185 'DocTest',
Edward Loperb7503ff2004-08-19 19:19:03 +0000186 # 3. Doctest Parser
187 'DocTestParser',
188 # 4. Doctest Finder
Tim Peters8485b562004-08-04 18:46:34 +0000189 'DocTestFinder',
Edward Loperb7503ff2004-08-19 19:19:03 +0000190 # 5. Doctest Runner
Tim Peters8485b562004-08-04 18:46:34 +0000191 'DocTestRunner',
Edward Loperb7503ff2004-08-19 19:19:03 +0000192 'OutputChecker',
193 'DocTestFailure',
194 'UnexpectedException',
195 'DebugRunner',
196 # 6. Test Functions
Tim Peters4fd9e2f2001-08-18 00:05:50 +0000197 'testmod',
198 'run_docstring_examples',
Edward Loperb7503ff2004-08-19 19:19:03 +0000199 # 7. Tester
Tim Peters4fd9e2f2001-08-18 00:05:50 +0000200 'Tester',
Edward Loperb7503ff2004-08-19 19:19:03 +0000201 # 8. Unittest Support
Tim Peters19397e52004-08-06 22:02:59 +0000202 'DocTestCase',
Tim Petersdb3756d2003-06-29 05:30:48 +0000203 'DocTestSuite',
Edward Loperb7503ff2004-08-19 19:19:03 +0000204 'DocFileCase',
205 'DocFileTest',
206 'DocFileSuite',
207 # 9. Debugging Support
208 'script_from_examples',
Tim Petersdb3756d2003-06-29 05:30:48 +0000209 'testsource',
Edward Loperb7503ff2004-08-19 19:19:03 +0000210 'debug_src',
211 'debug_script',
Tim Petersdb3756d2003-06-29 05:30:48 +0000212 'debug',
Tim Peters4fd9e2f2001-08-18 00:05:50 +0000213]
Tim Peters8a7d2d52001-01-16 07:10:57 +0000214
Tim Peters4fd9e2f2001-08-18 00:05:50 +0000215import __future__
Tim Peters8a7d2d52001-01-16 07:10:57 +0000216
Tim Peters19397e52004-08-06 22:02:59 +0000217import sys, traceback, inspect, linecache, os, re, types
Jim Fulton356fd192004-08-09 11:34:47 +0000218import unittest, difflib, pdb, tempfile
Tim Petersf727c6c2004-08-08 01:48:59 +0000219import warnings
Tim Peters8485b562004-08-04 18:46:34 +0000220from StringIO import StringIO
Tim Peters7402f792001-10-02 03:53:41 +0000221
Jim Fulton356fd192004-08-09 11:34:47 +0000222real_pdb_set_trace = pdb.set_trace
223
Tim Peters19397e52004-08-06 22:02:59 +0000224# There are 4 basic classes:
225# - Example: a <source, want> pair, plus an intra-docstring line number.
226# - DocTest: a collection of examples, parsed from a docstring, plus
227# info about where the docstring came from (name, filename, lineno).
228# - DocTestFinder: extracts DocTests from a given object's docstring and
229# its contained objects' docstrings.
230# - DocTestRunner: runs DocTest cases, and accumulates statistics.
231#
232# So the basic picture is:
233#
234# list of:
235# +------+ +---------+ +-------+
236# |object| --DocTestFinder-> | DocTest | --DocTestRunner-> |results|
237# +------+ +---------+ +-------+
238# | Example |
239# | ... |
240# | Example |
241# +---------+
242
Edward Loperac20f572004-08-12 02:02:24 +0000243# Option constants.
244OPTIONFLAGS_BY_NAME = {}
245def register_optionflag(name):
246 flag = 1 << len(OPTIONFLAGS_BY_NAME)
247 OPTIONFLAGS_BY_NAME[name] = flag
248 return flag
249
250DONT_ACCEPT_TRUE_FOR_1 = register_optionflag('DONT_ACCEPT_TRUE_FOR_1')
251DONT_ACCEPT_BLANKLINE = register_optionflag('DONT_ACCEPT_BLANKLINE')
252NORMALIZE_WHITESPACE = register_optionflag('NORMALIZE_WHITESPACE')
253ELLIPSIS = register_optionflag('ELLIPSIS')
254UNIFIED_DIFF = register_optionflag('UNIFIED_DIFF')
255CONTEXT_DIFF = register_optionflag('CONTEXT_DIFF')
256
257# Special string markers for use in `want` strings:
258BLANKLINE_MARKER = '<BLANKLINE>'
259ELLIPSIS_MARKER = '...'
260
Tim Peters8485b562004-08-04 18:46:34 +0000261######################################################################
262## Table of Contents
263######################################################################
Edward Loper7c748462004-08-09 02:06:06 +0000264# 1. Utility Functions
265# 2. Example & DocTest -- store test cases
266# 3. DocTest Parser -- extracts examples from strings
267# 4. DocTest Finder -- extracts test cases from objects
268# 5. DocTest Runner -- runs test cases
269# 6. Test Functions -- convenient wrappers for testing
270# 7. Tester Class -- for backwards compatibility
271# 8. Unittest Support
272# 9. Debugging Support
273# 10. Example Usage
Tim Peters8a7d2d52001-01-16 07:10:57 +0000274
Tim Peters8485b562004-08-04 18:46:34 +0000275######################################################################
276## 1. Utility Functions
277######################################################################
Tim Peters8a7d2d52001-01-16 07:10:57 +0000278
279def is_private(prefix, base):
280 """prefix, base -> true iff name prefix + "." + base is "private".
281
282 Prefix may be an empty string, and base does not contain a period.
283 Prefix is ignored (although functions you write conforming to this
284 protocol may make use of it).
285 Return true iff base begins with an (at least one) underscore, but
286 does not both begin and end with (at least) two underscores.
287
Tim Petersbafb1fe2004-08-08 01:52:57 +0000288 >>> warnings.filterwarnings("ignore", "is_private", DeprecationWarning,
289 ... "doctest", 0)
Tim Peters8a7d2d52001-01-16 07:10:57 +0000290 >>> is_private("a.b", "my_func")
Guido van Rossum77f6a652002-04-03 22:41:51 +0000291 False
Tim Peters8a7d2d52001-01-16 07:10:57 +0000292 >>> is_private("____", "_my_func")
Guido van Rossum77f6a652002-04-03 22:41:51 +0000293 True
Tim Peters8a7d2d52001-01-16 07:10:57 +0000294 >>> is_private("someclass", "__init__")
Guido van Rossum77f6a652002-04-03 22:41:51 +0000295 False
Tim Peters8a7d2d52001-01-16 07:10:57 +0000296 >>> is_private("sometypo", "__init_")
Guido van Rossum77f6a652002-04-03 22:41:51 +0000297 True
Tim Peters8a7d2d52001-01-16 07:10:57 +0000298 >>> is_private("x.y.z", "_")
Guido van Rossum77f6a652002-04-03 22:41:51 +0000299 True
Tim Peters8a7d2d52001-01-16 07:10:57 +0000300 >>> is_private("_x.y.z", "__")
Guido van Rossum77f6a652002-04-03 22:41:51 +0000301 False
Tim Peters8a7d2d52001-01-16 07:10:57 +0000302 >>> is_private("", "") # senseless but consistent
Guido van Rossum77f6a652002-04-03 22:41:51 +0000303 False
Tim Peters8a7d2d52001-01-16 07:10:57 +0000304 """
Tim Petersbafb1fe2004-08-08 01:52:57 +0000305 warnings.warn("is_private is deprecated; it wasn't useful; "
306 "examine DocTestFinder.find() lists instead",
Tim Peters3ddd60a2004-08-08 02:43:33 +0000307 DeprecationWarning, stacklevel=2)
Tim Peters8a7d2d52001-01-16 07:10:57 +0000308 return base[:1] == "_" and not base[:2] == "__" == base[-2:]
309
Tim Peters8485b562004-08-04 18:46:34 +0000310def _extract_future_flags(globs):
311 """
312 Return the compiler-flags associated with the future features that
313 have been imported into the given namespace (globs).
314 """
315 flags = 0
316 for fname in __future__.all_feature_names:
317 feature = globs.get(fname, None)
318 if feature is getattr(__future__, fname):
319 flags |= feature.compiler_flag
320 return flags
Tim Peters7402f792001-10-02 03:53:41 +0000321
Tim Peters8485b562004-08-04 18:46:34 +0000322def _normalize_module(module, depth=2):
323 """
324 Return the module specified by `module`. In particular:
325 - If `module` is a module, then return module.
326 - If `module` is a string, then import and return the
327 module with that name.
328 - If `module` is None, then return the calling module.
329 The calling module is assumed to be the module of
330 the stack frame at the given depth in the call stack.
331 """
332 if inspect.ismodule(module):
333 return module
334 elif isinstance(module, (str, unicode)):
335 return __import__(module, globals(), locals(), ["*"])
336 elif module is None:
337 return sys.modules[sys._getframe(depth).f_globals['__name__']]
338 else:
339 raise TypeError("Expected a module, string, or None")
Tim Peters7402f792001-10-02 03:53:41 +0000340
Edward Lopera1ef6112004-08-09 16:14:41 +0000341def _tag_msg(tag, msg, indent=' '):
Tim Peters8485b562004-08-04 18:46:34 +0000342 """
343 Return a string that displays a tag-and-message pair nicely,
344 keeping the tag and its message on the same line when that
Edward Lopera1ef6112004-08-09 16:14:41 +0000345 makes sense. If the message is displayed on separate lines,
346 then `indent` is added to the beginning of each line.
Tim Peters8485b562004-08-04 18:46:34 +0000347 """
Tim Peters8485b562004-08-04 18:46:34 +0000348 # If the message doesn't end in a newline, then add one.
349 if msg[-1:] != '\n':
350 msg += '\n'
351 # If the message is short enough, and contains no internal
352 # newlines, then display it on the same line as the tag.
353 # Otherwise, display the tag on its own line.
354 if (len(tag) + len(msg) < 75 and
355 msg.find('\n', 0, len(msg)-1) == -1):
356 return '%s: %s' % (tag, msg)
357 else:
Edward Lopera1ef6112004-08-09 16:14:41 +0000358 msg = '\n'.join([indent+l for l in msg[:-1].split('\n')])
359 return '%s:\n%s\n' % (tag, msg)
Tim Peters8a7d2d52001-01-16 07:10:57 +0000360
Edward Loper8e4a34b2004-08-12 02:34:27 +0000361def _exception_traceback(exc_info):
362 """
363 Return a string containing a traceback message for the given
364 exc_info tuple (as returned by sys.exc_info()).
365 """
366 # Get a traceback message.
367 excout = StringIO()
368 exc_type, exc_val, exc_tb = exc_info
369 traceback.print_exception(exc_type, exc_val, exc_tb, file=excout)
370 return excout.getvalue()
371
Tim Peters8485b562004-08-04 18:46:34 +0000372# Override some StringIO methods.
373class _SpoofOut(StringIO):
374 def getvalue(self):
375 result = StringIO.getvalue(self)
376 # If anything at all was written, make sure there's a trailing
377 # newline. There's no way for the expected output to indicate
378 # that a trailing newline is missing.
379 if result and not result.endswith("\n"):
380 result += "\n"
381 # Prevent softspace from screwing up the next test case, in
382 # case they used print with a trailing comma in an example.
383 if hasattr(self, "softspace"):
384 del self.softspace
385 return result
Tim Peters8a7d2d52001-01-16 07:10:57 +0000386
Tim Peters8485b562004-08-04 18:46:34 +0000387 def truncate(self, size=None):
388 StringIO.truncate(self, size)
389 if hasattr(self, "softspace"):
390 del self.softspace
Tim Peters8a7d2d52001-01-16 07:10:57 +0000391
Tim Peters26b3ebb2004-08-19 08:10:08 +0000392# Worst-case linear-time ellipsis matching.
Tim Petersb0a04e12004-08-20 02:08:04 +0000393def _ellipsis_match(want, got):
Tim Petersdc5de3b2004-08-19 14:06:20 +0000394 """
395 Essentially the only subtle case:
Tim Petersb0a04e12004-08-20 02:08:04 +0000396 >>> _ellipsis_match('aa...aa', 'aaa')
Tim Petersdc5de3b2004-08-19 14:06:20 +0000397 False
398 """
Tim Peters26b3ebb2004-08-19 08:10:08 +0000399 if ELLIPSIS_MARKER not in want:
400 return want == got
Tim Petersdc5de3b2004-08-19 14:06:20 +0000401
Tim Peters26b3ebb2004-08-19 08:10:08 +0000402 # Find "the real" strings.
403 ws = want.split(ELLIPSIS_MARKER)
404 assert len(ws) >= 2
Tim Peters26b3ebb2004-08-19 08:10:08 +0000405
Tim Petersdc5de3b2004-08-19 14:06:20 +0000406 # Deal with exact matches possibly needed at one or both ends.
407 startpos, endpos = 0, len(got)
408 w = ws[0]
409 if w: # starts with exact match
410 if got.startswith(w):
411 startpos = len(w)
412 del ws[0]
413 else:
414 return False
415 w = ws[-1]
416 if w: # ends with exact match
417 if got.endswith(w):
418 endpos -= len(w)
419 del ws[-1]
420 else:
421 return False
422
423 if startpos > endpos:
424 # Exact end matches required more characters than we have, as in
Tim Petersb0a04e12004-08-20 02:08:04 +0000425 # _ellipsis_match('aa...aa', 'aaa')
Tim Petersdc5de3b2004-08-19 14:06:20 +0000426 return False
427
428 # For the rest, we only need to find the leftmost non-overlapping
429 # match for each piece. If there's no overall match that way alone,
430 # there's no overall match period.
Tim Peters26b3ebb2004-08-19 08:10:08 +0000431 for w in ws:
432 # w may be '' at times, if there are consecutive ellipses, or
433 # due to an ellipsis at the start or end of `want`. That's OK.
Tim Petersdc5de3b2004-08-19 14:06:20 +0000434 # Search for an empty string succeeds, and doesn't change startpos.
435 startpos = got.find(w, startpos, endpos)
436 if startpos < 0:
Tim Peters26b3ebb2004-08-19 08:10:08 +0000437 return False
Tim Petersdc5de3b2004-08-19 14:06:20 +0000438 startpos += len(w)
Tim Peters26b3ebb2004-08-19 08:10:08 +0000439
Tim Petersdc5de3b2004-08-19 14:06:20 +0000440 return True
Tim Peters26b3ebb2004-08-19 08:10:08 +0000441
Tim Peters8485b562004-08-04 18:46:34 +0000442######################################################################
443## 2. Example & DocTest
444######################################################################
445## - An "example" is a <source, want> pair, where "source" is a
446## fragment of source code, and "want" is the expected output for
447## "source." The Example class also includes information about
448## where the example was extracted from.
449##
Edward Lopera1ef6112004-08-09 16:14:41 +0000450## - A "doctest" is a collection of examples, typically extracted from
451## a string (such as an object's docstring). The DocTest class also
452## includes information about where the string was extracted from.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000453
Tim Peters8485b562004-08-04 18:46:34 +0000454class Example:
455 """
456 A single doctest example, consisting of source code and expected
Edward Lopera1ef6112004-08-09 16:14:41 +0000457 output. `Example` defines the following attributes:
Tim Peters8a7d2d52001-01-16 07:10:57 +0000458
Edward Loper74bca7a2004-08-12 02:27:44 +0000459 - source: A single Python statement, always ending with a newline.
Tim Petersbb431472004-08-09 03:51:46 +0000460 The constructor adds a newline if needed.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000461
Edward Loper74bca7a2004-08-12 02:27:44 +0000462 - want: The expected output from running the source code (either
Tim Petersbb431472004-08-09 03:51:46 +0000463 from stdout, or a traceback in case of exception). `want` ends
464 with a newline unless it's empty, in which case it's an empty
465 string. The constructor adds a newline if needed.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000466
Edward Loper74bca7a2004-08-12 02:27:44 +0000467 - lineno: The line number within the DocTest string containing
Tim Peters8485b562004-08-04 18:46:34 +0000468 this Example where the Example begins. This line number is
469 zero-based, with respect to the beginning of the DocTest.
Edward Loper74bca7a2004-08-12 02:27:44 +0000470
471 - indent: The example's indentation in the DocTest string.
472 I.e., the number of space characters that preceed the
473 example's first prompt.
474
475 - options: A dictionary mapping from option flags to True or
476 False, which is used to override default options for this
477 example. Any option flags not contained in this dictionary
478 are left at their default value (as specified by the
479 DocTestRunner's optionflags). By default, no options are set.
Tim Peters8485b562004-08-04 18:46:34 +0000480 """
Edward Loper74bca7a2004-08-12 02:27:44 +0000481 def __init__(self, source, want, lineno, indent=0, options=None):
Tim Petersbb431472004-08-09 03:51:46 +0000482 # Normalize inputs.
483 if not source.endswith('\n'):
484 source += '\n'
485 if want and not want.endswith('\n'):
486 want += '\n'
Tim Peters8485b562004-08-04 18:46:34 +0000487 # Store properties.
488 self.source = source
489 self.want = want
490 self.lineno = lineno
Edward Loper74bca7a2004-08-12 02:27:44 +0000491 self.indent = indent
492 if options is None: options = {}
493 self.options = options
Tim Peters8a7d2d52001-01-16 07:10:57 +0000494
Tim Peters8485b562004-08-04 18:46:34 +0000495class DocTest:
496 """
497 A collection of doctest examples that should be run in a single
Edward Lopera1ef6112004-08-09 16:14:41 +0000498 namespace. Each `DocTest` defines the following attributes:
Tim Peters8a7d2d52001-01-16 07:10:57 +0000499
Tim Peters8485b562004-08-04 18:46:34 +0000500 - examples: the list of examples.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000501
Tim Peters8485b562004-08-04 18:46:34 +0000502 - globs: The namespace (aka globals) that the examples should
503 be run in.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000504
Tim Peters8485b562004-08-04 18:46:34 +0000505 - name: A name identifying the DocTest (typically, the name of
506 the object whose docstring this DocTest was extracted from).
Tim Peters8a7d2d52001-01-16 07:10:57 +0000507
Tim Peters8485b562004-08-04 18:46:34 +0000508 - filename: The name of the file that this DocTest was extracted
Edward Lopera1ef6112004-08-09 16:14:41 +0000509 from, or `None` if the filename is unknown.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000510
Tim Peters8485b562004-08-04 18:46:34 +0000511 - lineno: The line number within filename where this DocTest
Edward Lopera1ef6112004-08-09 16:14:41 +0000512 begins, or `None` if the line number is unavailable. This
513 line number is zero-based, with respect to the beginning of
514 the file.
515
516 - docstring: The string that the examples were extracted from,
517 or `None` if the string is unavailable.
Tim Peters8485b562004-08-04 18:46:34 +0000518 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000519 def __init__(self, examples, globs, name, filename, lineno, docstring):
Tim Peters8485b562004-08-04 18:46:34 +0000520 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000521 Create a new DocTest containing the given examples. The
522 DocTest's globals are initialized with a copy of `globs`.
Tim Peters8485b562004-08-04 18:46:34 +0000523 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000524 assert not isinstance(examples, basestring), \
525 "DocTest no longer accepts str; use DocTestParser instead"
526 self.examples = examples
527 self.docstring = docstring
Tim Peters8485b562004-08-04 18:46:34 +0000528 self.globs = globs.copy()
Tim Peters8485b562004-08-04 18:46:34 +0000529 self.name = name
530 self.filename = filename
531 self.lineno = lineno
Tim Peters8485b562004-08-04 18:46:34 +0000532
533 def __repr__(self):
534 if len(self.examples) == 0:
535 examples = 'no examples'
536 elif len(self.examples) == 1:
537 examples = '1 example'
538 else:
539 examples = '%d examples' % len(self.examples)
540 return ('<DocTest %s from %s:%s (%s)>' %
541 (self.name, self.filename, self.lineno, examples))
542
543
544 # This lets us sort tests by name:
545 def __cmp__(self, other):
546 if not isinstance(other, DocTest):
547 return -1
548 return cmp((self.name, self.filename, self.lineno, id(self)),
549 (other.name, other.filename, other.lineno, id(other)))
550
551######################################################################
Edward Loperb7503ff2004-08-19 19:19:03 +0000552## 3. DocTestParser
Edward Loper7c748462004-08-09 02:06:06 +0000553######################################################################
554
Edward Lopera1ef6112004-08-09 16:14:41 +0000555class DocTestParser:
Edward Loper7c748462004-08-09 02:06:06 +0000556 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000557 A class used to parse strings containing doctest examples.
Edward Loper7c748462004-08-09 02:06:06 +0000558 """
Edward Loper8e4a34b2004-08-12 02:34:27 +0000559 # This regular expression is used to find doctest examples in a
560 # string. It defines three groups: `source` is the source code
561 # (including leading indentation and prompts); `indent` is the
562 # indentation of the first (PS1) line of the source code; and
563 # `want` is the expected output (including leading indentation).
Edward Loper7c748462004-08-09 02:06:06 +0000564 _EXAMPLE_RE = re.compile(r'''
Tim Petersd40a92b2004-08-09 03:28:45 +0000565 # Source consists of a PS1 line followed by zero or more PS2 lines.
566 (?P<source>
567 (?:^(?P<indent> [ ]*) >>> .*) # PS1 line
568 (?:\n [ ]* \.\.\. .*)*) # PS2 lines
569 \n?
570 # Want consists of any non-blank lines that do not start with PS1.
571 (?P<want> (?:(?![ ]*$) # Not a blank line
572 (?![ ]*>>>) # Not a line starting with PS1
573 .*$\n? # But any other line
574 )*)
575 ''', re.MULTILINE | re.VERBOSE)
Edward Loper8e4a34b2004-08-12 02:34:27 +0000576
Tim Peters7ea48dd2004-08-13 01:52:59 +0000577 # A callable returning a true value iff its argument is a blank line
578 # or contains a single comment.
Edward Loper8e4a34b2004-08-12 02:34:27 +0000579 _IS_BLANK_OR_COMMENT = re.compile(r'^[ ]*(#.*)?$').match
Edward Loper7c748462004-08-09 02:06:06 +0000580
Edward Lopera1ef6112004-08-09 16:14:41 +0000581 def get_doctest(self, string, globs, name, filename, lineno):
Edward Loper7c748462004-08-09 02:06:06 +0000582 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000583 Extract all doctest examples from the given string, and
584 collect them into a `DocTest` object.
585
586 `globs`, `name`, `filename`, and `lineno` are attributes for
587 the new `DocTest` object. See the documentation for `DocTest`
588 for more information.
589 """
590 return DocTest(self.get_examples(string, name), globs,
591 name, filename, lineno, string)
592
593 def get_examples(self, string, name='<string>'):
594 """
595 Extract all doctest examples from the given string, and return
596 them as a list of `Example` objects. Line numbers are
597 0-based, because it's most common in doctests that nothing
598 interesting appears on the same line as opening triple-quote,
599 and so the first interesting line is called \"line 1\" then.
600
601 The optional argument `name` is a name identifying this
602 string, and is only used for error messages.
Edward Loper7c748462004-08-09 02:06:06 +0000603
604 >>> text = '''
605 ... >>> x, y = 2, 3 # no output expected
606 ... >>> if 1:
607 ... ... print x
608 ... ... print y
609 ... 2
610 ... 3
611 ...
612 ... Some text.
613 ... >>> x+y
614 ... 5
615 ... '''
Edward Lopera1ef6112004-08-09 16:14:41 +0000616 >>> for x in DocTestParser().get_examples(text):
Edward Loper78b58f32004-08-09 02:56:02 +0000617 ... print (x.source, x.want, x.lineno)
Tim Petersbb431472004-08-09 03:51:46 +0000618 ('x, y = 2, 3 # no output expected\\n', '', 1)
Edward Loper7c748462004-08-09 02:06:06 +0000619 ('if 1:\\n print x\\n print y\\n', '2\\n3\\n', 2)
Tim Petersbb431472004-08-09 03:51:46 +0000620 ('x+y\\n', '5\\n', 9)
Edward Loper7c748462004-08-09 02:06:06 +0000621 """
622 examples = []
623 charno, lineno = 0, 0
624 # Find all doctest examples in the string:
Edward Lopera1ef6112004-08-09 16:14:41 +0000625 for m in self._EXAMPLE_RE.finditer(string.expandtabs()):
Edward Loper7c748462004-08-09 02:06:06 +0000626 # Update lineno (lines before this example)
Edward Lopera1ef6112004-08-09 16:14:41 +0000627 lineno += string.count('\n', charno, m.start())
Edward Loper7c748462004-08-09 02:06:06 +0000628 # Extract source/want from the regexp match.
Edward Lopera1ef6112004-08-09 16:14:41 +0000629 (source, want) = self._parse_example(m, name, lineno)
Edward Loper74bca7a2004-08-12 02:27:44 +0000630 # Extract extra options from the source.
631 options = self._find_options(source, name, lineno)
Edward Loper74bca7a2004-08-12 02:27:44 +0000632 # Create an Example, and add it to the list.
Edward Loperb51b2342004-08-17 16:37:12 +0000633 if not self._IS_BLANK_OR_COMMENT(source):
634 examples.append( Example(source, want, lineno,
635 len(m.group('indent')), options) )
Edward Loper7c748462004-08-09 02:06:06 +0000636 # Update lineno (lines inside this example)
Edward Lopera1ef6112004-08-09 16:14:41 +0000637 lineno += string.count('\n', m.start(), m.end())
Edward Loper7c748462004-08-09 02:06:06 +0000638 # Update charno.
639 charno = m.end()
640 return examples
641
Edward Lopera1ef6112004-08-09 16:14:41 +0000642 def get_program(self, string, name="<string>"):
Edward Loper7c748462004-08-09 02:06:06 +0000643 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000644 Return an executable program from the given string, as a string.
Edward Loper7c748462004-08-09 02:06:06 +0000645
646 The format of this isn't rigidly defined. In general, doctest
647 examples become the executable statements in the result, and
648 their expected outputs become comments, preceded by an \"#Expected:\"
649 comment. Everything else (text, comments, everything not part of
650 a doctest test) is also placed in comments.
651
Edward Lopera1ef6112004-08-09 16:14:41 +0000652 The optional argument `name` is a name identifying this
653 string, and is only used for error messages.
654
Edward Loper7c748462004-08-09 02:06:06 +0000655 >>> text = '''
656 ... >>> x, y = 2, 3 # no output expected
657 ... >>> if 1:
658 ... ... print x
659 ... ... print y
660 ... 2
661 ... 3
662 ...
663 ... Some text.
664 ... >>> x+y
665 ... 5
666 ... '''
Edward Lopera1ef6112004-08-09 16:14:41 +0000667 >>> print DocTestParser().get_program(text)
Edward Loper7c748462004-08-09 02:06:06 +0000668 x, y = 2, 3 # no output expected
669 if 1:
670 print x
671 print y
672 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +0000673 ## 2
674 ## 3
Edward Loper7c748462004-08-09 02:06:06 +0000675 #
Edward Lopera5db6002004-08-12 02:41:30 +0000676 # Some text.
Edward Loper7c748462004-08-09 02:06:06 +0000677 x+y
678 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +0000679 ## 5
Edward Loper7c748462004-08-09 02:06:06 +0000680 """
Edward Lopera5db6002004-08-12 02:41:30 +0000681 string = string.expandtabs()
682 # If all lines begin with the same indentation, then strip it.
683 min_indent = self._min_indent(string)
684 if min_indent > 0:
685 string = '\n'.join([l[min_indent:] for l in string.split('\n')])
686
Edward Loper7c748462004-08-09 02:06:06 +0000687 output = []
688 charnum, lineno = 0, 0
689 # Find all doctest examples in the string:
Edward Lopera1ef6112004-08-09 16:14:41 +0000690 for m in self._EXAMPLE_RE.finditer(string.expandtabs()):
Edward Loper7c748462004-08-09 02:06:06 +0000691 # Add any text before this example, as a comment.
692 if m.start() > charnum:
Edward Lopera1ef6112004-08-09 16:14:41 +0000693 lines = string[charnum:m.start()-1].split('\n')
Edward Loper7c748462004-08-09 02:06:06 +0000694 output.extend([self._comment_line(l) for l in lines])
695 lineno += len(lines)
696
697 # Extract source/want from the regexp match.
Edward Loper74bca7a2004-08-12 02:27:44 +0000698 (source, want) = self._parse_example(m, name, lineno)
Edward Loper7c748462004-08-09 02:06:06 +0000699 # Display the source
700 output.append(source)
701 # Display the expected output, if any
702 if want:
703 output.append('# Expected:')
Edward Lopera5db6002004-08-12 02:41:30 +0000704 output.extend(['## '+l for l in want.split('\n')])
Edward Loper7c748462004-08-09 02:06:06 +0000705
706 # Update the line number & char number.
Edward Lopera1ef6112004-08-09 16:14:41 +0000707 lineno += string.count('\n', m.start(), m.end())
Edward Loper7c748462004-08-09 02:06:06 +0000708 charnum = m.end()
709 # Add any remaining text, as comments.
710 output.extend([self._comment_line(l)
Edward Lopera1ef6112004-08-09 16:14:41 +0000711 for l in string[charnum:].split('\n')])
Edward Loper7c748462004-08-09 02:06:06 +0000712 # Trim junk on both ends.
713 while output and output[-1] == '#':
714 output.pop()
715 while output and output[0] == '#':
716 output.pop(0)
717 # Combine the output, and return it.
718 return '\n'.join(output)
719
Edward Loper74bca7a2004-08-12 02:27:44 +0000720 def _parse_example(self, m, name, lineno):
721 """
722 Given a regular expression match from `_EXAMPLE_RE` (`m`),
723 return a pair `(source, want)`, where `source` is the matched
724 example's source code (with prompts and indentation stripped);
725 and `want` is the example's expected output (with indentation
726 stripped).
727
728 `name` is the string's name, and `lineno` is the line number
729 where the example starts; both are used for error messages.
730 """
Edward Loper7c748462004-08-09 02:06:06 +0000731 # Get the example's indentation level.
732 indent = len(m.group('indent'))
733
734 # Divide source into lines; check that they're properly
735 # indented; and then strip their indentation & prompts.
736 source_lines = m.group('source').split('\n')
Edward Lopera1ef6112004-08-09 16:14:41 +0000737 self._check_prompt_blank(source_lines, indent, name, lineno)
Tim Petersc5049152004-08-22 17:34:58 +0000738 self._check_prefix(source_lines[1:], ' '*indent + '.', name, lineno)
Edward Loper7c748462004-08-09 02:06:06 +0000739 source = '\n'.join([sl[indent+4:] for sl in source_lines])
Edward Loper7c748462004-08-09 02:06:06 +0000740
Tim Petersc5049152004-08-22 17:34:58 +0000741 # Divide want into lines; check that it's properly indented; and
742 # then strip the indentation. Spaces before the last newline should
743 # be preserved, so plain rstrip() isn't good enough.
Jim Fulton07a349c2004-08-22 14:10:00 +0000744 want = m.group('want')
Jim Fulton07a349c2004-08-22 14:10:00 +0000745 want_lines = want.split('\n')
Tim Petersc5049152004-08-22 17:34:58 +0000746 if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]):
747 del want_lines[-1] # forget final newline & spaces after it
Edward Lopera1ef6112004-08-09 16:14:41 +0000748 self._check_prefix(want_lines, ' '*indent, name,
Tim Petersc5049152004-08-22 17:34:58 +0000749 lineno + len(source_lines))
Edward Loper7c748462004-08-09 02:06:06 +0000750 want = '\n'.join([wl[indent:] for wl in want_lines])
Edward Loper7c748462004-08-09 02:06:06 +0000751
752 return source, want
753
Edward Loper74bca7a2004-08-12 02:27:44 +0000754 # This regular expression looks for option directives in the
755 # source code of an example. Option directives are comments
756 # starting with "doctest:". Warning: this may give false
757 # positives for string-literals that contain the string
758 # "#doctest:". Eliminating these false positives would require
759 # actually parsing the string; but we limit them by ignoring any
760 # line containing "#doctest:" that is *followed* by a quote mark.
761 _OPTION_DIRECTIVE_RE = re.compile(r'#\s*doctest:\s*([^\n\'"]*)$',
762 re.MULTILINE)
763
764 def _find_options(self, source, name, lineno):
765 """
766 Return a dictionary containing option overrides extracted from
767 option directives in the given source string.
768
769 `name` is the string's name, and `lineno` is the line number
770 where the example starts; both are used for error messages.
771 """
772 options = {}
773 # (note: with the current regexp, this will match at most once:)
774 for m in self._OPTION_DIRECTIVE_RE.finditer(source):
775 option_strings = m.group(1).replace(',', ' ').split()
776 for option in option_strings:
777 if (option[0] not in '+-' or
778 option[1:] not in OPTIONFLAGS_BY_NAME):
779 raise ValueError('line %r of the doctest for %s '
780 'has an invalid option: %r' %
781 (lineno+1, name, option))
782 flag = OPTIONFLAGS_BY_NAME[option[1:]]
783 options[flag] = (option[0] == '+')
784 if options and self._IS_BLANK_OR_COMMENT(source):
785 raise ValueError('line %r of the doctest for %s has an option '
786 'directive on a line with no example: %r' %
787 (lineno, name, source))
788 return options
789
Edward Lopera5db6002004-08-12 02:41:30 +0000790 # This regular expression finds the indentation of every non-blank
791 # line in a string.
792 _INDENT_RE = re.compile('^([ ]+)(?=\S)', re.MULTILINE)
793
794 def _min_indent(self, s):
795 "Return the minimum indentation of any non-blank line in `s`"
796 return min([len(indent) for indent in self._INDENT_RE.findall(s)])
797
Edward Loper7c748462004-08-09 02:06:06 +0000798 def _comment_line(self, line):
Edward Loper74bca7a2004-08-12 02:27:44 +0000799 "Return a commented form of the given line"
Edward Loper7c748462004-08-09 02:06:06 +0000800 line = line.rstrip()
Tim Petersdd0e4752004-08-09 03:31:56 +0000801 if line:
Edward Lopera5db6002004-08-12 02:41:30 +0000802 return '# '+line
Tim Petersdd0e4752004-08-09 03:31:56 +0000803 else:
804 return '#'
Edward Loper7c748462004-08-09 02:06:06 +0000805
Edward Lopera1ef6112004-08-09 16:14:41 +0000806 def _check_prompt_blank(self, lines, indent, name, lineno):
Edward Loper74bca7a2004-08-12 02:27:44 +0000807 """
808 Given the lines of a source string (including prompts and
809 leading indentation), check to make sure that every prompt is
810 followed by a space character. If any line is not followed by
811 a space character, then raise ValueError.
812 """
Edward Loper7c748462004-08-09 02:06:06 +0000813 for i, line in enumerate(lines):
814 if len(line) >= indent+4 and line[indent+3] != ' ':
815 raise ValueError('line %r of the docstring for %s '
816 'lacks blank after %s: %r' %
Edward Lopera1ef6112004-08-09 16:14:41 +0000817 (lineno+i+1, name,
Edward Loper7c748462004-08-09 02:06:06 +0000818 line[indent:indent+3], line))
819
Edward Lopera1ef6112004-08-09 16:14:41 +0000820 def _check_prefix(self, lines, prefix, name, lineno):
Edward Loper74bca7a2004-08-12 02:27:44 +0000821 """
822 Check that every line in the given list starts with the given
823 prefix; if any line does not, then raise a ValueError.
824 """
Edward Loper7c748462004-08-09 02:06:06 +0000825 for i, line in enumerate(lines):
826 if line and not line.startswith(prefix):
827 raise ValueError('line %r of the docstring for %s has '
828 'inconsistent leading whitespace: %r' %
Edward Lopera1ef6112004-08-09 16:14:41 +0000829 (lineno+i+1, name, line))
Edward Loper7c748462004-08-09 02:06:06 +0000830
831
832######################################################################
833## 4. DocTest Finder
Tim Peters8485b562004-08-04 18:46:34 +0000834######################################################################
835
836class DocTestFinder:
837 """
838 A class used to extract the DocTests that are relevant to a given
839 object, from its docstring and the docstrings of its contained
840 objects. Doctests can currently be extracted from the following
841 object types: modules, functions, classes, methods, staticmethods,
842 classmethods, and properties.
Tim Peters8485b562004-08-04 18:46:34 +0000843 """
844
Edward Lopera1ef6112004-08-09 16:14:41 +0000845 def __init__(self, verbose=False, parser=DocTestParser(),
Tim Petersf727c6c2004-08-08 01:48:59 +0000846 recurse=True, _namefilter=None):
Tim Peters8485b562004-08-04 18:46:34 +0000847 """
848 Create a new doctest finder.
849
Edward Lopera1ef6112004-08-09 16:14:41 +0000850 The optional argument `parser` specifies a class or
Tim Peters19397e52004-08-06 22:02:59 +0000851 function that should be used to create new DocTest objects (or
Tim Peters161c9632004-08-08 03:38:33 +0000852 objects that implement the same interface as DocTest). The
Tim Peters19397e52004-08-06 22:02:59 +0000853 signature for this factory function should match the signature
854 of the DocTest constructor.
855
Tim Peters8485b562004-08-04 18:46:34 +0000856 If the optional argument `recurse` is false, then `find` will
857 only examine the given object, and not any contained objects.
858 """
Edward Lopera1ef6112004-08-09 16:14:41 +0000859 self._parser = parser
Tim Peters8485b562004-08-04 18:46:34 +0000860 self._verbose = verbose
Tim Peters8485b562004-08-04 18:46:34 +0000861 self._recurse = recurse
Tim Petersf727c6c2004-08-08 01:48:59 +0000862 # _namefilter is undocumented, and exists only for temporary backward-
863 # compatibility support of testmod's deprecated isprivate mess.
864 self._namefilter = _namefilter
Tim Peters8485b562004-08-04 18:46:34 +0000865
866 def find(self, obj, name=None, module=None, globs=None,
Tim Petersf3f57472004-08-08 06:11:48 +0000867 extraglobs=None):
Tim Peters8485b562004-08-04 18:46:34 +0000868 """
869 Return a list of the DocTests that are defined by the given
870 object's docstring, or by any of its contained objects'
871 docstrings.
872
873 The optional parameter `module` is the module that contains
Tim Petersf3f57472004-08-08 06:11:48 +0000874 the given object. If the module is not specified or is None, then
875 the test finder will attempt to automatically determine the
Tim Peters8485b562004-08-04 18:46:34 +0000876 correct module. The object's module is used:
877
878 - As a default namespace, if `globs` is not specified.
879 - To prevent the DocTestFinder from extracting DocTests
Tim Petersf3f57472004-08-08 06:11:48 +0000880 from objects that are imported from other modules.
Tim Peters8485b562004-08-04 18:46:34 +0000881 - To find the name of the file containing the object.
882 - To help find the line number of the object within its
883 file.
884
Tim Petersf3f57472004-08-08 06:11:48 +0000885 Contained objects whose module does not match `module` are ignored.
886
887 If `module` is False, no attempt to find the module will be made.
888 This is obscure, of use mostly in tests: if `module` is False, or
889 is None but cannot be found automatically, then all objects are
890 considered to belong to the (non-existent) module, so all contained
891 objects will (recursively) be searched for doctests.
892
Tim Peters8485b562004-08-04 18:46:34 +0000893 The globals for each DocTest is formed by combining `globs`
894 and `extraglobs` (bindings in `extraglobs` override bindings
895 in `globs`). A new copy of the globals dictionary is created
896 for each DocTest. If `globs` is not specified, then it
897 defaults to the module's `__dict__`, if specified, or {}
898 otherwise. If `extraglobs` is not specified, then it defaults
899 to {}.
900
Tim Peters8485b562004-08-04 18:46:34 +0000901 """
902 # If name was not specified, then extract it from the object.
903 if name is None:
904 name = getattr(obj, '__name__', None)
905 if name is None:
906 raise ValueError("DocTestFinder.find: name must be given "
907 "when obj.__name__ doesn't exist: %r" %
908 (type(obj),))
909
910 # Find the module that contains the given object (if obj is
911 # a module, then module=obj.). Note: this may fail, in which
912 # case module will be None.
Tim Petersf3f57472004-08-08 06:11:48 +0000913 if module is False:
914 module = None
915 elif module is None:
Tim Peters8485b562004-08-04 18:46:34 +0000916 module = inspect.getmodule(obj)
917
918 # Read the module's source code. This is used by
919 # DocTestFinder._find_lineno to find the line number for a
920 # given object's docstring.
921 try:
922 file = inspect.getsourcefile(obj) or inspect.getfile(obj)
923 source_lines = linecache.getlines(file)
924 if not source_lines:
925 source_lines = None
926 except TypeError:
927 source_lines = None
928
929 # Initialize globals, and merge in extraglobs.
Tim Peters8a7d2d52001-01-16 07:10:57 +0000930 if globs is None:
Tim Peters8485b562004-08-04 18:46:34 +0000931 if module is None:
932 globs = {}
933 else:
934 globs = module.__dict__.copy()
935 else:
936 globs = globs.copy()
937 if extraglobs is not None:
938 globs.update(extraglobs)
Tim Peters8a7d2d52001-01-16 07:10:57 +0000939
Tim Peters8485b562004-08-04 18:46:34 +0000940 # Recursively expore `obj`, extracting DocTests.
941 tests = []
Tim Petersf3f57472004-08-08 06:11:48 +0000942 self._find(tests, obj, name, module, source_lines, globs, {})
Tim Peters8485b562004-08-04 18:46:34 +0000943 return tests
944
945 def _filter(self, obj, prefix, base):
946 """
947 Return true if the given object should not be examined.
948 """
Tim Petersf727c6c2004-08-08 01:48:59 +0000949 return (self._namefilter is not None and
950 self._namefilter(prefix, base))
Tim Peters8485b562004-08-04 18:46:34 +0000951
952 def _from_module(self, module, object):
953 """
954 Return true if the given object is defined in the given
955 module.
956 """
957 if module is None:
958 return True
959 elif inspect.isfunction(object):
960 return module.__dict__ is object.func_globals
961 elif inspect.isclass(object):
962 return module.__name__ == object.__module__
963 elif inspect.getmodule(object) is not None:
964 return module is inspect.getmodule(object)
965 elif hasattr(object, '__module__'):
966 return module.__name__ == object.__module__
967 elif isinstance(object, property):
968 return True # [XX] no way not be sure.
969 else:
970 raise ValueError("object must be a class or function")
971
Tim Petersf3f57472004-08-08 06:11:48 +0000972 def _find(self, tests, obj, name, module, source_lines, globs, seen):
Tim Peters8485b562004-08-04 18:46:34 +0000973 """
974 Find tests for the given object and any contained objects, and
975 add them to `tests`.
976 """
977 if self._verbose:
978 print 'Finding tests in %s' % name
979
980 # If we've already processed this object, then ignore it.
981 if id(obj) in seen:
982 return
983 seen[id(obj)] = 1
984
985 # Find a test for this object, and add it to the list of tests.
986 test = self._get_test(obj, name, module, globs, source_lines)
987 if test is not None:
988 tests.append(test)
989
990 # Look for tests in a module's contained objects.
991 if inspect.ismodule(obj) and self._recurse:
992 for valname, val in obj.__dict__.items():
993 # Check if this contained object should be ignored.
994 if self._filter(val, name, valname):
995 continue
996 valname = '%s.%s' % (name, valname)
997 # Recurse to functions & classes.
998 if ((inspect.isfunction(val) or inspect.isclass(val)) and
Tim Petersf3f57472004-08-08 06:11:48 +0000999 self._from_module(module, val)):
Tim Peters8485b562004-08-04 18:46:34 +00001000 self._find(tests, val, valname, module, source_lines,
Tim Petersf3f57472004-08-08 06:11:48 +00001001 globs, seen)
Tim Peters8485b562004-08-04 18:46:34 +00001002
1003 # Look for tests in a module's __test__ dictionary.
1004 if inspect.ismodule(obj) and self._recurse:
1005 for valname, val in getattr(obj, '__test__', {}).items():
1006 if not isinstance(valname, basestring):
1007 raise ValueError("DocTestFinder.find: __test__ keys "
1008 "must be strings: %r" %
1009 (type(valname),))
1010 if not (inspect.isfunction(val) or inspect.isclass(val) or
1011 inspect.ismethod(val) or inspect.ismodule(val) or
1012 isinstance(val, basestring)):
1013 raise ValueError("DocTestFinder.find: __test__ values "
1014 "must be strings, functions, methods, "
1015 "classes, or modules: %r" %
1016 (type(val),))
1017 valname = '%s.%s' % (name, valname)
1018 self._find(tests, val, valname, module, source_lines,
Tim Petersf3f57472004-08-08 06:11:48 +00001019 globs, seen)
Tim Peters8485b562004-08-04 18:46:34 +00001020
1021 # Look for tests in a class's contained objects.
1022 if inspect.isclass(obj) and self._recurse:
1023 for valname, val in obj.__dict__.items():
1024 # Check if this contained object should be ignored.
1025 if self._filter(val, name, valname):
1026 continue
1027 # Special handling for staticmethod/classmethod.
1028 if isinstance(val, staticmethod):
1029 val = getattr(obj, valname)
1030 if isinstance(val, classmethod):
1031 val = getattr(obj, valname).im_func
1032
1033 # Recurse to methods, properties, and nested classes.
1034 if ((inspect.isfunction(val) or inspect.isclass(val) or
Tim Petersf3f57472004-08-08 06:11:48 +00001035 isinstance(val, property)) and
1036 self._from_module(module, val)):
Tim Peters8485b562004-08-04 18:46:34 +00001037 valname = '%s.%s' % (name, valname)
1038 self._find(tests, val, valname, module, source_lines,
Tim Petersf3f57472004-08-08 06:11:48 +00001039 globs, seen)
Tim Peters8485b562004-08-04 18:46:34 +00001040
1041 def _get_test(self, obj, name, module, globs, source_lines):
1042 """
1043 Return a DocTest for the given object, if it defines a docstring;
1044 otherwise, return None.
1045 """
1046 # Extract the object's docstring. If it doesn't have one,
1047 # then return None (no test for this object).
1048 if isinstance(obj, basestring):
1049 docstring = obj
1050 else:
1051 try:
1052 if obj.__doc__ is None:
1053 return None
1054 docstring = str(obj.__doc__)
1055 except (TypeError, AttributeError):
1056 return None
1057
1058 # Don't bother if the docstring is empty.
1059 if not docstring:
1060 return None
1061
1062 # Find the docstring's location in the file.
1063 lineno = self._find_lineno(obj, source_lines)
1064
1065 # Return a DocTest for this object.
1066 if module is None:
1067 filename = None
1068 else:
1069 filename = getattr(module, '__file__', module.__name__)
Jim Fulton07a349c2004-08-22 14:10:00 +00001070 if filename[-4:] in (".pyc", ".pyo"):
1071 filename = filename[:-1]
Edward Lopera1ef6112004-08-09 16:14:41 +00001072 return self._parser.get_doctest(docstring, globs, name,
1073 filename, lineno)
Tim Peters8485b562004-08-04 18:46:34 +00001074
1075 def _find_lineno(self, obj, source_lines):
1076 """
1077 Return a line number of the given object's docstring. Note:
1078 this method assumes that the object has a docstring.
1079 """
1080 lineno = None
1081
1082 # Find the line number for modules.
1083 if inspect.ismodule(obj):
1084 lineno = 0
1085
1086 # Find the line number for classes.
1087 # Note: this could be fooled if a class is defined multiple
1088 # times in a single file.
1089 if inspect.isclass(obj):
1090 if source_lines is None:
1091 return None
1092 pat = re.compile(r'^\s*class\s*%s\b' %
1093 getattr(obj, '__name__', '-'))
1094 for i, line in enumerate(source_lines):
1095 if pat.match(line):
1096 lineno = i
1097 break
1098
1099 # Find the line number for functions & methods.
1100 if inspect.ismethod(obj): obj = obj.im_func
1101 if inspect.isfunction(obj): obj = obj.func_code
1102 if inspect.istraceback(obj): obj = obj.tb_frame
1103 if inspect.isframe(obj): obj = obj.f_code
1104 if inspect.iscode(obj):
1105 lineno = getattr(obj, 'co_firstlineno', None)-1
1106
1107 # Find the line number where the docstring starts. Assume
1108 # that it's the first line that begins with a quote mark.
1109 # Note: this could be fooled by a multiline function
1110 # signature, where a continuation line begins with a quote
1111 # mark.
1112 if lineno is not None:
1113 if source_lines is None:
1114 return lineno+1
1115 pat = re.compile('(^|.*:)\s*\w*("|\')')
1116 for lineno in range(lineno, len(source_lines)):
1117 if pat.match(source_lines[lineno]):
1118 return lineno
1119
1120 # We couldn't find the line number.
1121 return None
1122
1123######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00001124## 5. DocTest Runner
Tim Peters8485b562004-08-04 18:46:34 +00001125######################################################################
1126
Tim Peters8485b562004-08-04 18:46:34 +00001127class DocTestRunner:
1128 """
1129 A class used to run DocTest test cases, and accumulate statistics.
1130 The `run` method is used to process a single DocTest case. It
1131 returns a tuple `(f, t)`, where `t` is the number of test cases
1132 tried, and `f` is the number of test cases that failed.
1133
1134 >>> tests = DocTestFinder().find(_TestClass)
1135 >>> runner = DocTestRunner(verbose=False)
1136 >>> for test in tests:
1137 ... print runner.run(test)
1138 (0, 2)
1139 (0, 1)
1140 (0, 2)
1141 (0, 2)
1142
1143 The `summarize` method prints a summary of all the test cases that
1144 have been run by the runner, and returns an aggregated `(f, t)`
1145 tuple:
1146
1147 >>> runner.summarize(verbose=1)
1148 4 items passed all tests:
1149 2 tests in _TestClass
1150 2 tests in _TestClass.__init__
1151 2 tests in _TestClass.get
1152 1 tests in _TestClass.square
1153 7 tests in 4 items.
1154 7 passed and 0 failed.
1155 Test passed.
1156 (0, 7)
1157
1158 The aggregated number of tried examples and failed examples is
1159 also available via the `tries` and `failures` attributes:
1160
1161 >>> runner.tries
1162 7
1163 >>> runner.failures
1164 0
1165
1166 The comparison between expected outputs and actual outputs is done
Edward Loper34fcb142004-08-09 02:45:41 +00001167 by an `OutputChecker`. This comparison may be customized with a
1168 number of option flags; see the documentation for `testmod` for
1169 more information. If the option flags are insufficient, then the
1170 comparison may also be customized by passing a subclass of
1171 `OutputChecker` to the constructor.
Tim Peters8485b562004-08-04 18:46:34 +00001172
1173 The test runner's display output can be controlled in two ways.
1174 First, an output function (`out) can be passed to
1175 `TestRunner.run`; this function will be called with strings that
1176 should be displayed. It defaults to `sys.stdout.write`. If
1177 capturing the output is not sufficient, then the display output
1178 can be also customized by subclassing DocTestRunner, and
1179 overriding the methods `report_start`, `report_success`,
1180 `report_unexpected_exception`, and `report_failure`.
1181 """
1182 # This divider string is used to separate failure messages, and to
1183 # separate sections of the summary.
1184 DIVIDER = "*" * 70
1185
Edward Loper34fcb142004-08-09 02:45:41 +00001186 def __init__(self, checker=None, verbose=None, optionflags=0):
Tim Peters8485b562004-08-04 18:46:34 +00001187 """
1188 Create a new test runner.
1189
Edward Loper34fcb142004-08-09 02:45:41 +00001190 Optional keyword arg `checker` is the `OutputChecker` that
1191 should be used to compare the expected outputs and actual
1192 outputs of doctest examples.
1193
Tim Peters8485b562004-08-04 18:46:34 +00001194 Optional keyword arg 'verbose' prints lots of stuff if true,
1195 only failures if false; by default, it's true iff '-v' is in
1196 sys.argv.
1197
1198 Optional argument `optionflags` can be used to control how the
1199 test runner compares expected output to actual output, and how
1200 it displays failures. See the documentation for `testmod` for
1201 more information.
1202 """
Edward Loper34fcb142004-08-09 02:45:41 +00001203 self._checker = checker or OutputChecker()
Tim Peters8a7d2d52001-01-16 07:10:57 +00001204 if verbose is None:
Tim Peters8485b562004-08-04 18:46:34 +00001205 verbose = '-v' in sys.argv
1206 self._verbose = verbose
Tim Peters6ebe61f2003-06-27 20:48:05 +00001207 self.optionflags = optionflags
Jim Fulton07a349c2004-08-22 14:10:00 +00001208 self.original_optionflags = optionflags
Tim Peters6ebe61f2003-06-27 20:48:05 +00001209
Tim Peters8485b562004-08-04 18:46:34 +00001210 # Keep track of the examples we've run.
1211 self.tries = 0
1212 self.failures = 0
1213 self._name2ft = {}
Tim Peters8a7d2d52001-01-16 07:10:57 +00001214
Tim Peters8485b562004-08-04 18:46:34 +00001215 # Create a fake output target for capturing doctest output.
1216 self._fakeout = _SpoofOut()
Tim Peters4fd9e2f2001-08-18 00:05:50 +00001217
Tim Peters8485b562004-08-04 18:46:34 +00001218 #/////////////////////////////////////////////////////////////////
Tim Peters8485b562004-08-04 18:46:34 +00001219 # Reporting methods
1220 #/////////////////////////////////////////////////////////////////
Tim Peters17111f32001-10-03 04:08:26 +00001221
Tim Peters8485b562004-08-04 18:46:34 +00001222 def report_start(self, out, test, example):
Tim Peters8a7d2d52001-01-16 07:10:57 +00001223 """
Tim Peters8485b562004-08-04 18:46:34 +00001224 Report that the test runner is about to process the given
1225 example. (Only displays a message if verbose=True)
1226 """
1227 if self._verbose:
1228 out(_tag_msg("Trying", example.source) +
1229 _tag_msg("Expecting", example.want or "nothing"))
Tim Peters8a7d2d52001-01-16 07:10:57 +00001230
Tim Peters8485b562004-08-04 18:46:34 +00001231 def report_success(self, out, test, example, got):
1232 """
1233 Report that the given example ran successfully. (Only
1234 displays a message if verbose=True)
1235 """
1236 if self._verbose:
1237 out("ok\n")
Tim Peters8a7d2d52001-01-16 07:10:57 +00001238
Tim Peters8485b562004-08-04 18:46:34 +00001239 def report_failure(self, out, test, example, got):
1240 """
1241 Report that the given example failed.
1242 """
1243 # Print an error message.
Edward Loper8e4a34b2004-08-12 02:34:27 +00001244 out(self._failure_header(test, example) +
Edward Loper34fcb142004-08-09 02:45:41 +00001245 self._checker.output_difference(example.want, got,
1246 self.optionflags))
Tim Peters7402f792001-10-02 03:53:41 +00001247
Tim Peters8485b562004-08-04 18:46:34 +00001248 def report_unexpected_exception(self, out, test, example, exc_info):
1249 """
1250 Report that the given example raised an unexpected exception.
1251 """
Edward Loper8e4a34b2004-08-12 02:34:27 +00001252 out(self._failure_header(test, example) +
1253 _tag_msg("Exception raised", _exception_traceback(exc_info)))
Tim Peters7402f792001-10-02 03:53:41 +00001254
Edward Loper8e4a34b2004-08-12 02:34:27 +00001255 def _failure_header(self, test, example):
Jim Fulton07a349c2004-08-22 14:10:00 +00001256 out = [self.DIVIDER]
1257 if test.filename:
1258 if test.lineno is not None and example.lineno is not None:
1259 lineno = test.lineno + example.lineno + 1
1260 else:
1261 lineno = '?'
1262 out.append('File "%s", line %s, in %s' %
1263 (test.filename, lineno, test.name))
Tim Peters8485b562004-08-04 18:46:34 +00001264 else:
Jim Fulton07a349c2004-08-22 14:10:00 +00001265 out.append('Line %s, in %s' % (example.lineno+1, test.name))
1266 out.append('Failed example:')
1267 source = example.source
1268 if source.endswith('\n'):
1269 source = source[:-1]
1270 out.append(' ' + '\n '.join(source.split('\n')))
1271 return '\n'.join(out)+'\n'
Tim Peters7402f792001-10-02 03:53:41 +00001272
Tim Peters8485b562004-08-04 18:46:34 +00001273 #/////////////////////////////////////////////////////////////////
1274 # DocTest Running
1275 #/////////////////////////////////////////////////////////////////
Tim Peters7402f792001-10-02 03:53:41 +00001276
Tim Peters8485b562004-08-04 18:46:34 +00001277 # A regular expression for handling `want` strings that contain
Tim Peters41a65ea2004-08-13 03:55:05 +00001278 # expected exceptions. It divides `want` into three pieces:
1279 # - the pre-exception output (`want`)
1280 # - the traceback header line (`hdr`)
1281 # - the exception message (`msg`), as generated by
1282 # traceback.format_exception_only()
1283 # `msg` may have multiple lines. We assume/require that the
1284 # exception message is the first non-indented line starting with a word
1285 # character following the traceback header line.
1286 _EXCEPTION_RE = re.compile(r"""
1287 (?P<want> .*?) # suck up everything until traceback header
1288 # Grab the traceback header. Different versions of Python have
1289 # said different things on the first traceback line.
1290 ^(?P<hdr> Traceback\ \(
1291 (?: most\ recent\ call\ last
1292 | innermost\ last
1293 ) \) :
1294 )
1295 \s* $ # toss trailing whitespace on traceback header
1296 .*? # don't blink: absorb stuff until a line *starts* with \w
1297 ^ (?P<msg> \w+ .*)
1298 """, re.VERBOSE | re.MULTILINE | re.DOTALL)
Tim Peters7402f792001-10-02 03:53:41 +00001299
Tim Peters8485b562004-08-04 18:46:34 +00001300 def __run(self, test, compileflags, out):
Tim Peters8a7d2d52001-01-16 07:10:57 +00001301 """
Tim Peters8485b562004-08-04 18:46:34 +00001302 Run the examples in `test`. Write the outcome of each example
1303 with one of the `DocTestRunner.report_*` methods, using the
1304 writer function `out`. `compileflags` is the set of compiler
1305 flags that should be used to execute examples. Return a tuple
1306 `(f, t)`, where `t` is the number of examples tried, and `f`
1307 is the number of examples that failed. The examples are run
1308 in the namespace `test.globs`.
1309 """
1310 # Keep track of the number of failures and tries.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001311 failures = tries = 0
Tim Peters8485b562004-08-04 18:46:34 +00001312
1313 # Save the option flags (since option directives can be used
1314 # to modify them).
1315 original_optionflags = self.optionflags
1316
1317 # Process each example.
1318 for example in test.examples:
Edward Loper74bca7a2004-08-12 02:27:44 +00001319 # Merge in the example's options.
1320 self.optionflags = original_optionflags
1321 if example.options:
1322 for (optionflag, val) in example.options.items():
1323 if val:
1324 self.optionflags |= optionflag
1325 else:
1326 self.optionflags &= ~optionflag
Tim Peters8485b562004-08-04 18:46:34 +00001327
1328 # Record that we started this example.
1329 tries += 1
1330 self.report_start(out, test, example)
1331
1332 # Run the example in the given context (globs), and record
1333 # any exception that gets raised. (But don't intercept
1334 # keyboard interrupts.)
1335 try:
Tim Peters208ca702004-08-09 04:12:36 +00001336 # Don't blink! This is where the user's code gets run.
Tim Petersbb431472004-08-09 03:51:46 +00001337 exec compile(example.source, "<string>", "single",
Tim Peters8485b562004-08-04 18:46:34 +00001338 compileflags, 1) in test.globs
1339 exception = None
1340 except KeyboardInterrupt:
1341 raise
1342 except:
1343 exception = sys.exc_info()
1344
Tim Peters208ca702004-08-09 04:12:36 +00001345 got = self._fakeout.getvalue() # the actual output
Tim Peters8485b562004-08-04 18:46:34 +00001346 self._fakeout.truncate(0)
1347
1348 # If the example executed without raising any exceptions,
1349 # then verify its output and report its outcome.
1350 if exception is None:
Edward Loper34fcb142004-08-09 02:45:41 +00001351 if self._checker.check_output(example.want, got,
1352 self.optionflags):
Tim Peters8485b562004-08-04 18:46:34 +00001353 self.report_success(out, test, example, got)
Tim Peters8a7d2d52001-01-16 07:10:57 +00001354 else:
Tim Peters8485b562004-08-04 18:46:34 +00001355 self.report_failure(out, test, example, got)
1356 failures += 1
1357
1358 # If the example raised an exception, then check if it was
1359 # expected.
1360 else:
1361 exc_info = sys.exc_info()
1362 exc_msg = traceback.format_exception_only(*exc_info[:2])[-1]
1363
1364 # Search the `want` string for an exception. If we don't
1365 # find one, then report an unexpected exception.
1366 m = self._EXCEPTION_RE.match(example.want)
1367 if m is None:
1368 self.report_unexpected_exception(out, test, example,
1369 exc_info)
1370 failures += 1
1371 else:
Tim Peters41a65ea2004-08-13 03:55:05 +00001372 e_want, e_msg = m.group('want', 'msg')
Tim Peters8485b562004-08-04 18:46:34 +00001373 # The test passes iff the pre-exception output and
1374 # the exception description match the values given
1375 # in `want`.
Tim Peters41a65ea2004-08-13 03:55:05 +00001376 if (self._checker.check_output(e_want, got,
Edward Loper34fcb142004-08-09 02:45:41 +00001377 self.optionflags) and
Tim Peters41a65ea2004-08-13 03:55:05 +00001378 self._checker.check_output(e_msg, exc_msg,
Edward Loper34fcb142004-08-09 02:45:41 +00001379 self.optionflags)):
Tim Peters8485b562004-08-04 18:46:34 +00001380 self.report_success(out, test, example,
Tim Peters41a65ea2004-08-13 03:55:05 +00001381 got + _exception_traceback(exc_info))
Tim Peters8485b562004-08-04 18:46:34 +00001382 else:
1383 self.report_failure(out, test, example,
Tim Peters41a65ea2004-08-13 03:55:05 +00001384 got + _exception_traceback(exc_info))
Tim Peters8485b562004-08-04 18:46:34 +00001385 failures += 1
1386
1387 # Restore the option flags (in case they were modified)
1388 self.optionflags = original_optionflags
1389
1390 # Record and return the number of failures and tries.
1391 self.__record_outcome(test, failures, tries)
Tim Peters8a7d2d52001-01-16 07:10:57 +00001392 return failures, tries
1393
Tim Peters8485b562004-08-04 18:46:34 +00001394 def __record_outcome(self, test, f, t):
1395 """
1396 Record the fact that the given DocTest (`test`) generated `f`
1397 failures out of `t` tried examples.
1398 """
1399 f2, t2 = self._name2ft.get(test.name, (0,0))
1400 self._name2ft[test.name] = (f+f2, t+t2)
1401 self.failures += f
1402 self.tries += t
1403
1404 def run(self, test, compileflags=None, out=None, clear_globs=True):
1405 """
1406 Run the examples in `test`, and display the results using the
1407 writer function `out`.
1408
1409 The examples are run in the namespace `test.globs`. If
1410 `clear_globs` is true (the default), then this namespace will
1411 be cleared after the test runs, to help with garbage
1412 collection. If you would like to examine the namespace after
1413 the test completes, then use `clear_globs=False`.
1414
1415 `compileflags` gives the set of flags that should be used by
1416 the Python compiler when running the examples. If not
1417 specified, then it will default to the set of future-import
1418 flags that apply to `globs`.
1419
1420 The output of each example is checked using
1421 `DocTestRunner.check_output`, and the results are formatted by
1422 the `DocTestRunner.report_*` methods.
1423 """
1424 if compileflags is None:
1425 compileflags = _extract_future_flags(test.globs)
Jim Fulton356fd192004-08-09 11:34:47 +00001426
Tim Peters6c542b72004-08-09 16:43:36 +00001427 save_stdout = sys.stdout
Tim Peters8485b562004-08-04 18:46:34 +00001428 if out is None:
Tim Peters6c542b72004-08-09 16:43:36 +00001429 out = save_stdout.write
1430 sys.stdout = self._fakeout
Tim Peters8485b562004-08-04 18:46:34 +00001431
Tim Peters6c542b72004-08-09 16:43:36 +00001432 # Patch pdb.set_trace to restore sys.stdout, so that interactive
1433 # debugging output is visible (not still redirected to self._fakeout).
1434 # Note that we run "the real" pdb.set_trace (captured at doctest
1435 # import time) in our replacement. Because the current run() may
1436 # run another doctest (and so on), the current pdb.set_trace may be
1437 # our set_trace function, which changes sys.stdout. If we called
1438 # a chain of those, we wouldn't be left with the save_stdout
1439 # *this* run() invocation wants.
Jim Fulton356fd192004-08-09 11:34:47 +00001440 def set_trace():
Tim Peters6c542b72004-08-09 16:43:36 +00001441 sys.stdout = save_stdout
Jim Fulton356fd192004-08-09 11:34:47 +00001442 real_pdb_set_trace()
1443
Tim Peters6c542b72004-08-09 16:43:36 +00001444 save_set_trace = pdb.set_trace
1445 pdb.set_trace = set_trace
Tim Peters8485b562004-08-04 18:46:34 +00001446 try:
Tim Peters8485b562004-08-04 18:46:34 +00001447 return self.__run(test, compileflags, out)
1448 finally:
Tim Peters6c542b72004-08-09 16:43:36 +00001449 sys.stdout = save_stdout
1450 pdb.set_trace = save_set_trace
Tim Peters8485b562004-08-04 18:46:34 +00001451 if clear_globs:
1452 test.globs.clear()
1453
1454 #/////////////////////////////////////////////////////////////////
1455 # Summarization
1456 #/////////////////////////////////////////////////////////////////
Tim Peters8a7d2d52001-01-16 07:10:57 +00001457 def summarize(self, verbose=None):
1458 """
Tim Peters8485b562004-08-04 18:46:34 +00001459 Print a summary of all the test cases that have been run by
1460 this DocTestRunner, and return a tuple `(f, t)`, where `f` is
1461 the total number of failed examples, and `t` is the total
1462 number of tried examples.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001463
Tim Peters8485b562004-08-04 18:46:34 +00001464 The optional `verbose` argument controls how detailed the
1465 summary is. If the verbosity is not specified, then the
1466 DocTestRunner's verbosity is used.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001467 """
Tim Peters8a7d2d52001-01-16 07:10:57 +00001468 if verbose is None:
Tim Peters8485b562004-08-04 18:46:34 +00001469 verbose = self._verbose
Tim Peters8a7d2d52001-01-16 07:10:57 +00001470 notests = []
1471 passed = []
1472 failed = []
1473 totalt = totalf = 0
Tim Peters8485b562004-08-04 18:46:34 +00001474 for x in self._name2ft.items():
Tim Peters8a7d2d52001-01-16 07:10:57 +00001475 name, (f, t) = x
1476 assert f <= t
Tim Peters8485b562004-08-04 18:46:34 +00001477 totalt += t
1478 totalf += f
Tim Peters8a7d2d52001-01-16 07:10:57 +00001479 if t == 0:
1480 notests.append(name)
1481 elif f == 0:
1482 passed.append( (name, t) )
1483 else:
1484 failed.append(x)
1485 if verbose:
1486 if notests:
1487 print len(notests), "items had no tests:"
1488 notests.sort()
1489 for thing in notests:
1490 print " ", thing
1491 if passed:
1492 print len(passed), "items passed all tests:"
1493 passed.sort()
1494 for thing, count in passed:
1495 print " %3d tests in %s" % (count, thing)
1496 if failed:
Tim Peters8485b562004-08-04 18:46:34 +00001497 print self.DIVIDER
Tim Peters8a7d2d52001-01-16 07:10:57 +00001498 print len(failed), "items had failures:"
1499 failed.sort()
1500 for thing, (f, t) in failed:
1501 print " %3d of %3d in %s" % (f, t, thing)
1502 if verbose:
Tim Peters8485b562004-08-04 18:46:34 +00001503 print totalt, "tests in", len(self._name2ft), "items."
Tim Peters8a7d2d52001-01-16 07:10:57 +00001504 print totalt - totalf, "passed and", totalf, "failed."
1505 if totalf:
1506 print "***Test Failed***", totalf, "failures."
1507 elif verbose:
1508 print "Test passed."
1509 return totalf, totalt
1510
Edward Loper34fcb142004-08-09 02:45:41 +00001511class OutputChecker:
1512 """
1513 A class used to check the whether the actual output from a doctest
1514 example matches the expected output. `OutputChecker` defines two
1515 methods: `check_output`, which compares a given pair of outputs,
1516 and returns true if they match; and `output_difference`, which
1517 returns a string describing the differences between two outputs.
1518 """
1519 def check_output(self, want, got, optionflags):
1520 """
Edward Loper74bca7a2004-08-12 02:27:44 +00001521 Return True iff the actual output from an example (`got`)
1522 matches the expected output (`want`). These strings are
1523 always considered to match if they are identical; but
1524 depending on what option flags the test runner is using,
1525 several non-exact match types are also possible. See the
1526 documentation for `TestRunner` for more information about
1527 option flags.
Edward Loper34fcb142004-08-09 02:45:41 +00001528 """
1529 # Handle the common case first, for efficiency:
1530 # if they're string-identical, always return true.
1531 if got == want:
1532 return True
1533
1534 # The values True and False replaced 1 and 0 as the return
1535 # value for boolean comparisons in Python 2.3.
1536 if not (optionflags & DONT_ACCEPT_TRUE_FOR_1):
1537 if (got,want) == ("True\n", "1\n"):
1538 return True
1539 if (got,want) == ("False\n", "0\n"):
1540 return True
1541
1542 # <BLANKLINE> can be used as a special sequence to signify a
1543 # blank line, unless the DONT_ACCEPT_BLANKLINE flag is used.
1544 if not (optionflags & DONT_ACCEPT_BLANKLINE):
1545 # Replace <BLANKLINE> in want with a blank line.
1546 want = re.sub('(?m)^%s\s*?$' % re.escape(BLANKLINE_MARKER),
1547 '', want)
1548 # If a line in got contains only spaces, then remove the
1549 # spaces.
1550 got = re.sub('(?m)^\s*?$', '', got)
1551 if got == want:
1552 return True
1553
1554 # This flag causes doctest to ignore any differences in the
1555 # contents of whitespace strings. Note that this can be used
1556 # in conjunction with the ELLISPIS flag.
Tim Peters1cf3aa62004-08-19 06:49:33 +00001557 if optionflags & NORMALIZE_WHITESPACE:
Edward Loper34fcb142004-08-09 02:45:41 +00001558 got = ' '.join(got.split())
1559 want = ' '.join(want.split())
1560 if got == want:
1561 return True
1562
1563 # The ELLIPSIS flag says to let the sequence "..." in `want`
Tim Peters26b3ebb2004-08-19 08:10:08 +00001564 # match any substring in `got`.
Tim Peters1cf3aa62004-08-19 06:49:33 +00001565 if optionflags & ELLIPSIS:
Tim Petersb0a04e12004-08-20 02:08:04 +00001566 if _ellipsis_match(want, got):
Edward Loper34fcb142004-08-09 02:45:41 +00001567 return True
1568
1569 # We didn't find any match; return false.
1570 return False
1571
1572 def output_difference(self, want, got, optionflags):
1573 """
1574 Return a string describing the differences between the
Edward Loper74bca7a2004-08-12 02:27:44 +00001575 expected output for an example (`want`) and the actual output
1576 (`got`). `optionflags` is the set of option flags used to
1577 compare `want` and `got`. `indent` is the indentation of the
1578 original example.
Edward Loper34fcb142004-08-09 02:45:41 +00001579 """
Tim Petersc5049152004-08-22 17:34:58 +00001580
Edward Loper68ba9a62004-08-12 02:43:49 +00001581 # If <BLANKLINE>s are being used, then replace blank lines
1582 # with <BLANKLINE> in the actual output string.
Edward Loper34fcb142004-08-09 02:45:41 +00001583 if not (optionflags & DONT_ACCEPT_BLANKLINE):
Edward Loper68ba9a62004-08-12 02:43:49 +00001584 got = re.sub('(?m)^[ ]*(?=\n)', BLANKLINE_MARKER, got)
Edward Loper34fcb142004-08-09 02:45:41 +00001585
1586 # Check if we should use diff. Don't use diff if the actual
1587 # or expected outputs are too short, or if the expected output
1588 # contains an ellipsis marker.
1589 if ((optionflags & (UNIFIED_DIFF | CONTEXT_DIFF)) and
1590 want.count('\n') > 2 and got.count('\n') > 2 and
1591 not (optionflags & ELLIPSIS and '...' in want)):
1592 # Split want & got into lines.
1593 want_lines = [l+'\n' for l in want.split('\n')]
1594 got_lines = [l+'\n' for l in got.split('\n')]
1595 # Use difflib to find their differences.
1596 if optionflags & UNIFIED_DIFF:
1597 diff = difflib.unified_diff(want_lines, got_lines, n=2,
1598 fromfile='Expected', tofile='Got')
1599 kind = 'unified'
1600 elif optionflags & CONTEXT_DIFF:
1601 diff = difflib.context_diff(want_lines, got_lines, n=2,
1602 fromfile='Expected', tofile='Got')
1603 kind = 'context'
1604 else:
1605 assert 0, 'Bad diff option'
1606 # Remove trailing whitespace on diff output.
1607 diff = [line.rstrip() + '\n' for line in diff]
1608 return _tag_msg("Differences (" + kind + " diff)",
1609 ''.join(diff))
1610
1611 # If we're not using diff, then simply list the expected
1612 # output followed by the actual output.
Jim Fulton07a349c2004-08-22 14:10:00 +00001613 if want.endswith('\n'):
1614 want = want[:-1]
1615 want = ' ' + '\n '.join(want.split('\n'))
1616 if got.endswith('\n'):
1617 got = got[:-1]
1618 got = ' ' + '\n '.join(got.split('\n'))
1619 return "Expected:\n%s\nGot:\n%s\n" % (want, got)
Edward Loper34fcb142004-08-09 02:45:41 +00001620
Tim Peters19397e52004-08-06 22:02:59 +00001621class DocTestFailure(Exception):
1622 """A DocTest example has failed in debugging mode.
1623
1624 The exception instance has variables:
1625
1626 - test: the DocTest object being run
1627
1628 - excample: the Example object that failed
1629
1630 - got: the actual output
1631 """
1632 def __init__(self, test, example, got):
1633 self.test = test
1634 self.example = example
1635 self.got = got
1636
1637 def __str__(self):
1638 return str(self.test)
1639
1640class UnexpectedException(Exception):
1641 """A DocTest example has encountered an unexpected exception
1642
1643 The exception instance has variables:
1644
1645 - test: the DocTest object being run
1646
1647 - excample: the Example object that failed
1648
1649 - exc_info: the exception info
1650 """
1651 def __init__(self, test, example, exc_info):
1652 self.test = test
1653 self.example = example
1654 self.exc_info = exc_info
1655
1656 def __str__(self):
1657 return str(self.test)
Tim Petersd1b78272004-08-07 06:03:09 +00001658
Tim Peters19397e52004-08-06 22:02:59 +00001659class DebugRunner(DocTestRunner):
1660 r"""Run doc tests but raise an exception as soon as there is a failure.
1661
1662 If an unexpected exception occurs, an UnexpectedException is raised.
1663 It contains the test, the example, and the original exception:
1664
1665 >>> runner = DebugRunner(verbose=False)
Edward Lopera1ef6112004-08-09 16:14:41 +00001666 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
1667 ... {}, 'foo', 'foo.py', 0)
Tim Peters19397e52004-08-06 22:02:59 +00001668 >>> try:
1669 ... runner.run(test)
1670 ... except UnexpectedException, failure:
1671 ... pass
1672
1673 >>> failure.test is test
1674 True
1675
1676 >>> failure.example.want
1677 '42\n'
1678
1679 >>> exc_info = failure.exc_info
1680 >>> raise exc_info[0], exc_info[1], exc_info[2]
1681 Traceback (most recent call last):
1682 ...
1683 KeyError
1684
1685 We wrap the original exception to give the calling application
1686 access to the test and example information.
1687
1688 If the output doesn't match, then a DocTestFailure is raised:
1689
Edward Lopera1ef6112004-08-09 16:14:41 +00001690 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00001691 ... >>> x = 1
1692 ... >>> x
1693 ... 2
1694 ... ''', {}, 'foo', 'foo.py', 0)
1695
1696 >>> try:
1697 ... runner.run(test)
1698 ... except DocTestFailure, failure:
1699 ... pass
1700
1701 DocTestFailure objects provide access to the test:
1702
1703 >>> failure.test is test
1704 True
1705
1706 As well as to the example:
1707
1708 >>> failure.example.want
1709 '2\n'
1710
1711 and the actual output:
1712
1713 >>> failure.got
1714 '1\n'
1715
1716 If a failure or error occurs, the globals are left intact:
1717
1718 >>> del test.globs['__builtins__']
1719 >>> test.globs
1720 {'x': 1}
1721
Edward Lopera1ef6112004-08-09 16:14:41 +00001722 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00001723 ... >>> x = 2
1724 ... >>> raise KeyError
1725 ... ''', {}, 'foo', 'foo.py', 0)
1726
1727 >>> runner.run(test)
1728 Traceback (most recent call last):
1729 ...
1730 UnexpectedException: <DocTest foo from foo.py:0 (2 examples)>
Tim Petersd1b78272004-08-07 06:03:09 +00001731
Tim Peters19397e52004-08-06 22:02:59 +00001732 >>> del test.globs['__builtins__']
1733 >>> test.globs
1734 {'x': 2}
1735
1736 But the globals are cleared if there is no error:
1737
Edward Lopera1ef6112004-08-09 16:14:41 +00001738 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00001739 ... >>> x = 2
1740 ... ''', {}, 'foo', 'foo.py', 0)
1741
1742 >>> runner.run(test)
1743 (0, 1)
1744
1745 >>> test.globs
1746 {}
1747
1748 """
1749
1750 def run(self, test, compileflags=None, out=None, clear_globs=True):
1751 r = DocTestRunner.run(self, test, compileflags, out, False)
1752 if clear_globs:
1753 test.globs.clear()
1754 return r
1755
1756 def report_unexpected_exception(self, out, test, example, exc_info):
1757 raise UnexpectedException(test, example, exc_info)
1758
1759 def report_failure(self, out, test, example, got):
1760 raise DocTestFailure(test, example, got)
1761
Tim Peters8485b562004-08-04 18:46:34 +00001762######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00001763## 6. Test Functions
Tim Peters8485b562004-08-04 18:46:34 +00001764######################################################################
1765# These should be backwards compatible.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001766
Martin v. Löwis4581cfa2002-11-22 08:23:09 +00001767def testmod(m=None, name=None, globs=None, verbose=None, isprivate=None,
Tim Peters19397e52004-08-06 22:02:59 +00001768 report=True, optionflags=0, extraglobs=None,
1769 raise_on_error=False):
Tim Peters6ebe61f2003-06-27 20:48:05 +00001770 """m=None, name=None, globs=None, verbose=None, isprivate=None,
Tim Peters8485b562004-08-04 18:46:34 +00001771 report=True, optionflags=0, extraglobs=None
Tim Peters8a7d2d52001-01-16 07:10:57 +00001772
Martin v. Löwis4581cfa2002-11-22 08:23:09 +00001773 Test examples in docstrings in functions and classes reachable
1774 from module m (or the current module if m is not supplied), starting
Raymond Hettinger71adf7e2003-07-16 19:25:22 +00001775 with m.__doc__. Unless isprivate is specified, private names
1776 are not skipped.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001777
1778 Also test examples reachable from dict m.__test__ if it exists and is
Tim Petersc2388a22004-08-10 01:41:28 +00001779 not None. m.__test__ maps names to functions, classes and strings;
Tim Peters8a7d2d52001-01-16 07:10:57 +00001780 function and class docstrings are tested even if the name is private;
1781 strings are tested directly, as if they were docstrings.
1782
1783 Return (#failures, #tests).
1784
1785 See doctest.__doc__ for an overview.
1786
1787 Optional keyword arg "name" gives the name of the module; by default
1788 use m.__name__.
1789
1790 Optional keyword arg "globs" gives a dict to be used as the globals
1791 when executing examples; by default, use m.__dict__. A copy of this
1792 dict is actually used for each docstring, so that each docstring's
1793 examples start with a clean slate.
1794
Tim Peters8485b562004-08-04 18:46:34 +00001795 Optional keyword arg "extraglobs" gives a dictionary that should be
1796 merged into the globals that are used to execute examples. By
1797 default, no extra globals are used. This is new in 2.4.
1798
Tim Peters8a7d2d52001-01-16 07:10:57 +00001799 Optional keyword arg "verbose" prints lots of stuff if true, prints
1800 only failures if false; by default, it's true iff "-v" is in sys.argv.
1801
Tim Peters8a7d2d52001-01-16 07:10:57 +00001802 Optional keyword arg "report" prints a summary at the end when true,
1803 else prints nothing at the end. In verbose mode, the summary is
1804 detailed, else very brief (in fact, empty if all tests passed).
1805
Tim Peters6ebe61f2003-06-27 20:48:05 +00001806 Optional keyword arg "optionflags" or's together module constants,
1807 and defaults to 0. This is new in 2.3. Possible values:
1808
1809 DONT_ACCEPT_TRUE_FOR_1
1810 By default, if an expected output block contains just "1",
1811 an actual output block containing just "True" is considered
1812 to be a match, and similarly for "0" versus "False". When
1813 DONT_ACCEPT_TRUE_FOR_1 is specified, neither substitution
1814 is allowed.
1815
Tim Peters8485b562004-08-04 18:46:34 +00001816 DONT_ACCEPT_BLANKLINE
1817 By default, if an expected output block contains a line
1818 containing only the string "<BLANKLINE>", then that line
1819 will match a blank line in the actual output. When
1820 DONT_ACCEPT_BLANKLINE is specified, this substitution is
1821 not allowed.
1822
1823 NORMALIZE_WHITESPACE
1824 When NORMALIZE_WHITESPACE is specified, all sequences of
1825 whitespace are treated as equal. I.e., any sequence of
1826 whitespace within the expected output will match any
1827 sequence of whitespace within the actual output.
1828
1829 ELLIPSIS
1830 When ELLIPSIS is specified, then an ellipsis marker
1831 ("...") in the expected output can match any substring in
1832 the actual output.
1833
1834 UNIFIED_DIFF
1835 When UNIFIED_DIFF is specified, failures that involve
1836 multi-line expected and actual outputs will be displayed
1837 using a unified diff.
1838
1839 CONTEXT_DIFF
1840 When CONTEXT_DIFF is specified, failures that involve
1841 multi-line expected and actual outputs will be displayed
1842 using a context diff.
Tim Peters19397e52004-08-06 22:02:59 +00001843
1844 Optional keyword arg "raise_on_error" raises an exception on the
1845 first unexpected exception or failure. This allows failures to be
1846 post-mortem debugged.
1847
Tim Petersf727c6c2004-08-08 01:48:59 +00001848 Deprecated in Python 2.4:
1849 Optional keyword arg "isprivate" specifies a function used to
1850 determine whether a name is private. The default function is
1851 treat all functions as public. Optionally, "isprivate" can be
1852 set to doctest.is_private to skip over functions marked as private
1853 using the underscore naming convention; see its docs for details.
Tim Peters8485b562004-08-04 18:46:34 +00001854 """
1855
1856 """ [XX] This is no longer true:
Tim Peters8a7d2d52001-01-16 07:10:57 +00001857 Advanced tomfoolery: testmod runs methods of a local instance of
1858 class doctest.Tester, then merges the results into (or creates)
1859 global Tester instance doctest.master. Methods of doctest.master
1860 can be called directly too, if you want to do something unusual.
1861 Passing report=0 to testmod is especially useful then, to delay
1862 displaying a summary. Invoke doctest.master.summarize(verbose)
1863 when you're done fiddling.
1864 """
Tim Petersf727c6c2004-08-08 01:48:59 +00001865 if isprivate is not None:
1866 warnings.warn("the isprivate argument is deprecated; "
1867 "examine DocTestFinder.find() lists instead",
1868 DeprecationWarning)
1869
Tim Peters8485b562004-08-04 18:46:34 +00001870 # If no module was given, then use __main__.
Martin v. Löwis4581cfa2002-11-22 08:23:09 +00001871 if m is None:
Martin v. Löwis4581cfa2002-11-22 08:23:09 +00001872 # DWA - m will still be None if this wasn't invoked from the command
1873 # line, in which case the following TypeError is about as good an error
1874 # as we should expect
1875 m = sys.modules.get('__main__')
1876
Tim Peters8485b562004-08-04 18:46:34 +00001877 # Check that we were actually given a module.
1878 if not inspect.ismodule(m):
Walter Dörwald70a6b492004-02-12 17:35:32 +00001879 raise TypeError("testmod: module required; %r" % (m,))
Tim Peters8485b562004-08-04 18:46:34 +00001880
1881 # If no name was given, then use the module's name.
Tim Peters8a7d2d52001-01-16 07:10:57 +00001882 if name is None:
1883 name = m.__name__
Tim Peters8485b562004-08-04 18:46:34 +00001884
1885 # Find, parse, and run all tests in the given module.
Tim Petersf727c6c2004-08-08 01:48:59 +00001886 finder = DocTestFinder(_namefilter=isprivate)
Tim Peters19397e52004-08-06 22:02:59 +00001887
1888 if raise_on_error:
1889 runner = DebugRunner(verbose=verbose, optionflags=optionflags)
1890 else:
1891 runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1892
Tim Peters8485b562004-08-04 18:46:34 +00001893 for test in finder.find(m, name, globs=globs, extraglobs=extraglobs):
1894 runner.run(test)
1895
Tim Peters8a7d2d52001-01-16 07:10:57 +00001896 if report:
Tim Peters8485b562004-08-04 18:46:34 +00001897 runner.summarize()
Tim Peters8a7d2d52001-01-16 07:10:57 +00001898
Tim Peters8485b562004-08-04 18:46:34 +00001899 return runner.failures, runner.tries
Tim Petersdb3756d2003-06-29 05:30:48 +00001900
Tim Peters8485b562004-08-04 18:46:34 +00001901def run_docstring_examples(f, globs, verbose=False, name="NoName",
1902 compileflags=None, optionflags=0):
1903 """
1904 Test examples in the given object's docstring (`f`), using `globs`
1905 as globals. Optional argument `name` is used in failure messages.
1906 If the optional argument `verbose` is true, then generate output
1907 even if there are no failures.
Tim Petersdb3756d2003-06-29 05:30:48 +00001908
Tim Peters8485b562004-08-04 18:46:34 +00001909 `compileflags` gives the set of flags that should be used by the
1910 Python compiler when running the examples. If not specified, then
1911 it will default to the set of future-import flags that apply to
1912 `globs`.
Tim Petersdb3756d2003-06-29 05:30:48 +00001913
Tim Peters8485b562004-08-04 18:46:34 +00001914 Optional keyword arg `optionflags` specifies options for the
1915 testing and output. See the documentation for `testmod` for more
1916 information.
1917 """
1918 # Find, parse, and run all tests in the given module.
1919 finder = DocTestFinder(verbose=verbose, recurse=False)
1920 runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1921 for test in finder.find(f, name, globs=globs):
1922 runner.run(test, compileflags=compileflags)
Tim Petersdb3756d2003-06-29 05:30:48 +00001923
Tim Peters8485b562004-08-04 18:46:34 +00001924######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00001925## 7. Tester
Tim Peters8485b562004-08-04 18:46:34 +00001926######################################################################
1927# This is provided only for backwards compatibility. It's not
1928# actually used in any way.
Tim Petersdb3756d2003-06-29 05:30:48 +00001929
Tim Peters8485b562004-08-04 18:46:34 +00001930class Tester:
1931 def __init__(self, mod=None, globs=None, verbose=None,
1932 isprivate=None, optionflags=0):
Tim Peters3ddd60a2004-08-08 02:43:33 +00001933
1934 warnings.warn("class Tester is deprecated; "
1935 "use class doctest.DocTestRunner instead",
1936 DeprecationWarning, stacklevel=2)
Tim Peters8485b562004-08-04 18:46:34 +00001937 if mod is None and globs is None:
1938 raise TypeError("Tester.__init__: must specify mod or globs")
1939 if mod is not None and not _ismodule(mod):
1940 raise TypeError("Tester.__init__: mod must be a module; %r" %
1941 (mod,))
1942 if globs is None:
1943 globs = mod.__dict__
1944 self.globs = globs
Tim Petersdb3756d2003-06-29 05:30:48 +00001945
Tim Peters8485b562004-08-04 18:46:34 +00001946 self.verbose = verbose
1947 self.isprivate = isprivate
1948 self.optionflags = optionflags
Tim Petersf727c6c2004-08-08 01:48:59 +00001949 self.testfinder = DocTestFinder(_namefilter=isprivate)
Tim Peters8485b562004-08-04 18:46:34 +00001950 self.testrunner = DocTestRunner(verbose=verbose,
1951 optionflags=optionflags)
Tim Petersdb3756d2003-06-29 05:30:48 +00001952
Tim Peters8485b562004-08-04 18:46:34 +00001953 def runstring(self, s, name):
Edward Lopera1ef6112004-08-09 16:14:41 +00001954 test = DocTestParser().get_doctest(s, self.globs, name, None, None)
Tim Peters8485b562004-08-04 18:46:34 +00001955 if self.verbose:
1956 print "Running string", name
1957 (f,t) = self.testrunner.run(test)
1958 if self.verbose:
1959 print f, "of", t, "examples failed in string", name
1960 return (f,t)
Tim Petersdb3756d2003-06-29 05:30:48 +00001961
Tim Petersf3f57472004-08-08 06:11:48 +00001962 def rundoc(self, object, name=None, module=None):
Tim Peters8485b562004-08-04 18:46:34 +00001963 f = t = 0
1964 tests = self.testfinder.find(object, name, module=module,
Tim Petersf3f57472004-08-08 06:11:48 +00001965 globs=self.globs)
Tim Peters8485b562004-08-04 18:46:34 +00001966 for test in tests:
1967 (f2, t2) = self.testrunner.run(test)
1968 (f,t) = (f+f2, t+t2)
1969 return (f,t)
Tim Petersdb3756d2003-06-29 05:30:48 +00001970
Tim Peters8485b562004-08-04 18:46:34 +00001971 def rundict(self, d, name, module=None):
1972 import new
1973 m = new.module(name)
1974 m.__dict__.update(d)
Tim Petersf3f57472004-08-08 06:11:48 +00001975 if module is None:
1976 module = False
1977 return self.rundoc(m, name, module)
Tim Petersdb3756d2003-06-29 05:30:48 +00001978
Tim Peters8485b562004-08-04 18:46:34 +00001979 def run__test__(self, d, name):
1980 import new
1981 m = new.module(name)
1982 m.__test__ = d
1983 return self.rundoc(m, name, module)
Tim Petersdb3756d2003-06-29 05:30:48 +00001984
Tim Peters8485b562004-08-04 18:46:34 +00001985 def summarize(self, verbose=None):
1986 return self.testrunner.summarize(verbose)
Tim Petersdb3756d2003-06-29 05:30:48 +00001987
Tim Peters8485b562004-08-04 18:46:34 +00001988 def merge(self, other):
1989 d = self.testrunner._name2ft
1990 for name, (f, t) in other.testrunner._name2ft.items():
1991 if name in d:
1992 print "*** Tester.merge: '" + name + "' in both" \
1993 " testers; summing outcomes."
1994 f2, t2 = d[name]
1995 f = f + f2
1996 t = t + t2
1997 d[name] = f, t
Tim Petersdb3756d2003-06-29 05:30:48 +00001998
Tim Peters8485b562004-08-04 18:46:34 +00001999######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00002000## 8. Unittest Support
Tim Peters8485b562004-08-04 18:46:34 +00002001######################################################################
Tim Petersdb3756d2003-06-29 05:30:48 +00002002
Tim Peters19397e52004-08-06 22:02:59 +00002003class DocTestCase(unittest.TestCase):
Tim Petersdb3756d2003-06-29 05:30:48 +00002004
Edward Loper34fcb142004-08-09 02:45:41 +00002005 def __init__(self, test, optionflags=0, setUp=None, tearDown=None,
2006 checker=None):
Jim Fulton07a349c2004-08-22 14:10:00 +00002007
Jim Fultona643b652004-07-14 19:06:50 +00002008 unittest.TestCase.__init__(self)
Tim Peters19397e52004-08-06 22:02:59 +00002009 self._dt_optionflags = optionflags
Edward Loper34fcb142004-08-09 02:45:41 +00002010 self._dt_checker = checker
Tim Peters19397e52004-08-06 22:02:59 +00002011 self._dt_test = test
2012 self._dt_setUp = setUp
2013 self._dt_tearDown = tearDown
Tim Petersdb3756d2003-06-29 05:30:48 +00002014
Jim Fultona643b652004-07-14 19:06:50 +00002015 def setUp(self):
Tim Peters19397e52004-08-06 22:02:59 +00002016 if self._dt_setUp is not None:
2017 self._dt_setUp()
Jim Fultona643b652004-07-14 19:06:50 +00002018
2019 def tearDown(self):
Tim Peters19397e52004-08-06 22:02:59 +00002020 if self._dt_tearDown is not None:
2021 self._dt_tearDown()
Jim Fultona643b652004-07-14 19:06:50 +00002022
2023 def runTest(self):
Tim Peters19397e52004-08-06 22:02:59 +00002024 test = self._dt_test
Jim Fultona643b652004-07-14 19:06:50 +00002025 old = sys.stdout
2026 new = StringIO()
Edward Loper34fcb142004-08-09 02:45:41 +00002027 runner = DocTestRunner(optionflags=self._dt_optionflags,
2028 checker=self._dt_checker, verbose=False)
Tim Peters19397e52004-08-06 22:02:59 +00002029
Jim Fultona643b652004-07-14 19:06:50 +00002030 try:
Tim Peters19397e52004-08-06 22:02:59 +00002031 runner.DIVIDER = "-"*70
2032 failures, tries = runner.run(test, out=new.write)
Jim Fultona643b652004-07-14 19:06:50 +00002033 finally:
2034 sys.stdout = old
2035
2036 if failures:
Tim Peters19397e52004-08-06 22:02:59 +00002037 raise self.failureException(self.format_failure(new.getvalue()))
Tim Peters8485b562004-08-04 18:46:34 +00002038
Tim Peters19397e52004-08-06 22:02:59 +00002039 def format_failure(self, err):
2040 test = self._dt_test
2041 if test.lineno is None:
2042 lineno = 'unknown line number'
2043 else:
Jim Fulton07a349c2004-08-22 14:10:00 +00002044 lineno = '%s' % test.lineno
Tim Peters19397e52004-08-06 22:02:59 +00002045 lname = '.'.join(test.name.split('.')[-1:])
2046 return ('Failed doctest test for %s\n'
2047 ' File "%s", line %s, in %s\n\n%s'
2048 % (test.name, test.filename, lineno, lname, err)
2049 )
2050
2051 def debug(self):
2052 r"""Run the test case without results and without catching exceptions
2053
2054 The unit test framework includes a debug method on test cases
2055 and test suites to support post-mortem debugging. The test code
2056 is run in such a way that errors are not caught. This way a
2057 caller can catch the errors and initiate post-mortem debugging.
2058
2059 The DocTestCase provides a debug method that raises
2060 UnexpectedException errors if there is an unexepcted
2061 exception:
2062
Edward Lopera1ef6112004-08-09 16:14:41 +00002063 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
Tim Peters19397e52004-08-06 22:02:59 +00002064 ... {}, 'foo', 'foo.py', 0)
2065 >>> case = DocTestCase(test)
2066 >>> try:
2067 ... case.debug()
2068 ... except UnexpectedException, failure:
2069 ... pass
2070
2071 The UnexpectedException contains the test, the example, and
2072 the original exception:
2073
2074 >>> failure.test is test
2075 True
2076
2077 >>> failure.example.want
2078 '42\n'
2079
2080 >>> exc_info = failure.exc_info
2081 >>> raise exc_info[0], exc_info[1], exc_info[2]
2082 Traceback (most recent call last):
2083 ...
2084 KeyError
2085
2086 If the output doesn't match, then a DocTestFailure is raised:
2087
Edward Lopera1ef6112004-08-09 16:14:41 +00002088 >>> test = DocTestParser().get_doctest('''
Tim Peters19397e52004-08-06 22:02:59 +00002089 ... >>> x = 1
2090 ... >>> x
2091 ... 2
2092 ... ''', {}, 'foo', 'foo.py', 0)
2093 >>> case = DocTestCase(test)
2094
2095 >>> try:
2096 ... case.debug()
2097 ... except DocTestFailure, failure:
2098 ... pass
2099
2100 DocTestFailure objects provide access to the test:
2101
2102 >>> failure.test is test
2103 True
2104
2105 As well as to the example:
2106
2107 >>> failure.example.want
2108 '2\n'
2109
2110 and the actual output:
2111
2112 >>> failure.got
2113 '1\n'
2114
2115 """
2116
Edward Loper34fcb142004-08-09 02:45:41 +00002117 runner = DebugRunner(optionflags=self._dt_optionflags,
2118 checker=self._dt_checker, verbose=False)
Edward Loper3a3817f2004-08-19 19:26:06 +00002119 runner.run(self._dt_test)
Jim Fultona643b652004-07-14 19:06:50 +00002120
2121 def id(self):
Tim Peters19397e52004-08-06 22:02:59 +00002122 return self._dt_test.name
Jim Fultona643b652004-07-14 19:06:50 +00002123
2124 def __repr__(self):
Tim Peters19397e52004-08-06 22:02:59 +00002125 name = self._dt_test.name.split('.')
Jim Fultona643b652004-07-14 19:06:50 +00002126 return "%s (%s)" % (name[-1], '.'.join(name[:-1]))
2127
2128 __str__ = __repr__
2129
2130 def shortDescription(self):
Tim Peters19397e52004-08-06 22:02:59 +00002131 return "Doctest: " + self._dt_test.name
Jim Fultona643b652004-07-14 19:06:50 +00002132
Tim Peters19397e52004-08-06 22:02:59 +00002133def DocTestSuite(module=None, globs=None, extraglobs=None,
2134 optionflags=0, test_finder=None,
Edward Loper34fcb142004-08-09 02:45:41 +00002135 setUp=lambda: None, tearDown=lambda: None,
2136 checker=None):
Tim Peters8485b562004-08-04 18:46:34 +00002137 """
Tim Peters19397e52004-08-06 22:02:59 +00002138 Convert doctest tests for a mudule to a unittest test suite.
Jim Fultona643b652004-07-14 19:06:50 +00002139
Tim Peters19397e52004-08-06 22:02:59 +00002140 This converts each documentation string in a module that
2141 contains doctest tests to a unittest test case. If any of the
2142 tests in a doc string fail, then the test case fails. An exception
2143 is raised showing the name of the file containing the test and a
Jim Fultona643b652004-07-14 19:06:50 +00002144 (sometimes approximate) line number.
2145
Tim Peters19397e52004-08-06 22:02:59 +00002146 The `module` argument provides the module to be tested. The argument
Jim Fultona643b652004-07-14 19:06:50 +00002147 can be either a module or a module name.
2148
2149 If no argument is given, the calling module is used.
Jim Fultona643b652004-07-14 19:06:50 +00002150 """
Jim Fultona643b652004-07-14 19:06:50 +00002151
Tim Peters8485b562004-08-04 18:46:34 +00002152 if test_finder is None:
2153 test_finder = DocTestFinder()
Tim Peters8485b562004-08-04 18:46:34 +00002154
Tim Peters19397e52004-08-06 22:02:59 +00002155 module = _normalize_module(module)
2156 tests = test_finder.find(module, globs=globs, extraglobs=extraglobs)
2157 if globs is None:
2158 globs = module.__dict__
2159 if not tests: # [XX] why do we want to do this?
2160 raise ValueError(module, "has no tests")
Tim Petersdb3756d2003-06-29 05:30:48 +00002161
2162 tests.sort()
2163 suite = unittest.TestSuite()
Tim Peters8485b562004-08-04 18:46:34 +00002164 for test in tests:
Tim Peters19397e52004-08-06 22:02:59 +00002165 if len(test.examples) == 0:
2166 continue
Tim Peters8485b562004-08-04 18:46:34 +00002167 if not test.filename:
Tim Petersdb3756d2003-06-29 05:30:48 +00002168 filename = module.__file__
Jim Fulton07a349c2004-08-22 14:10:00 +00002169 if filename[-4:] in (".pyc", ".pyo"):
Tim Petersdb3756d2003-06-29 05:30:48 +00002170 filename = filename[:-1]
Tim Peters8485b562004-08-04 18:46:34 +00002171 test.filename = filename
Edward Loper34fcb142004-08-09 02:45:41 +00002172 suite.addTest(DocTestCase(test, optionflags, setUp, tearDown,
2173 checker))
Tim Peters19397e52004-08-06 22:02:59 +00002174
2175 return suite
2176
2177class DocFileCase(DocTestCase):
2178
2179 def id(self):
2180 return '_'.join(self._dt_test.name.split('.'))
2181
2182 def __repr__(self):
2183 return self._dt_test.filename
2184 __str__ = __repr__
2185
2186 def format_failure(self, err):
2187 return ('Failed doctest test for %s\n File "%s", line 0\n\n%s'
2188 % (self._dt_test.name, self._dt_test.filename, err)
2189 )
2190
2191def DocFileTest(path, package=None, globs=None,
2192 setUp=None, tearDown=None,
2193 optionflags=0):
2194 package = _normalize_module(package)
2195 name = path.split('/')[-1]
2196 dir = os.path.split(package.__file__)[0]
2197 path = os.path.join(dir, *(path.split('/')))
2198 doc = open(path).read()
2199
2200 if globs is None:
2201 globs = {}
2202
Edward Lopera1ef6112004-08-09 16:14:41 +00002203 test = DocTestParser().get_doctest(doc, globs, name, path, 0)
Tim Peters19397e52004-08-06 22:02:59 +00002204
2205 return DocFileCase(test, optionflags, setUp, tearDown)
2206
2207def DocFileSuite(*paths, **kw):
2208 """Creates a suite of doctest files.
2209
2210 One or more text file paths are given as strings. These should
2211 use "/" characters to separate path segments. Paths are relative
2212 to the directory of the calling module, or relative to the package
2213 passed as a keyword argument.
2214
2215 A number of options may be provided as keyword arguments:
2216
2217 package
2218 The name of a Python package. Text-file paths will be
2219 interpreted relative to the directory containing this package.
2220 The package may be supplied as a package object or as a dotted
2221 package name.
2222
2223 setUp
2224 The name of a set-up function. This is called before running the
2225 tests in each file.
2226
2227 tearDown
2228 The name of a tear-down function. This is called after running the
2229 tests in each file.
2230
2231 globs
2232 A dictionary containing initial global variables for the tests.
2233 """
2234 suite = unittest.TestSuite()
2235
2236 # We do this here so that _normalize_module is called at the right
2237 # level. If it were called in DocFileTest, then this function
2238 # would be the caller and we might guess the package incorrectly.
2239 kw['package'] = _normalize_module(kw.get('package'))
2240
2241 for path in paths:
2242 suite.addTest(DocFileTest(path, **kw))
Jim Fultona643b652004-07-14 19:06:50 +00002243
Tim Petersdb3756d2003-06-29 05:30:48 +00002244 return suite
2245
Tim Peters8485b562004-08-04 18:46:34 +00002246######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00002247## 9. Debugging Support
Tim Peters8485b562004-08-04 18:46:34 +00002248######################################################################
Jim Fultona643b652004-07-14 19:06:50 +00002249
Tim Peters19397e52004-08-06 22:02:59 +00002250def script_from_examples(s):
2251 r"""Extract script from text with examples.
2252
2253 Converts text with examples to a Python script. Example input is
2254 converted to regular code. Example output and all other words
2255 are converted to comments:
2256
2257 >>> text = '''
2258 ... Here are examples of simple math.
2259 ...
2260 ... Python has super accurate integer addition
2261 ...
2262 ... >>> 2 + 2
2263 ... 5
2264 ...
2265 ... And very friendly error messages:
2266 ...
2267 ... >>> 1/0
2268 ... To Infinity
2269 ... And
2270 ... Beyond
2271 ...
2272 ... You can use logic if you want:
2273 ...
2274 ... >>> if 0:
2275 ... ... blah
2276 ... ... blah
2277 ... ...
2278 ...
2279 ... Ho hum
2280 ... '''
2281
2282 >>> print script_from_examples(text)
Edward Lopera5db6002004-08-12 02:41:30 +00002283 # Here are examples of simple math.
Tim Peters19397e52004-08-06 22:02:59 +00002284 #
Edward Lopera5db6002004-08-12 02:41:30 +00002285 # Python has super accurate integer addition
Tim Peters19397e52004-08-06 22:02:59 +00002286 #
2287 2 + 2
2288 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +00002289 ## 5
Tim Peters19397e52004-08-06 22:02:59 +00002290 #
Edward Lopera5db6002004-08-12 02:41:30 +00002291 # And very friendly error messages:
Tim Peters19397e52004-08-06 22:02:59 +00002292 #
2293 1/0
2294 # Expected:
Edward Lopera5db6002004-08-12 02:41:30 +00002295 ## To Infinity
2296 ## And
2297 ## Beyond
Tim Peters19397e52004-08-06 22:02:59 +00002298 #
Edward Lopera5db6002004-08-12 02:41:30 +00002299 # You can use logic if you want:
Tim Peters19397e52004-08-06 22:02:59 +00002300 #
2301 if 0:
2302 blah
2303 blah
2304 <BLANKLINE>
2305 #
Edward Lopera5db6002004-08-12 02:41:30 +00002306 # Ho hum
Tim Peters19397e52004-08-06 22:02:59 +00002307 """
2308
Edward Lopera1ef6112004-08-09 16:14:41 +00002309 return DocTestParser().get_program(s)
Tim Peters19397e52004-08-06 22:02:59 +00002310
Tim Peters8485b562004-08-04 18:46:34 +00002311def _want_comment(example):
2312 """
Tim Peters19397e52004-08-06 22:02:59 +00002313 Return a comment containing the expected output for the given example.
Tim Peters8485b562004-08-04 18:46:34 +00002314 """
Jim Fultona643b652004-07-14 19:06:50 +00002315 # Return the expected output, if any
Tim Peters8485b562004-08-04 18:46:34 +00002316 want = example.want
2317 if want:
Tim Peters19397e52004-08-06 22:02:59 +00002318 if want[-1] == '\n':
2319 want = want[:-1]
Tim Peters8485b562004-08-04 18:46:34 +00002320 want = "\n# ".join(want.split("\n"))
2321 want = "\n# Expected:\n# %s" % want
2322 return want
Tim Petersdb3756d2003-06-29 05:30:48 +00002323
2324def testsource(module, name):
Tim Peters19397e52004-08-06 22:02:59 +00002325 """Extract the test sources from a doctest docstring as a script.
Tim Petersdb3756d2003-06-29 05:30:48 +00002326
2327 Provide the module (or dotted name of the module) containing the
Jim Fultona643b652004-07-14 19:06:50 +00002328 test to be debugged and the name (within the module) of the object
2329 with the doc string with tests to be debugged.
Tim Petersdb3756d2003-06-29 05:30:48 +00002330 """
Tim Peters8485b562004-08-04 18:46:34 +00002331 module = _normalize_module(module)
2332 tests = DocTestFinder().find(module)
2333 test = [t for t in tests if t.name == name]
Tim Petersdb3756d2003-06-29 05:30:48 +00002334 if not test:
2335 raise ValueError(name, "not found in tests")
2336 test = test[0]
Tim Peters19397e52004-08-06 22:02:59 +00002337 testsrc = script_from_examples(test.docstring)
Jim Fultona643b652004-07-14 19:06:50 +00002338 return testsrc
Tim Petersdb3756d2003-06-29 05:30:48 +00002339
Jim Fultona643b652004-07-14 19:06:50 +00002340def debug_src(src, pm=False, globs=None):
Tim Peters19397e52004-08-06 22:02:59 +00002341 """Debug a single doctest docstring, in argument `src`'"""
2342 testsrc = script_from_examples(src)
Tim Peters8485b562004-08-04 18:46:34 +00002343 debug_script(testsrc, pm, globs)
Tim Petersdb3756d2003-06-29 05:30:48 +00002344
Jim Fultona643b652004-07-14 19:06:50 +00002345def debug_script(src, pm=False, globs=None):
Tim Peters19397e52004-08-06 22:02:59 +00002346 "Debug a test script. `src` is the script, as a string."
Tim Petersdb3756d2003-06-29 05:30:48 +00002347 import pdb
Tim Petersdb3756d2003-06-29 05:30:48 +00002348
Tim Petersdb3756d2003-06-29 05:30:48 +00002349 srcfilename = tempfile.mktemp("doctestdebug.py")
Tim Peters8485b562004-08-04 18:46:34 +00002350 f = open(srcfilename, 'w')
2351 f.write(src)
2352 f.close()
2353
Jim Fultona643b652004-07-14 19:06:50 +00002354 if globs:
2355 globs = globs.copy()
2356 else:
2357 globs = {}
Tim Petersdb3756d2003-06-29 05:30:48 +00002358
Tim Peters8485b562004-08-04 18:46:34 +00002359 if pm:
2360 try:
2361 execfile(srcfilename, globs, globs)
2362 except:
2363 print sys.exc_info()[1]
2364 pdb.post_mortem(sys.exc_info()[2])
2365 else:
2366 # Note that %r is vital here. '%s' instead can, e.g., cause
2367 # backslashes to get treated as metacharacters on Windows.
2368 pdb.run("execfile(%r)" % srcfilename, globs, globs)
Tim Petersdb3756d2003-06-29 05:30:48 +00002369
Jim Fultona643b652004-07-14 19:06:50 +00002370def debug(module, name, pm=False):
Tim Peters19397e52004-08-06 22:02:59 +00002371 """Debug a single doctest docstring.
Jim Fultona643b652004-07-14 19:06:50 +00002372
2373 Provide the module (or dotted name of the module) containing the
2374 test to be debugged and the name (within the module) of the object
Tim Peters19397e52004-08-06 22:02:59 +00002375 with the docstring with tests to be debugged.
Jim Fultona643b652004-07-14 19:06:50 +00002376 """
Tim Peters8485b562004-08-04 18:46:34 +00002377 module = _normalize_module(module)
Jim Fultona643b652004-07-14 19:06:50 +00002378 testsrc = testsource(module, name)
2379 debug_script(testsrc, pm, module.__dict__)
2380
Tim Peters8485b562004-08-04 18:46:34 +00002381######################################################################
Edward Loper7c748462004-08-09 02:06:06 +00002382## 10. Example Usage
Tim Peters8485b562004-08-04 18:46:34 +00002383######################################################################
Tim Peters8a7d2d52001-01-16 07:10:57 +00002384class _TestClass:
2385 """
2386 A pointless class, for sanity-checking of docstring testing.
2387
2388 Methods:
2389 square()
2390 get()
2391
2392 >>> _TestClass(13).get() + _TestClass(-12).get()
2393 1
2394 >>> hex(_TestClass(13).square().get())
2395 '0xa9'
2396 """
2397
2398 def __init__(self, val):
2399 """val -> _TestClass object with associated value val.
2400
2401 >>> t = _TestClass(123)
2402 >>> print t.get()
2403 123
2404 """
2405
2406 self.val = val
2407
2408 def square(self):
2409 """square() -> square TestClass's associated value
2410
2411 >>> _TestClass(13).square().get()
2412 169
2413 """
2414
2415 self.val = self.val ** 2
2416 return self
2417
2418 def get(self):
2419 """get() -> return TestClass's associated value.
2420
2421 >>> x = _TestClass(-42)
2422 >>> print x.get()
2423 -42
2424 """
2425
2426 return self.val
2427
2428__test__ = {"_TestClass": _TestClass,
2429 "string": r"""
2430 Example of a string object, searched as-is.
2431 >>> x = 1; y = 2
2432 >>> x + y, x * y
2433 (3, 2)
Tim Peters6ebe61f2003-06-27 20:48:05 +00002434 """,
2435 "bool-int equivalence": r"""
2436 In 2.2, boolean expressions displayed
2437 0 or 1. By default, we still accept
2438 them. This can be disabled by passing
2439 DONT_ACCEPT_TRUE_FOR_1 to the new
2440 optionflags argument.
2441 >>> 4 == 4
2442 1
2443 >>> 4 == 4
2444 True
2445 >>> 4 > 4
2446 0
2447 >>> 4 > 4
2448 False
2449 """,
Tim Peters8485b562004-08-04 18:46:34 +00002450 "blank lines": r"""
2451 Blank lines can be marked with <BLANKLINE>:
2452 >>> print 'foo\n\nbar\n'
2453 foo
2454 <BLANKLINE>
2455 bar
2456 <BLANKLINE>
2457 """,
2458 }
2459# "ellipsis": r"""
2460# If the ellipsis flag is used, then '...' can be used to
2461# elide substrings in the desired output:
2462# >>> print range(1000)
2463# [0, 1, 2, ..., 999]
2464# """,
2465# "whitespace normalization": r"""
2466# If the whitespace normalization flag is used, then
2467# differences in whitespace are ignored.
2468# >>> print range(30)
2469# [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
2470# 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,
2471# 27, 28, 29]
2472# """,
2473# }
2474
2475def test1(): r"""
Tim Peters3ddd60a2004-08-08 02:43:33 +00002476>>> warnings.filterwarnings("ignore", "class Tester", DeprecationWarning,
2477... "doctest", 0)
Tim Peters8485b562004-08-04 18:46:34 +00002478>>> from doctest import Tester
2479>>> t = Tester(globs={'x': 42}, verbose=0)
2480>>> t.runstring(r'''
2481... >>> x = x * 2
2482... >>> print x
2483... 42
2484... ''', 'XYZ')
2485**********************************************************************
Jim Fulton07a349c2004-08-22 14:10:00 +00002486Line 3, in XYZ
2487Failed example:
2488 print x
2489Expected:
2490 42
2491Got:
2492 84
Tim Peters8485b562004-08-04 18:46:34 +00002493(1, 2)
2494>>> t.runstring(">>> x = x * 2\n>>> print x\n84\n", 'example2')
2495(0, 2)
2496>>> t.summarize()
2497**********************************************************************
24981 items had failures:
2499 1 of 2 in XYZ
2500***Test Failed*** 1 failures.
2501(1, 4)
2502>>> t.summarize(verbose=1)
25031 items passed all tests:
2504 2 tests in example2
2505**********************************************************************
25061 items had failures:
2507 1 of 2 in XYZ
25084 tests in 2 items.
25093 passed and 1 failed.
2510***Test Failed*** 1 failures.
2511(1, 4)
2512"""
2513
2514def test2(): r"""
Tim Peters3ddd60a2004-08-08 02:43:33 +00002515 >>> warnings.filterwarnings("ignore", "class Tester",
2516 ... DeprecationWarning, "doctest", 0)
Tim Peters8485b562004-08-04 18:46:34 +00002517 >>> t = Tester(globs={}, verbose=1)
2518 >>> test = r'''
2519 ... # just an example
2520 ... >>> x = 1 + 2
2521 ... >>> x
2522 ... 3
2523 ... '''
2524 >>> t.runstring(test, "Example")
2525 Running string Example
2526 Trying: x = 1 + 2
2527 Expecting: nothing
2528 ok
2529 Trying: x
2530 Expecting: 3
2531 ok
2532 0 of 2 examples failed in string Example
2533 (0, 2)
2534"""
2535def test3(): r"""
Tim Peters3ddd60a2004-08-08 02:43:33 +00002536 >>> warnings.filterwarnings("ignore", "class Tester",
2537 ... DeprecationWarning, "doctest", 0)
Tim Peters8485b562004-08-04 18:46:34 +00002538 >>> t = Tester(globs={}, verbose=0)
2539 >>> def _f():
2540 ... '''Trivial docstring example.
2541 ... >>> assert 2 == 2
2542 ... '''
2543 ... return 32
2544 ...
2545 >>> t.rundoc(_f) # expect 0 failures in 1 example
2546 (0, 1)
2547"""
2548def test4(): """
2549 >>> import new
2550 >>> m1 = new.module('_m1')
2551 >>> m2 = new.module('_m2')
2552 >>> test_data = \"""
2553 ... def _f():
2554 ... '''>>> assert 1 == 1
2555 ... '''
2556 ... def g():
2557 ... '''>>> assert 2 != 1
2558 ... '''
2559 ... class H:
2560 ... '''>>> assert 2 > 1
2561 ... '''
2562 ... def bar(self):
2563 ... '''>>> assert 1 < 2
2564 ... '''
2565 ... \"""
2566 >>> exec test_data in m1.__dict__
2567 >>> exec test_data in m2.__dict__
2568 >>> m1.__dict__.update({"f2": m2._f, "g2": m2.g, "h2": m2.H})
2569
2570 Tests that objects outside m1 are excluded:
2571
Tim Peters3ddd60a2004-08-08 02:43:33 +00002572 >>> warnings.filterwarnings("ignore", "class Tester",
2573 ... DeprecationWarning, "doctest", 0)
Tim Peters8485b562004-08-04 18:46:34 +00002574 >>> t = Tester(globs={}, verbose=0)
Tim Petersf727c6c2004-08-08 01:48:59 +00002575 >>> t.rundict(m1.__dict__, "rundict_test", m1) # f2 and g2 and h2 skipped
Tim Peters8485b562004-08-04 18:46:34 +00002576 (0, 4)
2577
Tim Petersf727c6c2004-08-08 01:48:59 +00002578 Once more, not excluding stuff outside m1:
Tim Peters8485b562004-08-04 18:46:34 +00002579
2580 >>> t = Tester(globs={}, verbose=0)
2581 >>> t.rundict(m1.__dict__, "rundict_test_pvt") # None are skipped.
2582 (0, 8)
2583
2584 The exclusion of objects from outside the designated module is
2585 meant to be invoked automagically by testmod.
2586
Tim Petersf727c6c2004-08-08 01:48:59 +00002587 >>> testmod(m1, verbose=False)
2588 (0, 4)
Tim Peters8485b562004-08-04 18:46:34 +00002589"""
Tim Peters8a7d2d52001-01-16 07:10:57 +00002590
2591def _test():
Tim Peters8485b562004-08-04 18:46:34 +00002592 #import doctest
2593 #doctest.testmod(doctest, verbose=False,
2594 # optionflags=ELLIPSIS | NORMALIZE_WHITESPACE |
2595 # UNIFIED_DIFF)
2596 #print '~'*70
2597 r = unittest.TextTestRunner()
2598 r.run(DocTestSuite())
Tim Peters8a7d2d52001-01-16 07:10:57 +00002599
2600if __name__ == "__main__":
2601 _test()