root / env / lib / python2.7 / site-packages / distribute-0.6.19-py2.7.egg / setuptools / tests / doctest.py @ 1a305335
History | View | Annotate | Download (97.4 KB)
1 | 1a305335 | officers | # Module doctest.
|
---|---|---|---|
2 | # Released to the public domain 16-Jan-2001, by Tim Peters (tim@python.org).
|
||
3 | # Major enhancements and refactoring by:
|
||
4 | # Jim Fulton
|
||
5 | # Edward Loper
|
||
6 | |||
7 | # Provided as-is; use at your own risk; no warranty; no promises; enjoy!
|
||
8 | |||
9 | try:
|
||
10 | basestring
|
||
11 | except NameError: |
||
12 | basestring = str,unicode |
||
13 | |||
14 | try:
|
||
15 | enumerate
|
||
16 | except NameError: |
||
17 | def enumerate(seq): |
||
18 | return zip(range(len(seq)),seq) |
||
19 | |||
20 | r"""Module doctest -- a framework for running examples in docstrings.
|
||
21 |
|
||
22 | In simplest use, end each module M to be tested with:
|
||
23 |
|
||
24 | def _test():
|
||
25 | import doctest
|
||
26 | doctest.testmod()
|
||
27 |
|
||
28 | if __name__ == "__main__":
|
||
29 | _test()
|
||
30 |
|
||
31 | Then running the module as a script will cause the examples in the
|
||
32 | docstrings to get executed and verified:
|
||
33 |
|
||
34 | python M.py
|
||
35 |
|
||
36 | This won't display anything unless an example fails, in which case the
|
||
37 | failing example(s) and the cause(s) of the failure(s) are printed to stdout
|
||
38 | (why not stderr? because stderr is a lame hack <0.2 wink>), and the final
|
||
39 | line of output is "Test failed.".
|
||
40 |
|
||
41 | Run it with the -v switch instead:
|
||
42 |
|
||
43 | python M.py -v
|
||
44 |
|
||
45 | and a detailed report of all examples tried is printed to stdout, along
|
||
46 | with assorted summaries at the end.
|
||
47 |
|
||
48 | You can force verbose mode by passing "verbose=True" to testmod, or prohibit
|
||
49 | it by passing "verbose=False". In either of those cases, sys.argv is not
|
||
50 | examined by testmod.
|
||
51 |
|
||
52 | There are a variety of other ways to run doctests, including integration
|
||
53 | with the unittest framework, and support for running non-Python text
|
||
54 | files containing doctests. There are also many ways to override parts
|
||
55 | of doctest's default behaviors. See the Library Reference Manual for
|
||
56 | details.
|
||
57 | """
|
||
58 | |||
59 | __docformat__ = 'reStructuredText en'
|
||
60 | |||
61 | __all__ = [ |
||
62 | # 0, Option Flags
|
||
63 | 'register_optionflag',
|
||
64 | 'DONT_ACCEPT_TRUE_FOR_1',
|
||
65 | 'DONT_ACCEPT_BLANKLINE',
|
||
66 | 'NORMALIZE_WHITESPACE',
|
||
67 | 'ELLIPSIS',
|
||
68 | 'IGNORE_EXCEPTION_DETAIL',
|
||
69 | 'COMPARISON_FLAGS',
|
||
70 | 'REPORT_UDIFF',
|
||
71 | 'REPORT_CDIFF',
|
||
72 | 'REPORT_NDIFF',
|
||
73 | 'REPORT_ONLY_FIRST_FAILURE',
|
||
74 | 'REPORTING_FLAGS',
|
||
75 | # 1. Utility Functions
|
||
76 | 'is_private',
|
||
77 | # 2. Example & DocTest
|
||
78 | 'Example',
|
||
79 | 'DocTest',
|
||
80 | # 3. Doctest Parser
|
||
81 | 'DocTestParser',
|
||
82 | # 4. Doctest Finder
|
||
83 | 'DocTestFinder',
|
||
84 | # 5. Doctest Runner
|
||
85 | 'DocTestRunner',
|
||
86 | 'OutputChecker',
|
||
87 | 'DocTestFailure',
|
||
88 | 'UnexpectedException',
|
||
89 | 'DebugRunner',
|
||
90 | # 6. Test Functions
|
||
91 | 'testmod',
|
||
92 | 'testfile',
|
||
93 | 'run_docstring_examples',
|
||
94 | # 7. Tester
|
||
95 | 'Tester',
|
||
96 | # 8. Unittest Support
|
||
97 | 'DocTestSuite',
|
||
98 | 'DocFileSuite',
|
||
99 | 'set_unittest_reportflags',
|
||
100 | # 9. Debugging Support
|
||
101 | 'script_from_examples',
|
||
102 | 'testsource',
|
||
103 | 'debug_src',
|
||
104 | 'debug',
|
||
105 | ] |
||
106 | |||
107 | import __future__ |
||
108 | |||
109 | import sys, traceback, inspect, linecache, os, re, types |
||
110 | import unittest, difflib, pdb, tempfile |
||
111 | import warnings |
||
112 | from StringIO import StringIO |
||
113 | |||
114 | # Don't whine about the deprecated is_private function in this
|
||
115 | # module's tests.
|
||
116 | warnings.filterwarnings("ignore", "is_private", DeprecationWarning, |
||
117 | __name__, 0)
|
||
118 | |||
119 | # There are 4 basic classes:
|
||
120 | # - Example: a <source, want> pair, plus an intra-docstring line number.
|
||
121 | # - DocTest: a collection of examples, parsed from a docstring, plus
|
||
122 | # info about where the docstring came from (name, filename, lineno).
|
||
123 | # - DocTestFinder: extracts DocTests from a given object's docstring and
|
||
124 | # its contained objects' docstrings.
|
||
125 | # - DocTestRunner: runs DocTest cases, and accumulates statistics.
|
||
126 | #
|
||
127 | # So the basic picture is:
|
||
128 | #
|
||
129 | # list of:
|
||
130 | # +------+ +---------+ +-------+
|
||
131 | # |object| --DocTestFinder-> | DocTest | --DocTestRunner-> |results|
|
||
132 | # +------+ +---------+ +-------+
|
||
133 | # | Example |
|
||
134 | # | ... |
|
||
135 | # | Example |
|
||
136 | # +---------+
|
||
137 | |||
138 | # Option constants.
|
||
139 | |||
140 | OPTIONFLAGS_BY_NAME = {} |
||
141 | def register_optionflag(name): |
||
142 | flag = 1 << len(OPTIONFLAGS_BY_NAME) |
||
143 | OPTIONFLAGS_BY_NAME[name] = flag |
||
144 | return flag
|
||
145 | |||
146 | DONT_ACCEPT_TRUE_FOR_1 = register_optionflag('DONT_ACCEPT_TRUE_FOR_1')
|
||
147 | DONT_ACCEPT_BLANKLINE = register_optionflag('DONT_ACCEPT_BLANKLINE')
|
||
148 | NORMALIZE_WHITESPACE = register_optionflag('NORMALIZE_WHITESPACE')
|
||
149 | ELLIPSIS = register_optionflag('ELLIPSIS')
|
||
150 | IGNORE_EXCEPTION_DETAIL = register_optionflag('IGNORE_EXCEPTION_DETAIL')
|
||
151 | |||
152 | COMPARISON_FLAGS = (DONT_ACCEPT_TRUE_FOR_1 | |
||
153 | DONT_ACCEPT_BLANKLINE | |
||
154 | NORMALIZE_WHITESPACE | |
||
155 | ELLIPSIS | |
||
156 | IGNORE_EXCEPTION_DETAIL) |
||
157 | |||
158 | REPORT_UDIFF = register_optionflag('REPORT_UDIFF')
|
||
159 | REPORT_CDIFF = register_optionflag('REPORT_CDIFF')
|
||
160 | REPORT_NDIFF = register_optionflag('REPORT_NDIFF')
|
||
161 | REPORT_ONLY_FIRST_FAILURE = register_optionflag('REPORT_ONLY_FIRST_FAILURE')
|
||
162 | |||
163 | REPORTING_FLAGS = (REPORT_UDIFF | |
||
164 | REPORT_CDIFF | |
||
165 | REPORT_NDIFF | |
||
166 | REPORT_ONLY_FIRST_FAILURE) |
||
167 | |||
168 | # Special string markers for use in `want` strings:
|
||
169 | BLANKLINE_MARKER = '<BLANKLINE>'
|
||
170 | ELLIPSIS_MARKER = '...'
|
||
171 | |||
172 | ######################################################################
|
||
173 | ## Table of Contents
|
||
174 | ######################################################################
|
||
175 | # 1. Utility Functions
|
||
176 | # 2. Example & DocTest -- store test cases
|
||
177 | # 3. DocTest Parser -- extracts examples from strings
|
||
178 | # 4. DocTest Finder -- extracts test cases from objects
|
||
179 | # 5. DocTest Runner -- runs test cases
|
||
180 | # 6. Test Functions -- convenient wrappers for testing
|
||
181 | # 7. Tester Class -- for backwards compatibility
|
||
182 | # 8. Unittest Support
|
||
183 | # 9. Debugging Support
|
||
184 | # 10. Example Usage
|
||
185 | |||
186 | ######################################################################
|
||
187 | ## 1. Utility Functions
|
||
188 | ######################################################################
|
||
189 | |||
190 | def is_private(prefix, base): |
||
191 | """prefix, base -> true iff name prefix + "." + base is "private".
|
||
192 |
|
||
193 | Prefix may be an empty string, and base does not contain a period.
|
||
194 | Prefix is ignored (although functions you write conforming to this
|
||
195 | protocol may make use of it).
|
||
196 | Return true iff base begins with an (at least one) underscore, but
|
||
197 | does not both begin and end with (at least) two underscores.
|
||
198 |
|
||
199 | >>> is_private("a.b", "my_func")
|
||
200 | False
|
||
201 | >>> is_private("____", "_my_func")
|
||
202 | True
|
||
203 | >>> is_private("someclass", "__init__")
|
||
204 | False
|
||
205 | >>> is_private("sometypo", "__init_")
|
||
206 | True
|
||
207 | >>> is_private("x.y.z", "_")
|
||
208 | True
|
||
209 | >>> is_private("_x.y.z", "__")
|
||
210 | False
|
||
211 | >>> is_private("", "") # senseless but consistent
|
||
212 | False
|
||
213 | """
|
||
214 | warnings.warn("is_private is deprecated; it wasn't useful; "
|
||
215 | "examine DocTestFinder.find() lists instead",
|
||
216 | DeprecationWarning, stacklevel=2) |
||
217 | return base[:1] == "_" and not base[:2] == "__" == base[-2:] |
||
218 | |||
219 | def _extract_future_flags(globs): |
||
220 | """
|
||
221 | Return the compiler-flags associated with the future features that
|
||
222 | have been imported into the given namespace (globs).
|
||
223 | """
|
||
224 | flags = 0
|
||
225 | for fname in __future__.all_feature_names: |
||
226 | feature = globs.get(fname, None)
|
||
227 | if feature is getattr(__future__, fname): |
||
228 | flags |= feature.compiler_flag |
||
229 | return flags
|
||
230 | |||
231 | def _normalize_module(module, depth=2): |
||
232 | """
|
||
233 | Return the module specified by `module`. In particular:
|
||
234 | - If `module` is a module, then return module.
|
||
235 | - If `module` is a string, then import and return the
|
||
236 | module with that name.
|
||
237 | - If `module` is None, then return the calling module.
|
||
238 | The calling module is assumed to be the module of
|
||
239 | the stack frame at the given depth in the call stack.
|
||
240 | """
|
||
241 | if inspect.ismodule(module):
|
||
242 | return module
|
||
243 | elif isinstance(module, (str, unicode)): |
||
244 | return __import__(module, globals(), locals(), ["*"]) |
||
245 | elif module is None: |
||
246 | return sys.modules[sys._getframe(depth).f_globals['__name__']] |
||
247 | else:
|
||
248 | raise TypeError("Expected a module, string, or None") |
||
249 | |||
250 | def _indent(s, indent=4): |
||
251 | """
|
||
252 | Add the given number of space characters to the beginning every
|
||
253 | non-blank line in `s`, and return the result.
|
||
254 | """
|
||
255 | # This regexp matches the start of non-blank lines:
|
||
256 | return re.sub('(?m)^(?!$)', indent*' ', s) |
||
257 | |||
258 | def _exception_traceback(exc_info): |
||
259 | """
|
||
260 | Return a string containing a traceback message for the given
|
||
261 | exc_info tuple (as returned by sys.exc_info()).
|
||
262 | """
|
||
263 | # Get a traceback message.
|
||
264 | excout = StringIO() |
||
265 | exc_type, exc_val, exc_tb = exc_info |
||
266 | traceback.print_exception(exc_type, exc_val, exc_tb, file=excout) |
||
267 | return excout.getvalue()
|
||
268 | |||
269 | # Override some StringIO methods.
|
||
270 | class _SpoofOut(StringIO): |
||
271 | def getvalue(self): |
||
272 | result = StringIO.getvalue(self)
|
||
273 | # If anything at all was written, make sure there's a trailing
|
||
274 | # newline. There's no way for the expected output to indicate
|
||
275 | # that a trailing newline is missing.
|
||
276 | if result and not result.endswith("\n"): |
||
277 | result += "\n"
|
||
278 | # Prevent softspace from screwing up the next test case, in
|
||
279 | # case they used print with a trailing comma in an example.
|
||
280 | if hasattr(self, "softspace"): |
||
281 | del self.softspace |
||
282 | return result
|
||
283 | |||
284 | def truncate(self, size=None): |
||
285 | StringIO.truncate(self, size)
|
||
286 | if hasattr(self, "softspace"): |
||
287 | del self.softspace |
||
288 | |||
289 | # Worst-case linear-time ellipsis matching.
|
||
290 | def _ellipsis_match(want, got): |
||
291 | """
|
||
292 | Essentially the only subtle case:
|
||
293 | >>> _ellipsis_match('aa...aa', 'aaa')
|
||
294 | False
|
||
295 | """
|
||
296 | if want.find(ELLIPSIS_MARKER)==-1: |
||
297 | return want == got
|
||
298 | |||
299 | # Find "the real" strings.
|
||
300 | ws = want.split(ELLIPSIS_MARKER) |
||
301 | assert len(ws) >= 2 |
||
302 | |||
303 | # Deal with exact matches possibly needed at one or both ends.
|
||
304 | startpos, endpos = 0, len(got) |
||
305 | w = ws[0]
|
||
306 | if w: # starts with exact match |
||
307 | if got.startswith(w):
|
||
308 | startpos = len(w)
|
||
309 | del ws[0] |
||
310 | else:
|
||
311 | return False |
||
312 | w = ws[-1]
|
||
313 | if w: # ends with exact match |
||
314 | if got.endswith(w):
|
||
315 | endpos -= len(w)
|
||
316 | del ws[-1] |
||
317 | else:
|
||
318 | return False |
||
319 | |||
320 | if startpos > endpos:
|
||
321 | # Exact end matches required more characters than we have, as in
|
||
322 | # _ellipsis_match('aa...aa', 'aaa')
|
||
323 | return False |
||
324 | |||
325 | # For the rest, we only need to find the leftmost non-overlapping
|
||
326 | # match for each piece. If there's no overall match that way alone,
|
||
327 | # there's no overall match period.
|
||
328 | for w in ws: |
||
329 | # w may be '' at times, if there are consecutive ellipses, or
|
||
330 | # due to an ellipsis at the start or end of `want`. That's OK.
|
||
331 | # Search for an empty string succeeds, and doesn't change startpos.
|
||
332 | startpos = got.find(w, startpos, endpos) |
||
333 | if startpos < 0: |
||
334 | return False |
||
335 | startpos += len(w)
|
||
336 | |||
337 | return True |
||
338 | |||
339 | def _comment_line(line): |
||
340 | "Return a commented form of the given line"
|
||
341 | line = line.rstrip() |
||
342 | if line:
|
||
343 | return '# '+line |
||
344 | else:
|
||
345 | return '#' |
||
346 | |||
347 | class _OutputRedirectingPdb(pdb.Pdb): |
||
348 | """
|
||
349 | A specialized version of the python debugger that redirects stdout
|
||
350 | to a given stream when interacting with the user. Stdout is *not*
|
||
351 | redirected when traced code is executed.
|
||
352 | """
|
||
353 | def __init__(self, out): |
||
354 | self.__out = out
|
||
355 | pdb.Pdb.__init__(self)
|
||
356 | |||
357 | def trace_dispatch(self, *args): |
||
358 | # Redirect stdout to the given stream.
|
||
359 | save_stdout = sys.stdout |
||
360 | sys.stdout = self.__out
|
||
361 | # Call Pdb's trace dispatch method.
|
||
362 | try:
|
||
363 | return pdb.Pdb.trace_dispatch(self, *args) |
||
364 | finally:
|
||
365 | sys.stdout = save_stdout |
||
366 | |||
367 | # [XX] Normalize with respect to os.path.pardir?
|
||
368 | def _module_relative_path(module, path): |
||
369 | if not inspect.ismodule(module): |
||
370 | raise TypeError, 'Expected a module: %r' % module |
||
371 | if path.startswith('/'): |
||
372 | raise ValueError, 'Module-relative files may not have absolute paths' |
||
373 | |||
374 | # Find the base directory for the path.
|
||
375 | if hasattr(module, '__file__'): |
||
376 | # A normal module/package
|
||
377 | basedir = os.path.split(module.__file__)[0]
|
||
378 | elif module.__name__ == '__main__': |
||
379 | # An interactive session.
|
||
380 | if len(sys.argv)>0 and sys.argv[0] != '': |
||
381 | basedir = os.path.split(sys.argv[0])[0] |
||
382 | else:
|
||
383 | basedir = os.curdir |
||
384 | else:
|
||
385 | # A module w/o __file__ (this includes builtins)
|
||
386 | raise ValueError("Can't resolve paths relative to the module " + |
||
387 | module + " (it has no __file__)")
|
||
388 | |||
389 | # Combine the base directory and the path.
|
||
390 | return os.path.join(basedir, *(path.split('/'))) |
||
391 | |||
392 | ######################################################################
|
||
393 | ## 2. Example & DocTest
|
||
394 | ######################################################################
|
||
395 | ## - An "example" is a <source, want> pair, where "source" is a
|
||
396 | ## fragment of source code, and "want" is the expected output for
|
||
397 | ## "source." The Example class also includes information about
|
||
398 | ## where the example was extracted from.
|
||
399 | ##
|
||
400 | ## - A "doctest" is a collection of examples, typically extracted from
|
||
401 | ## a string (such as an object's docstring). The DocTest class also
|
||
402 | ## includes information about where the string was extracted from.
|
||
403 | |||
404 | class Example: |
||
405 | """
|
||
406 | A single doctest example, consisting of source code and expected
|
||
407 | output. `Example` defines the following attributes:
|
||
408 |
|
||
409 | - source: A single Python statement, always ending with a newline.
|
||
410 | The constructor adds a newline if needed.
|
||
411 |
|
||
412 | - want: The expected output from running the source code (either
|
||
413 | from stdout, or a traceback in case of exception). `want` ends
|
||
414 | with a newline unless it's empty, in which case it's an empty
|
||
415 | string. The constructor adds a newline if needed.
|
||
416 |
|
||
417 | - exc_msg: The exception message generated by the example, if
|
||
418 | the example is expected to generate an exception; or `None` if
|
||
419 | it is not expected to generate an exception. This exception
|
||
420 | message is compared against the return value of
|
||
421 | `traceback.format_exception_only()`. `exc_msg` ends with a
|
||
422 | newline unless it's `None`. The constructor adds a newline
|
||
423 | if needed.
|
||
424 |
|
||
425 | - lineno: The line number within the DocTest string containing
|
||
426 | this Example where the Example begins. This line number is
|
||
427 | zero-based, with respect to the beginning of the DocTest.
|
||
428 |
|
||
429 | - indent: The example's indentation in the DocTest string.
|
||
430 | I.e., the number of space characters that preceed the
|
||
431 | example's first prompt.
|
||
432 |
|
||
433 | - options: A dictionary mapping from option flags to True or
|
||
434 | False, which is used to override default options for this
|
||
435 | example. Any option flags not contained in this dictionary
|
||
436 | are left at their default value (as specified by the
|
||
437 | DocTestRunner's optionflags). By default, no options are set.
|
||
438 | """
|
||
439 | def __init__(self, source, want, exc_msg=None, lineno=0, indent=0, |
||
440 | options=None):
|
||
441 | # Normalize inputs.
|
||
442 | if not source.endswith('\n'): |
||
443 | source += '\n'
|
||
444 | if want and not want.endswith('\n'): |
||
445 | want += '\n'
|
||
446 | if exc_msg is not None and not exc_msg.endswith('\n'): |
||
447 | exc_msg += '\n'
|
||
448 | # Store properties.
|
||
449 | self.source = source
|
||
450 | self.want = want
|
||
451 | self.lineno = lineno
|
||
452 | self.indent = indent
|
||
453 | if options is None: options = {} |
||
454 | self.options = options
|
||
455 | self.exc_msg = exc_msg
|
||
456 | |||
457 | class DocTest: |
||
458 | """
|
||
459 | A collection of doctest examples that should be run in a single
|
||
460 | namespace. Each `DocTest` defines the following attributes:
|
||
461 |
|
||
462 | - examples: the list of examples.
|
||
463 |
|
||
464 | - globs: The namespace (aka globals) that the examples should
|
||
465 | be run in.
|
||
466 |
|
||
467 | - name: A name identifying the DocTest (typically, the name of
|
||
468 | the object whose docstring this DocTest was extracted from).
|
||
469 |
|
||
470 | - filename: The name of the file that this DocTest was extracted
|
||
471 | from, or `None` if the filename is unknown.
|
||
472 |
|
||
473 | - lineno: The line number within filename where this DocTest
|
||
474 | begins, or `None` if the line number is unavailable. This
|
||
475 | line number is zero-based, with respect to the beginning of
|
||
476 | the file.
|
||
477 |
|
||
478 | - docstring: The string that the examples were extracted from,
|
||
479 | or `None` if the string is unavailable.
|
||
480 | """
|
||
481 | def __init__(self, examples, globs, name, filename, lineno, docstring): |
||
482 | """
|
||
483 | Create a new DocTest containing the given examples. The
|
||
484 | DocTest's globals are initialized with a copy of `globs`.
|
||
485 | """
|
||
486 | assert not isinstance(examples, basestring), \ |
||
487 | "DocTest no longer accepts str; use DocTestParser instead"
|
||
488 | self.examples = examples
|
||
489 | self.docstring = docstring
|
||
490 | self.globs = globs.copy()
|
||
491 | self.name = name
|
||
492 | self.filename = filename
|
||
493 | self.lineno = lineno
|
||
494 | |||
495 | def __repr__(self): |
||
496 | if len(self.examples) == 0: |
||
497 | examples = 'no examples'
|
||
498 | elif len(self.examples) == 1: |
||
499 | examples = '1 example'
|
||
500 | else:
|
||
501 | examples = '%d examples' % len(self.examples) |
||
502 | return ('<DocTest %s from %s:%s (%s)>' % |
||
503 | (self.name, self.filename, self.lineno, examples)) |
||
504 | |||
505 | |||
506 | # This lets us sort tests by name:
|
||
507 | def __cmp__(self, other): |
||
508 | if not isinstance(other, DocTest): |
||
509 | return -1 |
||
510 | return cmp((self.name, self.filename, self.lineno, id(self)), |
||
511 | (other.name, other.filename, other.lineno, id(other)))
|
||
512 | |||
513 | ######################################################################
|
||
514 | ## 3. DocTestParser
|
||
515 | ######################################################################
|
||
516 | |||
517 | class DocTestParser: |
||
518 | """
|
||
519 | A class used to parse strings containing doctest examples.
|
||
520 | """
|
||
521 | # This regular expression is used to find doctest examples in a
|
||
522 | # string. It defines three groups: `source` is the source code
|
||
523 | # (including leading indentation and prompts); `indent` is the
|
||
524 | # indentation of the first (PS1) line of the source code; and
|
||
525 | # `want` is the expected output (including leading indentation).
|
||
526 | _EXAMPLE_RE = re.compile(r'''
|
||
527 | # Source consists of a PS1 line followed by zero or more PS2 lines.
|
||
528 | (?P<source>
|
||
529 | (?:^(?P<indent> [ ]*) >>> .*) # PS1 line
|
||
530 | (?:\n [ ]* \.\.\. .*)*) # PS2 lines
|
||
531 | \n?
|
||
532 | # Want consists of any non-blank lines that do not start with PS1.
|
||
533 | (?P<want> (?:(?![ ]*$) # Not a blank line
|
||
534 | (?![ ]*>>>) # Not a line starting with PS1
|
||
535 | .*$\n? # But any other line
|
||
536 | )*)
|
||
537 | ''', re.MULTILINE | re.VERBOSE)
|
||
538 | |||
539 | # A regular expression for handling `want` strings that contain
|
||
540 | # expected exceptions. It divides `want` into three pieces:
|
||
541 | # - the traceback header line (`hdr`)
|
||
542 | # - the traceback stack (`stack`)
|
||
543 | # - the exception message (`msg`), as generated by
|
||
544 | # traceback.format_exception_only()
|
||
545 | # `msg` may have multiple lines. We assume/require that the
|
||
546 | # exception message is the first non-indented line starting with a word
|
||
547 | # character following the traceback header line.
|
||
548 | _EXCEPTION_RE = re.compile(r"""
|
||
549 | # Grab the traceback header. Different versions of Python have
|
||
550 | # said different things on the first traceback line.
|
||
551 | ^(?P<hdr> Traceback\ \(
|
||
552 | (?: most\ recent\ call\ last
|
||
553 | | innermost\ last
|
||
554 | ) \) :
|
||
555 | )
|
||
556 | \s* $ # toss trailing whitespace on the header.
|
||
557 | (?P<stack> .*?) # don't blink: absorb stuff until...
|
||
558 | ^ (?P<msg> \w+ .*) # a line *starts* with alphanum.
|
||
559 | """, re.VERBOSE | re.MULTILINE | re.DOTALL)
|
||
560 | |||
561 | # A callable returning a true value iff its argument is a blank line
|
||
562 | # or contains a single comment.
|
||
563 | _IS_BLANK_OR_COMMENT = re.compile(r'^[ ]*(#.*)?$').match
|
||
564 | |||
565 | def parse(self, string, name='<string>'): |
||
566 | """
|
||
567 | Divide the given string into examples and intervening text,
|
||
568 | and return them as a list of alternating Examples and strings.
|
||
569 | Line numbers for the Examples are 0-based. The optional
|
||
570 | argument `name` is a name identifying this string, and is only
|
||
571 | used for error messages.
|
||
572 | """
|
||
573 | string = string.expandtabs() |
||
574 | # If all lines begin with the same indentation, then strip it.
|
||
575 | min_indent = self._min_indent(string)
|
||
576 | if min_indent > 0: |
||
577 | string = '\n'.join([l[min_indent:] for l in string.split('\n')]) |
||
578 | |||
579 | output = [] |
||
580 | charno, lineno = 0, 0 |
||
581 | # Find all doctest examples in the string:
|
||
582 | for m in self._EXAMPLE_RE.finditer(string): |
||
583 | # Add the pre-example text to `output`.
|
||
584 | output.append(string[charno:m.start()]) |
||
585 | # Update lineno (lines before this example)
|
||
586 | lineno += string.count('\n', charno, m.start())
|
||
587 | # Extract info from the regexp match.
|
||
588 | (source, options, want, exc_msg) = \ |
||
589 | self._parse_example(m, name, lineno)
|
||
590 | # Create an Example, and add it to the list.
|
||
591 | if not self._IS_BLANK_OR_COMMENT(source): |
||
592 | output.append( Example(source, want, exc_msg, |
||
593 | lineno=lineno, |
||
594 | indent=min_indent+len(m.group('indent')), |
||
595 | options=options) ) |
||
596 | # Update lineno (lines inside this example)
|
||
597 | lineno += string.count('\n', m.start(), m.end())
|
||
598 | # Update charno.
|
||
599 | charno = m.end() |
||
600 | # Add any remaining post-example text to `output`.
|
||
601 | output.append(string[charno:]) |
||
602 | return output
|
||
603 | |||
604 | def get_doctest(self, string, globs, name, filename, lineno): |
||
605 | """
|
||
606 | Extract all doctest examples from the given string, and
|
||
607 | collect them into a `DocTest` object.
|
||
608 |
|
||
609 | `globs`, `name`, `filename`, and `lineno` are attributes for
|
||
610 | the new `DocTest` object. See the documentation for `DocTest`
|
||
611 | for more information.
|
||
612 | """
|
||
613 | return DocTest(self.get_examples(string, name), globs, |
||
614 | name, filename, lineno, string) |
||
615 | |||
616 | def get_examples(self, string, name='<string>'): |
||
617 | """
|
||
618 | Extract all doctest examples from the given string, and return
|
||
619 | them as a list of `Example` objects. Line numbers are
|
||
620 | 0-based, because it's most common in doctests that nothing
|
||
621 | interesting appears on the same line as opening triple-quote,
|
||
622 | and so the first interesting line is called \"line 1\" then.
|
||
623 |
|
||
624 | The optional argument `name` is a name identifying this
|
||
625 | string, and is only used for error messages.
|
||
626 | """
|
||
627 | return [x for x in self.parse(string, name) |
||
628 | if isinstance(x, Example)] |
||
629 | |||
630 | def _parse_example(self, m, name, lineno): |
||
631 | """
|
||
632 | Given a regular expression match from `_EXAMPLE_RE` (`m`),
|
||
633 | return a pair `(source, want)`, where `source` is the matched
|
||
634 | example's source code (with prompts and indentation stripped);
|
||
635 | and `want` is the example's expected output (with indentation
|
||
636 | stripped).
|
||
637 |
|
||
638 | `name` is the string's name, and `lineno` is the line number
|
||
639 | where the example starts; both are used for error messages.
|
||
640 | """
|
||
641 | # Get the example's indentation level.
|
||
642 | indent = len(m.group('indent')) |
||
643 | |||
644 | # Divide source into lines; check that they're properly
|
||
645 | # indented; and then strip their indentation & prompts.
|
||
646 | source_lines = m.group('source').split('\n') |
||
647 | self._check_prompt_blank(source_lines, indent, name, lineno)
|
||
648 | self._check_prefix(source_lines[1:], ' '*indent + '.', name, lineno) |
||
649 | source = '\n'.join([sl[indent+4:] for sl in source_lines]) |
||
650 | |||
651 | # Divide want into lines; check that it's properly indented; and
|
||
652 | # then strip the indentation. Spaces before the last newline should
|
||
653 | # be preserved, so plain rstrip() isn't good enough.
|
||
654 | want = m.group('want')
|
||
655 | want_lines = want.split('\n')
|
||
656 | if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]): |
||
657 | del want_lines[-1] # forget final newline & spaces after it |
||
658 | self._check_prefix(want_lines, ' '*indent, name, |
||
659 | lineno + len(source_lines))
|
||
660 | want = '\n'.join([wl[indent:] for wl in want_lines]) |
||
661 | |||
662 | # If `want` contains a traceback message, then extract it.
|
||
663 | m = self._EXCEPTION_RE.match(want)
|
||
664 | if m:
|
||
665 | exc_msg = m.group('msg')
|
||
666 | else:
|
||
667 | exc_msg = None
|
||
668 | |||
669 | # Extract options from the source.
|
||
670 | options = self._find_options(source, name, lineno)
|
||
671 | |||
672 | return source, options, want, exc_msg
|
||
673 | |||
674 | # This regular expression looks for option directives in the
|
||
675 | # source code of an example. Option directives are comments
|
||
676 | # starting with "doctest:". Warning: this may give false
|
||
677 | # positives for string-literals that contain the string
|
||
678 | # "#doctest:". Eliminating these false positives would require
|
||
679 | # actually parsing the string; but we limit them by ignoring any
|
||
680 | # line containing "#doctest:" that is *followed* by a quote mark.
|
||
681 | _OPTION_DIRECTIVE_RE = re.compile(r'#\s*doctest:\s*([^\n\'"]*)$',
|
||
682 | re.MULTILINE) |
||
683 | |||
684 | def _find_options(self, source, name, lineno): |
||
685 | """
|
||
686 | Return a dictionary containing option overrides extracted from
|
||
687 | option directives in the given source string.
|
||
688 |
|
||
689 | `name` is the string's name, and `lineno` is the line number
|
||
690 | where the example starts; both are used for error messages.
|
||
691 | """
|
||
692 | options = {} |
||
693 | # (note: with the current regexp, this will match at most once:)
|
||
694 | for m in self._OPTION_DIRECTIVE_RE.finditer(source): |
||
695 | option_strings = m.group(1).replace(',', ' ').split() |
||
696 | for option in option_strings: |
||
697 | if (option[0] not in '+-' or |
||
698 | option[1:] not in OPTIONFLAGS_BY_NAME): |
||
699 | raise ValueError('line %r of the doctest for %s ' |
||
700 | 'has an invalid option: %r' %
|
||
701 | (lineno+1, name, option))
|
||
702 | flag = OPTIONFLAGS_BY_NAME[option[1:]]
|
||
703 | options[flag] = (option[0] == '+') |
||
704 | if options and self._IS_BLANK_OR_COMMENT(source): |
||
705 | raise ValueError('line %r of the doctest for %s has an option ' |
||
706 | 'directive on a line with no example: %r' %
|
||
707 | (lineno, name, source)) |
||
708 | return options
|
||
709 | |||
710 | # This regular expression finds the indentation of every non-blank
|
||
711 | # line in a string.
|
||
712 | _INDENT_RE = re.compile('^([ ]*)(?=\S)', re.MULTILINE)
|
||
713 | |||
714 | def _min_indent(self, s): |
||
715 | "Return the minimum indentation of any non-blank line in `s`"
|
||
716 | indents = [len(indent) for indent in self._INDENT_RE.findall(s)] |
||
717 | if len(indents) > 0: |
||
718 | return min(indents) |
||
719 | else:
|
||
720 | return 0 |
||
721 | |||
722 | def _check_prompt_blank(self, lines, indent, name, lineno): |
||
723 | """
|
||
724 | Given the lines of a source string (including prompts and
|
||
725 | leading indentation), check to make sure that every prompt is
|
||
726 | followed by a space character. If any line is not followed by
|
||
727 | a space character, then raise ValueError.
|
||
728 | """
|
||
729 | for i, line in enumerate(lines): |
||
730 | if len(line) >= indent+4 and line[indent+3] != ' ': |
||
731 | raise ValueError('line %r of the docstring for %s ' |
||
732 | 'lacks blank after %s: %r' %
|
||
733 | (lineno+i+1, name,
|
||
734 | line[indent:indent+3], line))
|
||
735 | |||
736 | def _check_prefix(self, lines, prefix, name, lineno): |
||
737 | """
|
||
738 | Check that every line in the given list starts with the given
|
||
739 | prefix; if any line does not, then raise a ValueError.
|
||
740 | """
|
||
741 | for i, line in enumerate(lines): |
||
742 | if line and not line.startswith(prefix): |
||
743 | raise ValueError('line %r of the docstring for %s has ' |
||
744 | 'inconsistent leading whitespace: %r' %
|
||
745 | (lineno+i+1, name, line))
|
||
746 | |||
747 | |||
748 | ######################################################################
|
||
749 | ## 4. DocTest Finder
|
||
750 | ######################################################################
|
||
751 | |||
752 | class DocTestFinder: |
||
753 | """
|
||
754 | A class used to extract the DocTests that are relevant to a given
|
||
755 | object, from its docstring and the docstrings of its contained
|
||
756 | objects. Doctests can currently be extracted from the following
|
||
757 | object types: modules, functions, classes, methods, staticmethods,
|
||
758 | classmethods, and properties.
|
||
759 | """
|
||
760 | |||
761 | def __init__(self, verbose=False, parser=DocTestParser(), |
||
762 | recurse=True, _namefilter=None, exclude_empty=True): |
||
763 | """
|
||
764 | Create a new doctest finder.
|
||
765 |
|
||
766 | The optional argument `parser` specifies a class or
|
||
767 | function that should be used to create new DocTest objects (or
|
||
768 | objects that implement the same interface as DocTest). The
|
||
769 | signature for this factory function should match the signature
|
||
770 | of the DocTest constructor.
|
||
771 |
|
||
772 | If the optional argument `recurse` is false, then `find` will
|
||
773 | only examine the given object, and not any contained objects.
|
||
774 |
|
||
775 | If the optional argument `exclude_empty` is false, then `find`
|
||
776 | will include tests for objects with empty docstrings.
|
||
777 | """
|
||
778 | self._parser = parser
|
||
779 | self._verbose = verbose
|
||
780 | self._recurse = recurse
|
||
781 | self._exclude_empty = exclude_empty
|
||
782 | # _namefilter is undocumented, and exists only for temporary backward-
|
||
783 | # compatibility support of testmod's deprecated isprivate mess.
|
||
784 | self._namefilter = _namefilter
|
||
785 | |||
786 | def find(self, obj, name=None, module=None, globs=None, |
||
787 | extraglobs=None):
|
||
788 | """
|
||
789 | Return a list of the DocTests that are defined by the given
|
||
790 | object's docstring, or by any of its contained objects'
|
||
791 | docstrings.
|
||
792 |
|
||
793 | The optional parameter `module` is the module that contains
|
||
794 | the given object. If the module is not specified or is None, then
|
||
795 | the test finder will attempt to automatically determine the
|
||
796 | correct module. The object's module is used:
|
||
797 |
|
||
798 | - As a default namespace, if `globs` is not specified.
|
||
799 | - To prevent the DocTestFinder from extracting DocTests
|
||
800 | from objects that are imported from other modules.
|
||
801 | - To find the name of the file containing the object.
|
||
802 | - To help find the line number of the object within its
|
||
803 | file.
|
||
804 |
|
||
805 | Contained objects whose module does not match `module` are ignored.
|
||
806 |
|
||
807 | If `module` is False, no attempt to find the module will be made.
|
||
808 | This is obscure, of use mostly in tests: if `module` is False, or
|
||
809 | is None but cannot be found automatically, then all objects are
|
||
810 | considered to belong to the (non-existent) module, so all contained
|
||
811 | objects will (recursively) be searched for doctests.
|
||
812 |
|
||
813 | The globals for each DocTest is formed by combining `globs`
|
||
814 | and `extraglobs` (bindings in `extraglobs` override bindings
|
||
815 | in `globs`). A new copy of the globals dictionary is created
|
||
816 | for each DocTest. If `globs` is not specified, then it
|
||
817 | defaults to the module's `__dict__`, if specified, or {}
|
||
818 | otherwise. If `extraglobs` is not specified, then it defaults
|
||
819 | to {}.
|
||
820 |
|
||
821 | """
|
||
822 | # If name was not specified, then extract it from the object.
|
||
823 | if name is None: |
||
824 | name = getattr(obj, '__name__', None) |
||
825 | if name is None: |
||
826 | raise ValueError("DocTestFinder.find: name must be given " |
||
827 | "when obj.__name__ doesn't exist: %r" %
|
||
828 | (type(obj),))
|
||
829 | |||
830 | # Find the module that contains the given object (if obj is
|
||
831 | # a module, then module=obj.). Note: this may fail, in which
|
||
832 | # case module will be None.
|
||
833 | if module is False: |
||
834 | module = None
|
||
835 | elif module is None: |
||
836 | module = inspect.getmodule(obj) |
||
837 | |||
838 | # Read the module's source code. This is used by
|
||
839 | # DocTestFinder._find_lineno to find the line number for a
|
||
840 | # given object's docstring.
|
||
841 | try:
|
||
842 | file = inspect.getsourcefile(obj) or inspect.getfile(obj)
|
||
843 | source_lines = linecache.getlines(file)
|
||
844 | if not source_lines: |
||
845 | source_lines = None
|
||
846 | except TypeError: |
||
847 | source_lines = None
|
||
848 | |||
849 | # Initialize globals, and merge in extraglobs.
|
||
850 | if globs is None: |
||
851 | if module is None: |
||
852 | globs = {} |
||
853 | else:
|
||
854 | globs = module.__dict__.copy() |
||
855 | else:
|
||
856 | globs = globs.copy() |
||
857 | if extraglobs is not None: |
||
858 | globs.update(extraglobs) |
||
859 | |||
860 | # Recursively expore `obj`, extracting DocTests.
|
||
861 | tests = [] |
||
862 | self._find(tests, obj, name, module, source_lines, globs, {})
|
||
863 | return tests
|
||
864 | |||
865 | def _filter(self, obj, prefix, base): |
||
866 | """
|
||
867 | Return true if the given object should not be examined.
|
||
868 | """
|
||
869 | return (self._namefilter is not None and |
||
870 | self._namefilter(prefix, base))
|
||
871 | |||
872 | def _from_module(self, module, object): |
||
873 | """
|
||
874 | Return true if the given object is defined in the given
|
||
875 | module.
|
||
876 | """
|
||
877 | if module is None: |
||
878 | return True |
||
879 | elif inspect.isfunction(object): |
||
880 | return module.__dict__ is object.func_globals |
||
881 | elif inspect.isclass(object): |
||
882 | return module.__name__ == object.__module__ |
||
883 | elif inspect.getmodule(object) is not None: |
||
884 | return module is inspect.getmodule(object) |
||
885 | elif hasattr(object, '__module__'): |
||
886 | return module.__name__ == object.__module__ |
||
887 | elif isinstance(object, property): |
||
888 | return True # [XX] no way not be sure. |
||
889 | else:
|
||
890 | raise ValueError("object must be a class or function") |
||
891 | |||
892 | def _find(self, tests, obj, name, module, source_lines, globs, seen): |
||
893 | """
|
||
894 | Find tests for the given object and any contained objects, and
|
||
895 | add them to `tests`.
|
||
896 | """
|
||
897 | if self._verbose: |
||
898 | print 'Finding tests in %s' % name |
||
899 | |||
900 | # If we've already processed this object, then ignore it.
|
||
901 | if id(obj) in seen: |
||
902 | return
|
||
903 | seen[id(obj)] = 1 |
||
904 | |||
905 | # Find a test for this object, and add it to the list of tests.
|
||
906 | test = self._get_test(obj, name, module, globs, source_lines)
|
||
907 | if test is not None: |
||
908 | tests.append(test) |
||
909 | |||
910 | # Look for tests in a module's contained objects.
|
||
911 | if inspect.ismodule(obj) and self._recurse: |
||
912 | for valname, val in obj.__dict__.items(): |
||
913 | # Check if this contained object should be ignored.
|
||
914 | if self._filter(val, name, valname): |
||
915 | continue
|
||
916 | valname = '%s.%s' % (name, valname)
|
||
917 | # Recurse to functions & classes.
|
||
918 | if ((inspect.isfunction(val) or inspect.isclass(val)) and |
||
919 | self._from_module(module, val)):
|
||
920 | self._find(tests, val, valname, module, source_lines,
|
||
921 | globs, seen) |
||
922 | |||
923 | # Look for tests in a module's __test__ dictionary.
|
||
924 | if inspect.ismodule(obj) and self._recurse: |
||
925 | for valname, val in getattr(obj, '__test__', {}).items(): |
||
926 | if not isinstance(valname, basestring): |
||
927 | raise ValueError("DocTestFinder.find: __test__ keys " |
||
928 | "must be strings: %r" %
|
||
929 | (type(valname),))
|
||
930 | if not (inspect.isfunction(val) or inspect.isclass(val) or |
||
931 | inspect.ismethod(val) or inspect.ismodule(val) or |
||
932 | isinstance(val, basestring)): |
||
933 | raise ValueError("DocTestFinder.find: __test__ values " |
||
934 | "must be strings, functions, methods, "
|
||
935 | "classes, or modules: %r" %
|
||
936 | (type(val),))
|
||
937 | valname = '%s.__test__.%s' % (name, valname)
|
||
938 | self._find(tests, val, valname, module, source_lines,
|
||
939 | globs, seen) |
||
940 | |||
941 | # Look for tests in a class's contained objects.
|
||
942 | if inspect.isclass(obj) and self._recurse: |
||
943 | for valname, val in obj.__dict__.items(): |
||
944 | # Check if this contained object should be ignored.
|
||
945 | if self._filter(val, name, valname): |
||
946 | continue
|
||
947 | # Special handling for staticmethod/classmethod.
|
||
948 | if isinstance(val, staticmethod): |
||
949 | val = getattr(obj, valname)
|
||
950 | if isinstance(val, classmethod): |
||
951 | val = getattr(obj, valname).im_func
|
||
952 | |||
953 | # Recurse to methods, properties, and nested classes.
|
||
954 | if ((inspect.isfunction(val) or inspect.isclass(val) or |
||
955 | isinstance(val, property)) and |
||
956 | self._from_module(module, val)):
|
||
957 | valname = '%s.%s' % (name, valname)
|
||
958 | self._find(tests, val, valname, module, source_lines,
|
||
959 | globs, seen) |
||
960 | |||
961 | def _get_test(self, obj, name, module, globs, source_lines): |
||
962 | """
|
||
963 | Return a DocTest for the given object, if it defines a docstring;
|
||
964 | otherwise, return None.
|
||
965 | """
|
||
966 | # Extract the object's docstring. If it doesn't have one,
|
||
967 | # then return None (no test for this object).
|
||
968 | if isinstance(obj, basestring): |
||
969 | docstring = obj |
||
970 | else:
|
||
971 | try:
|
||
972 | if obj.__doc__ is None: |
||
973 | docstring = ''
|
||
974 | else:
|
||
975 | docstring = obj.__doc__ |
||
976 | if not isinstance(docstring, basestring): |
||
977 | docstring = str(docstring)
|
||
978 | except (TypeError, AttributeError): |
||
979 | docstring = ''
|
||
980 | |||
981 | # Find the docstring's location in the file.
|
||
982 | lineno = self._find_lineno(obj, source_lines)
|
||
983 | |||
984 | # Don't bother if the docstring is empty.
|
||
985 | if self._exclude_empty and not docstring: |
||
986 | return None |
||
987 | |||
988 | # Return a DocTest for this object.
|
||
989 | if module is None: |
||
990 | filename = None
|
||
991 | else:
|
||
992 | filename = getattr(module, '__file__', module.__name__) |
||
993 | if filename[-4:] in (".pyc", ".pyo"): |
||
994 | filename = filename[:-1]
|
||
995 | return self._parser.get_doctest(docstring, globs, name, |
||
996 | filename, lineno) |
||
997 | |||
998 | def _find_lineno(self, obj, source_lines): |
||
999 | """
|
||
1000 | Return a line number of the given object's docstring. Note:
|
||
1001 | this method assumes that the object has a docstring.
|
||
1002 | """
|
||
1003 | lineno = None
|
||
1004 | |||
1005 | # Find the line number for modules.
|
||
1006 | if inspect.ismodule(obj):
|
||
1007 | lineno = 0
|
||
1008 | |||
1009 | # Find the line number for classes.
|
||
1010 | # Note: this could be fooled if a class is defined multiple
|
||
1011 | # times in a single file.
|
||
1012 | if inspect.isclass(obj):
|
||
1013 | if source_lines is None: |
||
1014 | return None |
||
1015 | pat = re.compile(r'^\s*class\s*%s\b' %
|
||
1016 | getattr(obj, '__name__', '-')) |
||
1017 | for i, line in enumerate(source_lines): |
||
1018 | if pat.match(line):
|
||
1019 | lineno = i |
||
1020 | break
|
||
1021 | |||
1022 | # Find the line number for functions & methods.
|
||
1023 | if inspect.ismethod(obj): obj = obj.im_func
|
||
1024 | if inspect.isfunction(obj): obj = obj.func_code
|
||
1025 | if inspect.istraceback(obj): obj = obj.tb_frame
|
||
1026 | if inspect.isframe(obj): obj = obj.f_code
|
||
1027 | if inspect.iscode(obj):
|
||
1028 | lineno = getattr(obj, 'co_firstlineno', None)-1 |
||
1029 | |||
1030 | # Find the line number where the docstring starts. Assume
|
||
1031 | # that it's the first line that begins with a quote mark.
|
||
1032 | # Note: this could be fooled by a multiline function
|
||
1033 | # signature, where a continuation line begins with a quote
|
||
1034 | # mark.
|
||
1035 | if lineno is not None: |
||
1036 | if source_lines is None: |
||
1037 | return lineno+1 |
||
1038 | pat = re.compile('(^|.*:)\s*\w*("|\')')
|
||
1039 | for lineno in range(lineno, len(source_lines)): |
||
1040 | if pat.match(source_lines[lineno]):
|
||
1041 | return lineno
|
||
1042 | |||
1043 | # We couldn't find the line number.
|
||
1044 | return None |
||
1045 | |||
1046 | ######################################################################
|
||
1047 | ## 5. DocTest Runner
|
||
1048 | ######################################################################
|
||
1049 | |||
1050 | class DocTestRunner: |
||
1051 | """
|
||
1052 | A class used to run DocTest test cases, and accumulate statistics.
|
||
1053 | The `run` method is used to process a single DocTest case. It
|
||
1054 | returns a tuple `(f, t)`, where `t` is the number of test cases
|
||
1055 | tried, and `f` is the number of test cases that failed.
|
||
1056 |
|
||
1057 | >>> tests = DocTestFinder().find(_TestClass)
|
||
1058 | >>> runner = DocTestRunner(verbose=False)
|
||
1059 | >>> for test in tests:
|
||
1060 | ... print runner.run(test)
|
||
1061 | (0, 2)
|
||
1062 | (0, 1)
|
||
1063 | (0, 2)
|
||
1064 | (0, 2)
|
||
1065 |
|
||
1066 | The `summarize` method prints a summary of all the test cases that
|
||
1067 | have been run by the runner, and returns an aggregated `(f, t)`
|
||
1068 | tuple:
|
||
1069 |
|
||
1070 | >>> runner.summarize(verbose=1)
|
||
1071 | 4 items passed all tests:
|
||
1072 | 2 tests in _TestClass
|
||
1073 | 2 tests in _TestClass.__init__
|
||
1074 | 2 tests in _TestClass.get
|
||
1075 | 1 tests in _TestClass.square
|
||
1076 | 7 tests in 4 items.
|
||
1077 | 7 passed and 0 failed.
|
||
1078 | Test passed.
|
||
1079 | (0, 7)
|
||
1080 |
|
||
1081 | The aggregated number of tried examples and failed examples is
|
||
1082 | also available via the `tries` and `failures` attributes:
|
||
1083 |
|
||
1084 | >>> runner.tries
|
||
1085 | 7
|
||
1086 | >>> runner.failures
|
||
1087 | 0
|
||
1088 |
|
||
1089 | The comparison between expected outputs and actual outputs is done
|
||
1090 | by an `OutputChecker`. This comparison may be customized with a
|
||
1091 | number of option flags; see the documentation for `testmod` for
|
||
1092 | more information. If the option flags are insufficient, then the
|
||
1093 | comparison may also be customized by passing a subclass of
|
||
1094 | `OutputChecker` to the constructor.
|
||
1095 |
|
||
1096 | The test runner's display output can be controlled in two ways.
|
||
1097 | First, an output function (`out) can be passed to
|
||
1098 | `TestRunner.run`; this function will be called with strings that
|
||
1099 | should be displayed. It defaults to `sys.stdout.write`. If
|
||
1100 | capturing the output is not sufficient, then the display output
|
||
1101 | can be also customized by subclassing DocTestRunner, and
|
||
1102 | overriding the methods `report_start`, `report_success`,
|
||
1103 | `report_unexpected_exception`, and `report_failure`.
|
||
1104 | """
|
||
1105 | # This divider string is used to separate failure messages, and to
|
||
1106 | # separate sections of the summary.
|
||
1107 | DIVIDER = "*" * 70 |
||
1108 | |||
1109 | def __init__(self, checker=None, verbose=None, optionflags=0): |
||
1110 | """
|
||
1111 | Create a new test runner.
|
||
1112 |
|
||
1113 | Optional keyword arg `checker` is the `OutputChecker` that
|
||
1114 | should be used to compare the expected outputs and actual
|
||
1115 | outputs of doctest examples.
|
||
1116 |
|
||
1117 | Optional keyword arg 'verbose' prints lots of stuff if true,
|
||
1118 | only failures if false; by default, it's true iff '-v' is in
|
||
1119 | sys.argv.
|
||
1120 |
|
||
1121 | Optional argument `optionflags` can be used to control how the
|
||
1122 | test runner compares expected output to actual output, and how
|
||
1123 | it displays failures. See the documentation for `testmod` for
|
||
1124 | more information.
|
||
1125 | """
|
||
1126 | self._checker = checker or OutputChecker() |
||
1127 | if verbose is None: |
||
1128 | verbose = '-v' in sys.argv |
||
1129 | self._verbose = verbose
|
||
1130 | self.optionflags = optionflags
|
||
1131 | self.original_optionflags = optionflags
|
||
1132 | |||
1133 | # Keep track of the examples we've run.
|
||
1134 | self.tries = 0 |
||
1135 | self.failures = 0 |
||
1136 | self._name2ft = {}
|
||
1137 | |||
1138 | # Create a fake output target for capturing doctest output.
|
||
1139 | self._fakeout = _SpoofOut()
|
||
1140 | |||
1141 | #/////////////////////////////////////////////////////////////////
|
||
1142 | # Reporting methods
|
||
1143 | #/////////////////////////////////////////////////////////////////
|
||
1144 | |||
1145 | def report_start(self, out, test, example): |
||
1146 | """
|
||
1147 | Report that the test runner is about to process the given
|
||
1148 | example. (Only displays a message if verbose=True)
|
||
1149 | """
|
||
1150 | if self._verbose: |
||
1151 | if example.want:
|
||
1152 | out('Trying:\n' + _indent(example.source) +
|
||
1153 | 'Expecting:\n' + _indent(example.want))
|
||
1154 | else:
|
||
1155 | out('Trying:\n' + _indent(example.source) +
|
||
1156 | 'Expecting nothing\n')
|
||
1157 | |||
1158 | def report_success(self, out, test, example, got): |
||
1159 | """
|
||
1160 | Report that the given example ran successfully. (Only
|
||
1161 | displays a message if verbose=True)
|
||
1162 | """
|
||
1163 | if self._verbose: |
||
1164 | out("ok\n")
|
||
1165 | |||
1166 | def report_failure(self, out, test, example, got): |
||
1167 | """
|
||
1168 | Report that the given example failed.
|
||
1169 | """
|
||
1170 | out(self._failure_header(test, example) +
|
||
1171 | self._checker.output_difference(example, got, self.optionflags)) |
||
1172 | |||
1173 | def report_unexpected_exception(self, out, test, example, exc_info): |
||
1174 | """
|
||
1175 | Report that the given example raised an unexpected exception.
|
||
1176 | """
|
||
1177 | out(self._failure_header(test, example) +
|
||
1178 | 'Exception raised:\n' + _indent(_exception_traceback(exc_info)))
|
||
1179 | |||
1180 | def _failure_header(self, test, example): |
||
1181 | out = [self.DIVIDER]
|
||
1182 | if test.filename:
|
||
1183 | if test.lineno is not None and example.lineno is not None: |
||
1184 | lineno = test.lineno + example.lineno + 1
|
||
1185 | else:
|
||
1186 | lineno = '?'
|
||
1187 | out.append('File "%s", line %s, in %s' %
|
||
1188 | (test.filename, lineno, test.name)) |
||
1189 | else:
|
||
1190 | out.append('Line %s, in %s' % (example.lineno+1, test.name)) |
||
1191 | out.append('Failed example:')
|
||
1192 | source = example.source |
||
1193 | out.append(_indent(source)) |
||
1194 | return '\n'.join(out) |
||
1195 | |||
1196 | #/////////////////////////////////////////////////////////////////
|
||
1197 | # DocTest Running
|
||
1198 | #/////////////////////////////////////////////////////////////////
|
||
1199 | |||
1200 | def __run(self, test, compileflags, out): |
||
1201 | """
|
||
1202 | Run the examples in `test`. Write the outcome of each example
|
||
1203 | with one of the `DocTestRunner.report_*` methods, using the
|
||
1204 | writer function `out`. `compileflags` is the set of compiler
|
||
1205 | flags that should be used to execute examples. Return a tuple
|
||
1206 | `(f, t)`, where `t` is the number of examples tried, and `f`
|
||
1207 | is the number of examples that failed. The examples are run
|
||
1208 | in the namespace `test.globs`.
|
||
1209 | """
|
||
1210 | # Keep track of the number of failures and tries.
|
||
1211 | failures = tries = 0
|
||
1212 | |||
1213 | # Save the option flags (since option directives can be used
|
||
1214 | # to modify them).
|
||
1215 | original_optionflags = self.optionflags
|
||
1216 | |||
1217 | SUCCESS, FAILURE, BOOM = range(3) # `outcome` state |
||
1218 | |||
1219 | check = self._checker.check_output
|
||
1220 | |||
1221 | # Process each example.
|
||
1222 | for examplenum, example in enumerate(test.examples): |
||
1223 | |||
1224 | # If REPORT_ONLY_FIRST_FAILURE is set, then supress
|
||
1225 | # reporting after the first failure.
|
||
1226 | quiet = (self.optionflags & REPORT_ONLY_FIRST_FAILURE and |
||
1227 | failures > 0)
|
||
1228 | |||
1229 | # Merge in the example's options.
|
||
1230 | self.optionflags = original_optionflags
|
||
1231 | if example.options:
|
||
1232 | for (optionflag, val) in example.options.items(): |
||
1233 | if val:
|
||
1234 | self.optionflags |= optionflag
|
||
1235 | else:
|
||
1236 | self.optionflags &= ~optionflag
|
||
1237 | |||
1238 | # Record that we started this example.
|
||
1239 | tries += 1
|
||
1240 | if not quiet: |
||
1241 | self.report_start(out, test, example)
|
||
1242 | |||
1243 | # Use a special filename for compile(), so we can retrieve
|
||
1244 | # the source code during interactive debugging (see
|
||
1245 | # __patched_linecache_getlines).
|
||
1246 | filename = '<doctest %s[%d]>' % (test.name, examplenum)
|
||
1247 | |||
1248 | # Run the example in the given context (globs), and record
|
||
1249 | # any exception that gets raised. (But don't intercept
|
||
1250 | # keyboard interrupts.)
|
||
1251 | try:
|
||
1252 | # Don't blink! This is where the user's code gets run.
|
||
1253 | exec compile(example.source, filename, "single", |
||
1254 | compileflags, 1) in test.globs |
||
1255 | self.debugger.set_continue() # ==== Example Finished ==== |
||
1256 | exception = None
|
||
1257 | except KeyboardInterrupt: |
||
1258 | raise
|
||
1259 | except:
|
||
1260 | exception = sys.exc_info() |
||
1261 | self.debugger.set_continue() # ==== Example Finished ==== |
||
1262 | |||
1263 | got = self._fakeout.getvalue() # the actual output |
||
1264 | self._fakeout.truncate(0) |
||
1265 | outcome = FAILURE # guilty until proved innocent or insane
|
||
1266 | |||
1267 | # If the example executed without raising any exceptions,
|
||
1268 | # verify its output.
|
||
1269 | if exception is None: |
||
1270 | if check(example.want, got, self.optionflags): |
||
1271 | outcome = SUCCESS |
||
1272 | |||
1273 | # The example raised an exception: check if it was expected.
|
||
1274 | else:
|
||
1275 | exc_info = sys.exc_info() |
||
1276 | exc_msg = traceback.format_exception_only(*exc_info[:2])[-1] |
||
1277 | if not quiet: |
||
1278 | got += _exception_traceback(exc_info) |
||
1279 | |||
1280 | # If `example.exc_msg` is None, then we weren't expecting
|
||
1281 | # an exception.
|
||
1282 | if example.exc_msg is None: |
||
1283 | outcome = BOOM |
||
1284 | |||
1285 | # We expected an exception: see whether it matches.
|
||
1286 | elif check(example.exc_msg, exc_msg, self.optionflags): |
||
1287 | outcome = SUCCESS |
||
1288 | |||
1289 | # Another chance if they didn't care about the detail.
|
||
1290 | elif self.optionflags & IGNORE_EXCEPTION_DETAIL: |
||
1291 | m1 = re.match(r'[^:]*:', example.exc_msg)
|
||
1292 | m2 = re.match(r'[^:]*:', exc_msg)
|
||
1293 | if m1 and m2 and check(m1.group(0), m2.group(0), |
||
1294 | self.optionflags):
|
||
1295 | outcome = SUCCESS |
||
1296 | |||
1297 | # Report the outcome.
|
||
1298 | if outcome is SUCCESS: |
||
1299 | if not quiet: |
||
1300 | self.report_success(out, test, example, got)
|
||
1301 | elif outcome is FAILURE: |
||
1302 | if not quiet: |
||
1303 | self.report_failure(out, test, example, got)
|
||
1304 | failures += 1
|
||
1305 | elif outcome is BOOM: |
||
1306 | if not quiet: |
||
1307 | self.report_unexpected_exception(out, test, example,
|
||
1308 | exc_info) |
||
1309 | failures += 1
|
||
1310 | else:
|
||
1311 | assert False, ("unknown outcome", outcome) |
||
1312 | |||
1313 | # Restore the option flags (in case they were modified)
|
||
1314 | self.optionflags = original_optionflags
|
||
1315 | |||
1316 | # Record and return the number of failures and tries.
|
||
1317 | self.__record_outcome(test, failures, tries)
|
||
1318 | return failures, tries
|
||
1319 | |||
1320 | def __record_outcome(self, test, f, t): |
||
1321 | """
|
||
1322 | Record the fact that the given DocTest (`test`) generated `f`
|
||
1323 | failures out of `t` tried examples.
|
||
1324 | """
|
||
1325 | f2, t2 = self._name2ft.get(test.name, (0,0)) |
||
1326 | self._name2ft[test.name] = (f+f2, t+t2)
|
||
1327 | self.failures += f
|
||
1328 | self.tries += t
|
||
1329 | |||
1330 | __LINECACHE_FILENAME_RE = re.compile(r'<doctest '
|
||
1331 | r'(?P<name>[\w\.]+)'
|
||
1332 | r'\[(?P<examplenum>\d+)\]>$')
|
||
1333 | def __patched_linecache_getlines(self, filename, module_globals=None): |
||
1334 | m = self.__LINECACHE_FILENAME_RE.match(filename)
|
||
1335 | if m and m.group('name') == self.test.name: |
||
1336 | example = self.test.examples[int(m.group('examplenum'))] |
||
1337 | return example.source.splitlines(True) |
||
1338 | elif self.save_linecache_getlines.func_code.co_argcount>1: |
||
1339 | return self.save_linecache_getlines(filename, module_globals) |
||
1340 | else:
|
||
1341 | return self.save_linecache_getlines(filename) |
||
1342 | |||
1343 | def run(self, test, compileflags=None, out=None, clear_globs=True): |
||
1344 | """
|
||
1345 | Run the examples in `test`, and display the results using the
|
||
1346 | writer function `out`.
|
||
1347 |
|
||
1348 | The examples are run in the namespace `test.globs`. If
|
||
1349 | `clear_globs` is true (the default), then this namespace will
|
||
1350 | be cleared after the test runs, to help with garbage
|
||
1351 | collection. If you would like to examine the namespace after
|
||
1352 | the test completes, then use `clear_globs=False`.
|
||
1353 |
|
||
1354 | `compileflags` gives the set of flags that should be used by
|
||
1355 | the Python compiler when running the examples. If not
|
||
1356 | specified, then it will default to the set of future-import
|
||
1357 | flags that apply to `globs`.
|
||
1358 |
|
||
1359 | The output of each example is checked using
|
||
1360 | `DocTestRunner.check_output`, and the results are formatted by
|
||
1361 | the `DocTestRunner.report_*` methods.
|
||
1362 | """
|
||
1363 | self.test = test
|
||
1364 | |||
1365 | if compileflags is None: |
||
1366 | compileflags = _extract_future_flags(test.globs) |
||
1367 | |||
1368 | save_stdout = sys.stdout |
||
1369 | if out is None: |
||
1370 | out = save_stdout.write |
||
1371 | sys.stdout = self._fakeout
|
||
1372 | |||
1373 | # Patch pdb.set_trace to restore sys.stdout during interactive
|
||
1374 | # debugging (so it's not still redirected to self._fakeout).
|
||
1375 | # Note that the interactive output will go to *our*
|
||
1376 | # save_stdout, even if that's not the real sys.stdout; this
|
||
1377 | # allows us to write test cases for the set_trace behavior.
|
||
1378 | save_set_trace = pdb.set_trace |
||
1379 | self.debugger = _OutputRedirectingPdb(save_stdout)
|
||
1380 | self.debugger.reset()
|
||
1381 | pdb.set_trace = self.debugger.set_trace
|
||
1382 | |||
1383 | # Patch linecache.getlines, so we can see the example's source
|
||
1384 | # when we're inside the debugger.
|
||
1385 | self.save_linecache_getlines = linecache.getlines
|
||
1386 | linecache.getlines = self.__patched_linecache_getlines
|
||
1387 | |||
1388 | try:
|
||
1389 | return self.__run(test, compileflags, out) |
||
1390 | finally:
|
||
1391 | sys.stdout = save_stdout |
||
1392 | pdb.set_trace = save_set_trace |
||
1393 | linecache.getlines = self.save_linecache_getlines
|
||
1394 | if clear_globs:
|
||
1395 | test.globs.clear() |
||
1396 | |||
1397 | #/////////////////////////////////////////////////////////////////
|
||
1398 | # Summarization
|
||
1399 | #/////////////////////////////////////////////////////////////////
|
||
1400 | def summarize(self, verbose=None): |
||
1401 | """
|
||
1402 | Print a summary of all the test cases that have been run by
|
||
1403 | this DocTestRunner, and return a tuple `(f, t)`, where `f` is
|
||
1404 | the total number of failed examples, and `t` is the total
|
||
1405 | number of tried examples.
|
||
1406 |
|
||
1407 | The optional `verbose` argument controls how detailed the
|
||
1408 | summary is. If the verbosity is not specified, then the
|
||
1409 | DocTestRunner's verbosity is used.
|
||
1410 | """
|
||
1411 | if verbose is None: |
||
1412 | verbose = self._verbose
|
||
1413 | notests = [] |
||
1414 | passed = [] |
||
1415 | failed = [] |
||
1416 | totalt = totalf = 0
|
||
1417 | for x in self._name2ft.items(): |
||
1418 | name, (f, t) = x |
||
1419 | assert f <= t
|
||
1420 | totalt += t |
||
1421 | totalf += f |
||
1422 | if t == 0: |
||
1423 | notests.append(name) |
||
1424 | elif f == 0: |
||
1425 | passed.append( (name, t) ) |
||
1426 | else:
|
||
1427 | failed.append(x) |
||
1428 | if verbose:
|
||
1429 | if notests:
|
||
1430 | print len(notests), "items had no tests:" |
||
1431 | notests.sort() |
||
1432 | for thing in notests: |
||
1433 | print " ", thing |
||
1434 | if passed:
|
||
1435 | print len(passed), "items passed all tests:" |
||
1436 | passed.sort() |
||
1437 | for thing, count in passed: |
||
1438 | print " %3d tests in %s" % (count, thing) |
||
1439 | if failed:
|
||
1440 | print self.DIVIDER |
||
1441 | print len(failed), "items had failures:" |
||
1442 | failed.sort() |
||
1443 | for thing, (f, t) in failed: |
||
1444 | print " %3d of %3d in %s" % (f, t, thing) |
||
1445 | if verbose:
|
||
1446 | print totalt, "tests in", len(self._name2ft), "items." |
||
1447 | print totalt - totalf, "passed and", totalf, "failed." |
||
1448 | if totalf:
|
||
1449 | print "***Test Failed***", totalf, "failures." |
||
1450 | elif verbose:
|
||
1451 | print "Test passed." |
||
1452 | return totalf, totalt
|
||
1453 | |||
1454 | #/////////////////////////////////////////////////////////////////
|
||
1455 | # Backward compatibility cruft to maintain doctest.master.
|
||
1456 | #/////////////////////////////////////////////////////////////////
|
||
1457 | def merge(self, other): |
||
1458 | d = self._name2ft
|
||
1459 | for name, (f, t) in other._name2ft.items(): |
||
1460 | if name in d: |
||
1461 | print "*** DocTestRunner.merge: '" + name + "' in both" \ |
||
1462 | " testers; summing outcomes."
|
||
1463 | f2, t2 = d[name] |
||
1464 | f = f + f2 |
||
1465 | t = t + t2 |
||
1466 | d[name] = f, t |
||
1467 | |||
1468 | class OutputChecker: |
||
1469 | """
|
||
1470 | A class used to check the whether the actual output from a doctest
|
||
1471 | example matches the expected output. `OutputChecker` defines two
|
||
1472 | methods: `check_output`, which compares a given pair of outputs,
|
||
1473 | and returns true if they match; and `output_difference`, which
|
||
1474 | returns a string describing the differences between two outputs.
|
||
1475 | """
|
||
1476 | def check_output(self, want, got, optionflags): |
||
1477 | """
|
||
1478 | Return True iff the actual output from an example (`got`)
|
||
1479 | matches the expected output (`want`). These strings are
|
||
1480 | always considered to match if they are identical; but
|
||
1481 | depending on what option flags the test runner is using,
|
||
1482 | several non-exact match types are also possible. See the
|
||
1483 | documentation for `TestRunner` for more information about
|
||
1484 | option flags.
|
||
1485 | """
|
||
1486 | # Handle the common case first, for efficiency:
|
||
1487 | # if they're string-identical, always return true.
|
||
1488 | if got == want:
|
||
1489 | return True |
||
1490 | |||
1491 | # The values True and False replaced 1 and 0 as the return
|
||
1492 | # value for boolean comparisons in Python 2.3.
|
||
1493 | if not (optionflags & DONT_ACCEPT_TRUE_FOR_1): |
||
1494 | if (got,want) == ("True\n", "1\n"): |
||
1495 | return True |
||
1496 | if (got,want) == ("False\n", "0\n"): |
||
1497 | return True |
||
1498 | |||
1499 | # <BLANKLINE> can be used as a special sequence to signify a
|
||
1500 | # blank line, unless the DONT_ACCEPT_BLANKLINE flag is used.
|
||
1501 | if not (optionflags & DONT_ACCEPT_BLANKLINE): |
||
1502 | # Replace <BLANKLINE> in want with a blank line.
|
||
1503 | want = re.sub('(?m)^%s\s*?$' % re.escape(BLANKLINE_MARKER),
|
||
1504 | '', want)
|
||
1505 | # If a line in got contains only spaces, then remove the
|
||
1506 | # spaces.
|
||
1507 | got = re.sub('(?m)^\s*?$', '', got) |
||
1508 | if got == want:
|
||
1509 | return True |
||
1510 | |||
1511 | # This flag causes doctest to ignore any differences in the
|
||
1512 | # contents of whitespace strings. Note that this can be used
|
||
1513 | # in conjunction with the ELLIPSIS flag.
|
||
1514 | if optionflags & NORMALIZE_WHITESPACE:
|
||
1515 | got = ' '.join(got.split())
|
||
1516 | want = ' '.join(want.split())
|
||
1517 | if got == want:
|
||
1518 | return True |
||
1519 | |||
1520 | # The ELLIPSIS flag says to let the sequence "..." in `want`
|
||
1521 | # match any substring in `got`.
|
||
1522 | if optionflags & ELLIPSIS:
|
||
1523 | if _ellipsis_match(want, got):
|
||
1524 | return True |
||
1525 | |||
1526 | # We didn't find any match; return false.
|
||
1527 | return False |
||
1528 | |||
1529 | # Should we do a fancy diff?
|
||
1530 | def _do_a_fancy_diff(self, want, got, optionflags): |
||
1531 | # Not unless they asked for a fancy diff.
|
||
1532 | if not optionflags & (REPORT_UDIFF | |
||
1533 | REPORT_CDIFF | |
||
1534 | REPORT_NDIFF): |
||
1535 | return False |
||
1536 | |||
1537 | # If expected output uses ellipsis, a meaningful fancy diff is
|
||
1538 | # too hard ... or maybe not. In two real-life failures Tim saw,
|
||
1539 | # a diff was a major help anyway, so this is commented out.
|
||
1540 | # [todo] _ellipsis_match() knows which pieces do and don't match,
|
||
1541 | # and could be the basis for a kick-ass diff in this case.
|
||
1542 | ##if optionflags & ELLIPSIS and ELLIPSIS_MARKER in want:
|
||
1543 | ## return False
|
||
1544 | |||
1545 | # ndiff does intraline difference marking, so can be useful even
|
||
1546 | # for 1-line differences.
|
||
1547 | if optionflags & REPORT_NDIFF:
|
||
1548 | return True |
||
1549 | |||
1550 | # The other diff types need at least a few lines to be helpful.
|
||
1551 | return want.count('\n') > 2 and got.count('\n') > 2 |
||
1552 | |||
1553 | def output_difference(self, example, got, optionflags): |
||
1554 | """
|
||
1555 | Return a string describing the differences between the
|
||
1556 | expected output for a given example (`example`) and the actual
|
||
1557 | output (`got`). `optionflags` is the set of option flags used
|
||
1558 | to compare `want` and `got`.
|
||
1559 | """
|
||
1560 | want = example.want |
||
1561 | # If <BLANKLINE>s are being used, then replace blank lines
|
||
1562 | # with <BLANKLINE> in the actual output string.
|
||
1563 | if not (optionflags & DONT_ACCEPT_BLANKLINE): |
||
1564 | got = re.sub('(?m)^[ ]*(?=\n)', BLANKLINE_MARKER, got)
|
||
1565 | |||
1566 | # Check if we should use diff.
|
||
1567 | if self._do_a_fancy_diff(want, got, optionflags): |
||
1568 | # Split want & got into lines.
|
||
1569 | want_lines = want.splitlines(True) # True == keep line ends |
||
1570 | got_lines = got.splitlines(True)
|
||
1571 | # Use difflib to find their differences.
|
||
1572 | if optionflags & REPORT_UDIFF:
|
||
1573 | diff = difflib.unified_diff(want_lines, got_lines, n=2)
|
||
1574 | diff = list(diff)[2:] # strip the diff header |
||
1575 | kind = 'unified diff with -expected +actual'
|
||
1576 | elif optionflags & REPORT_CDIFF:
|
||
1577 | diff = difflib.context_diff(want_lines, got_lines, n=2)
|
||
1578 | diff = list(diff)[2:] # strip the diff header |
||
1579 | kind = 'context diff with expected followed by actual'
|
||
1580 | elif optionflags & REPORT_NDIFF:
|
||
1581 | engine = difflib.Differ(charjunk=difflib.IS_CHARACTER_JUNK) |
||
1582 | diff = list(engine.compare(want_lines, got_lines))
|
||
1583 | kind = 'ndiff with -expected +actual'
|
||
1584 | else:
|
||
1585 | assert 0, 'Bad diff option' |
||
1586 | # Remove trailing whitespace on diff output.
|
||
1587 | diff = [line.rstrip() + '\n' for line in diff] |
||
1588 | return 'Differences (%s):\n' % kind + _indent(''.join(diff)) |
||
1589 | |||
1590 | # If we're not using diff, then simply list the expected
|
||
1591 | # output followed by the actual output.
|
||
1592 | if want and got: |
||
1593 | return 'Expected:\n%sGot:\n%s' % (_indent(want), _indent(got)) |
||
1594 | elif want:
|
||
1595 | return 'Expected:\n%sGot nothing\n' % _indent(want) |
||
1596 | elif got:
|
||
1597 | return 'Expected nothing\nGot:\n%s' % _indent(got) |
||
1598 | else:
|
||
1599 | return 'Expected nothing\nGot nothing\n' |
||
1600 | |||
1601 | class DocTestFailure(Exception): |
||
1602 | """A DocTest example has failed in debugging mode.
|
||
1603 |
|
||
1604 | The exception instance has variables:
|
||
1605 |
|
||
1606 | - test: the DocTest object being run
|
||
1607 |
|
||
1608 | - excample: the Example object that failed
|
||
1609 |
|
||
1610 | - got: the actual output
|
||
1611 | """
|
||
1612 | def __init__(self, test, example, got): |
||
1613 | self.test = test
|
||
1614 | self.example = example
|
||
1615 | self.got = got
|
||
1616 | |||
1617 | def __str__(self): |
||
1618 | return str(self.test) |
||
1619 | |||
1620 | class UnexpectedException(Exception): |
||
1621 | """A DocTest example has encountered an unexpected exception
|
||
1622 |
|
||
1623 | The exception instance has variables:
|
||
1624 |
|
||
1625 | - test: the DocTest object being run
|
||
1626 |
|
||
1627 | - excample: the Example object that failed
|
||
1628 |
|
||
1629 | - exc_info: the exception info
|
||
1630 | """
|
||
1631 | def __init__(self, test, example, exc_info): |
||
1632 | self.test = test
|
||
1633 | self.example = example
|
||
1634 | self.exc_info = exc_info
|
||
1635 | |||
1636 | def __str__(self): |
||
1637 | return str(self.test) |
||
1638 | |||
1639 | class DebugRunner(DocTestRunner): |
||
1640 | r"""Run doc tests but raise an exception as soon as there is a failure.
|
||
1641 |
|
||
1642 | If an unexpected exception occurs, an UnexpectedException is raised.
|
||
1643 | It contains the test, the example, and the original exception:
|
||
1644 |
|
||
1645 | >>> runner = DebugRunner(verbose=False)
|
||
1646 | >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
|
||
1647 | ... {}, 'foo', 'foo.py', 0)
|
||
1648 | >>> try:
|
||
1649 | ... runner.run(test)
|
||
1650 | ... except UnexpectedException, failure:
|
||
1651 | ... pass
|
||
1652 |
|
||
1653 | >>> failure.test is test
|
||
1654 | True
|
||
1655 |
|
||
1656 | >>> failure.example.want
|
||
1657 | '42\n'
|
||
1658 |
|
||
1659 | >>> exc_info = failure.exc_info
|
||
1660 | >>> raise exc_info[0], exc_info[1], exc_info[2]
|
||
1661 | Traceback (most recent call last):
|
||
1662 | ...
|
||
1663 | KeyError
|
||
1664 |
|
||
1665 | We wrap the original exception to give the calling application
|
||
1666 | access to the test and example information.
|
||
1667 |
|
||
1668 | If the output doesn't match, then a DocTestFailure is raised:
|
||
1669 |
|
||
1670 | >>> test = DocTestParser().get_doctest('''
|
||
1671 | ... >>> x = 1
|
||
1672 | ... >>> x
|
||
1673 | ... 2
|
||
1674 | ... ''', {}, 'foo', 'foo.py', 0)
|
||
1675 |
|
||
1676 | >>> try:
|
||
1677 | ... runner.run(test)
|
||
1678 | ... except DocTestFailure, failure:
|
||
1679 | ... pass
|
||
1680 |
|
||
1681 | DocTestFailure objects provide access to the test:
|
||
1682 |
|
||
1683 | >>> failure.test is test
|
||
1684 | True
|
||
1685 |
|
||
1686 | As well as to the example:
|
||
1687 |
|
||
1688 | >>> failure.example.want
|
||
1689 | '2\n'
|
||
1690 |
|
||
1691 | and the actual output:
|
||
1692 |
|
||
1693 | >>> failure.got
|
||
1694 | '1\n'
|
||
1695 |
|
||
1696 | If a failure or error occurs, the globals are left intact:
|
||
1697 |
|
||
1698 | >>> del test.globs['__builtins__']
|
||
1699 | >>> test.globs
|
||
1700 | {'x': 1}
|
||
1701 |
|
||
1702 | >>> test = DocTestParser().get_doctest('''
|
||
1703 | ... >>> x = 2
|
||
1704 | ... >>> raise KeyError
|
||
1705 | ... ''', {}, 'foo', 'foo.py', 0)
|
||
1706 |
|
||
1707 | >>> runner.run(test)
|
||
1708 | Traceback (most recent call last):
|
||
1709 | ...
|
||
1710 | UnexpectedException: <DocTest foo from foo.py:0 (2 examples)>
|
||
1711 |
|
||
1712 | >>> del test.globs['__builtins__']
|
||
1713 | >>> test.globs
|
||
1714 | {'x': 2}
|
||
1715 |
|
||
1716 | But the globals are cleared if there is no error:
|
||
1717 |
|
||
1718 | >>> test = DocTestParser().get_doctest('''
|
||
1719 | ... >>> x = 2
|
||
1720 | ... ''', {}, 'foo', 'foo.py', 0)
|
||
1721 |
|
||
1722 | >>> runner.run(test)
|
||
1723 | (0, 1)
|
||
1724 |
|
||
1725 | >>> test.globs
|
||
1726 | {}
|
||
1727 |
|
||
1728 | """
|
||
1729 | |||
1730 | def run(self, test, compileflags=None, out=None, clear_globs=True): |
||
1731 | r = DocTestRunner.run(self, test, compileflags, out, False) |
||
1732 | if clear_globs:
|
||
1733 | test.globs.clear() |
||
1734 | return r
|
||
1735 | |||
1736 | def report_unexpected_exception(self, out, test, example, exc_info): |
||
1737 | raise UnexpectedException(test, example, exc_info)
|
||
1738 | |||
1739 | def report_failure(self, out, test, example, got): |
||
1740 | raise DocTestFailure(test, example, got)
|
||
1741 | |||
1742 | ######################################################################
|
||
1743 | ## 6. Test Functions
|
||
1744 | ######################################################################
|
||
1745 | # These should be backwards compatible.
|
||
1746 | |||
1747 | # For backward compatibility, a global instance of a DocTestRunner
|
||
1748 | # class, updated by testmod.
|
||
1749 | master = None
|
||
1750 | |||
1751 | def testmod(m=None, name=None, globs=None, verbose=None, isprivate=None, |
||
1752 | report=True, optionflags=0, extraglobs=None, |
||
1753 | raise_on_error=False, exclude_empty=False): |
||
1754 | """m=None, name=None, globs=None, verbose=None, isprivate=None,
|
||
1755 | report=True, optionflags=0, extraglobs=None, raise_on_error=False,
|
||
1756 | exclude_empty=False
|
||
1757 |
|
||
1758 | Test examples in docstrings in functions and classes reachable
|
||
1759 | from module m (or the current module if m is not supplied), starting
|
||
1760 | with m.__doc__. Unless isprivate is specified, private names
|
||
1761 | are not skipped.
|
||
1762 |
|
||
1763 | Also test examples reachable from dict m.__test__ if it exists and is
|
||
1764 | not None. m.__test__ maps names to functions, classes and strings;
|
||
1765 | function and class docstrings are tested even if the name is private;
|
||
1766 | strings are tested directly, as if they were docstrings.
|
||
1767 |
|
||
1768 | Return (#failures, #tests).
|
||
1769 |
|
||
1770 | See doctest.__doc__ for an overview.
|
||
1771 |
|
||
1772 | Optional keyword arg "name" gives the name of the module; by default
|
||
1773 | use m.__name__.
|
||
1774 |
|
||
1775 | Optional keyword arg "globs" gives a dict to be used as the globals
|
||
1776 | when executing examples; by default, use m.__dict__. A copy of this
|
||
1777 | dict is actually used for each docstring, so that each docstring's
|
||
1778 | examples start with a clean slate.
|
||
1779 |
|
||
1780 | Optional keyword arg "extraglobs" gives a dictionary that should be
|
||
1781 | merged into the globals that are used to execute examples. By
|
||
1782 | default, no extra globals are used. This is new in 2.4.
|
||
1783 |
|
||
1784 | Optional keyword arg "verbose" prints lots of stuff if true, prints
|
||
1785 | only failures if false; by default, it's true iff "-v" is in sys.argv.
|
||
1786 |
|
||
1787 | Optional keyword arg "report" prints a summary at the end when true,
|
||
1788 | else prints nothing at the end. In verbose mode, the summary is
|
||
1789 | detailed, else very brief (in fact, empty if all tests passed).
|
||
1790 |
|
||
1791 | Optional keyword arg "optionflags" or's together module constants,
|
||
1792 | and defaults to 0. This is new in 2.3. Possible values (see the
|
||
1793 | docs for details):
|
||
1794 |
|
||
1795 | DONT_ACCEPT_TRUE_FOR_1
|
||
1796 | DONT_ACCEPT_BLANKLINE
|
||
1797 | NORMALIZE_WHITESPACE
|
||
1798 | ELLIPSIS
|
||
1799 | IGNORE_EXCEPTION_DETAIL
|
||
1800 | REPORT_UDIFF
|
||
1801 | REPORT_CDIFF
|
||
1802 | REPORT_NDIFF
|
||
1803 | REPORT_ONLY_FIRST_FAILURE
|
||
1804 |
|
||
1805 | Optional keyword arg "raise_on_error" raises an exception on the
|
||
1806 | first unexpected exception or failure. This allows failures to be
|
||
1807 | post-mortem debugged.
|
||
1808 |
|
||
1809 | Deprecated in Python 2.4:
|
||
1810 | Optional keyword arg "isprivate" specifies a function used to
|
||
1811 | determine whether a name is private. The default function is
|
||
1812 | treat all functions as public. Optionally, "isprivate" can be
|
||
1813 | set to doctest.is_private to skip over functions marked as private
|
||
1814 | using the underscore naming convention; see its docs for details.
|
||
1815 |
|
||
1816 | Advanced tomfoolery: testmod runs methods of a local instance of
|
||
1817 | class doctest.Tester, then merges the results into (or creates)
|
||
1818 | global Tester instance doctest.master. Methods of doctest.master
|
||
1819 | can be called directly too, if you want to do something unusual.
|
||
1820 | Passing report=0 to testmod is especially useful then, to delay
|
||
1821 | displaying a summary. Invoke doctest.master.summarize(verbose)
|
||
1822 | when you're done fiddling.
|
||
1823 | """
|
||
1824 | global master
|
||
1825 | |||
1826 | if isprivate is not None: |
||
1827 | warnings.warn("the isprivate argument is deprecated; "
|
||
1828 | "examine DocTestFinder.find() lists instead",
|
||
1829 | DeprecationWarning)
|
||
1830 | |||
1831 | # If no module was given, then use __main__.
|
||
1832 | if m is None: |
||
1833 | # DWA - m will still be None if this wasn't invoked from the command
|
||
1834 | # line, in which case the following TypeError is about as good an error
|
||
1835 | # as we should expect
|
||
1836 | m = sys.modules.get('__main__')
|
||
1837 | |||
1838 | # Check that we were actually given a module.
|
||
1839 | if not inspect.ismodule(m): |
||
1840 | raise TypeError("testmod: module required; %r" % (m,)) |
||
1841 | |||
1842 | # If no name was given, then use the module's name.
|
||
1843 | if name is None: |
||
1844 | name = m.__name__ |
||
1845 | |||
1846 | # Find, parse, and run all tests in the given module.
|
||
1847 | finder = DocTestFinder(_namefilter=isprivate, exclude_empty=exclude_empty) |
||
1848 | |||
1849 | if raise_on_error:
|
||
1850 | runner = DebugRunner(verbose=verbose, optionflags=optionflags) |
||
1851 | else:
|
||
1852 | runner = DocTestRunner(verbose=verbose, optionflags=optionflags) |
||
1853 | |||
1854 | for test in finder.find(m, name, globs=globs, extraglobs=extraglobs): |
||
1855 | runner.run(test) |
||
1856 | |||
1857 | if report:
|
||
1858 | runner.summarize() |
||
1859 | |||
1860 | if master is None: |
||
1861 | master = runner |
||
1862 | else:
|
||
1863 | master.merge(runner) |
||
1864 | |||
1865 | return runner.failures, runner.tries
|
||
1866 | |||
1867 | def testfile(filename, module_relative=True, name=None, package=None, |
||
1868 | globs=None, verbose=None, report=True, optionflags=0, |
||
1869 | extraglobs=None, raise_on_error=False, parser=DocTestParser()): |
||
1870 | """
|
||
1871 | Test examples in the given file. Return (#failures, #tests).
|
||
1872 |
|
||
1873 | Optional keyword arg "module_relative" specifies how filenames
|
||
1874 | should be interpreted:
|
||
1875 |
|
||
1876 | - If "module_relative" is True (the default), then "filename"
|
||
1877 | specifies a module-relative path. By default, this path is
|
||
1878 | relative to the calling module's directory; but if the
|
||
1879 | "package" argument is specified, then it is relative to that
|
||
1880 | package. To ensure os-independence, "filename" should use
|
||
1881 | "/" characters to separate path segments, and should not
|
||
1882 | be an absolute path (i.e., it may not begin with "/").
|
||
1883 |
|
||
1884 | - If "module_relative" is False, then "filename" specifies an
|
||
1885 | os-specific path. The path may be absolute or relative (to
|
||
1886 | the current working directory).
|
||
1887 |
|
||
1888 | Optional keyword arg "name" gives the name of the test; by default
|
||
1889 | use the file's basename.
|
||
1890 |
|
||
1891 | Optional keyword argument "package" is a Python package or the
|
||
1892 | name of a Python package whose directory should be used as the
|
||
1893 | base directory for a module relative filename. If no package is
|
||
1894 | specified, then the calling module's directory is used as the base
|
||
1895 | directory for module relative filenames. It is an error to
|
||
1896 | specify "package" if "module_relative" is False.
|
||
1897 |
|
||
1898 | Optional keyword arg "globs" gives a dict to be used as the globals
|
||
1899 | when executing examples; by default, use {}. A copy of this dict
|
||
1900 | is actually used for each docstring, so that each docstring's
|
||
1901 | examples start with a clean slate.
|
||
1902 |
|
||
1903 | Optional keyword arg "extraglobs" gives a dictionary that should be
|
||
1904 | merged into the globals that are used to execute examples. By
|
||
1905 | default, no extra globals are used.
|
||
1906 |
|
||
1907 | Optional keyword arg "verbose" prints lots of stuff if true, prints
|
||
1908 | only failures if false; by default, it's true iff "-v" is in sys.argv.
|
||
1909 |
|
||
1910 | Optional keyword arg "report" prints a summary at the end when true,
|
||
1911 | else prints nothing at the end. In verbose mode, the summary is
|
||
1912 | detailed, else very brief (in fact, empty if all tests passed).
|
||
1913 |
|
||
1914 | Optional keyword arg "optionflags" or's together module constants,
|
||
1915 | and defaults to 0. Possible values (see the docs for details):
|
||
1916 |
|
||
1917 | DONT_ACCEPT_TRUE_FOR_1
|
||
1918 | DONT_ACCEPT_BLANKLINE
|
||
1919 | NORMALIZE_WHITESPACE
|
||
1920 | ELLIPSIS
|
||
1921 | IGNORE_EXCEPTION_DETAIL
|
||
1922 | REPORT_UDIFF
|
||
1923 | REPORT_CDIFF
|
||
1924 | REPORT_NDIFF
|
||
1925 | REPORT_ONLY_FIRST_FAILURE
|
||
1926 |
|
||
1927 | Optional keyword arg "raise_on_error" raises an exception on the
|
||
1928 | first unexpected exception or failure. This allows failures to be
|
||
1929 | post-mortem debugged.
|
||
1930 |
|
||
1931 | Optional keyword arg "parser" specifies a DocTestParser (or
|
||
1932 | subclass) that should be used to extract tests from the files.
|
||
1933 |
|
||
1934 | Advanced tomfoolery: testmod runs methods of a local instance of
|
||
1935 | class doctest.Tester, then merges the results into (or creates)
|
||
1936 | global Tester instance doctest.master. Methods of doctest.master
|
||
1937 | can be called directly too, if you want to do something unusual.
|
||
1938 | Passing report=0 to testmod is especially useful then, to delay
|
||
1939 | displaying a summary. Invoke doctest.master.summarize(verbose)
|
||
1940 | when you're done fiddling.
|
||
1941 | """
|
||
1942 | global master
|
||
1943 | |||
1944 | if package and not module_relative: |
||
1945 | raise ValueError("Package may only be specified for module-" |
||
1946 | "relative paths.")
|
||
1947 | |||
1948 | # Relativize the path
|
||
1949 | if module_relative:
|
||
1950 | package = _normalize_module(package) |
||
1951 | filename = _module_relative_path(package, filename) |
||
1952 | |||
1953 | # If no name was given, then use the file's name.
|
||
1954 | if name is None: |
||
1955 | name = os.path.basename(filename) |
||
1956 | |||
1957 | # Assemble the globals.
|
||
1958 | if globs is None: |
||
1959 | globs = {} |
||
1960 | else:
|
||
1961 | globs = globs.copy() |
||
1962 | if extraglobs is not None: |
||
1963 | globs.update(extraglobs) |
||
1964 | |||
1965 | if raise_on_error:
|
||
1966 | runner = DebugRunner(verbose=verbose, optionflags=optionflags) |
||
1967 | else:
|
||
1968 | runner = DocTestRunner(verbose=verbose, optionflags=optionflags) |
||
1969 | |||
1970 | # Read the file, convert it to a test, and run it.
|
||
1971 | s = open(filename).read()
|
||
1972 | test = parser.get_doctest(s, globs, name, filename, 0)
|
||
1973 | runner.run(test) |
||
1974 | |||
1975 | if report:
|
||
1976 | runner.summarize() |
||
1977 | |||
1978 | if master is None: |
||
1979 | master = runner |
||
1980 | else:
|
||
1981 | master.merge(runner) |
||
1982 | |||
1983 | return runner.failures, runner.tries
|
||
1984 | |||
1985 | def run_docstring_examples(f, globs, verbose=False, name="NoName", |
||
1986 | compileflags=None, optionflags=0): |
||
1987 | """
|
||
1988 | Test examples in the given object's docstring (`f`), using `globs`
|
||
1989 | as globals. Optional argument `name` is used in failure messages.
|
||
1990 | If the optional argument `verbose` is true, then generate output
|
||
1991 | even if there are no failures.
|
||
1992 |
|
||
1993 | `compileflags` gives the set of flags that should be used by the
|
||
1994 | Python compiler when running the examples. If not specified, then
|
||
1995 | it will default to the set of future-import flags that apply to
|
||
1996 | `globs`.
|
||
1997 |
|
||
1998 | Optional keyword arg `optionflags` specifies options for the
|
||
1999 | testing and output. See the documentation for `testmod` for more
|
||
2000 | information.
|
||
2001 | """
|
||
2002 | # Find, parse, and run all tests in the given module.
|
||
2003 | finder = DocTestFinder(verbose=verbose, recurse=False)
|
||
2004 | runner = DocTestRunner(verbose=verbose, optionflags=optionflags) |
||
2005 | for test in finder.find(f, name, globs=globs): |
||
2006 | runner.run(test, compileflags=compileflags) |
||
2007 | |||
2008 | ######################################################################
|
||
2009 | ## 7. Tester
|
||
2010 | ######################################################################
|
||
2011 | # This is provided only for backwards compatibility. It's not
|
||
2012 | # actually used in any way.
|
||
2013 | |||
2014 | class Tester: |
||
2015 | def __init__(self, mod=None, globs=None, verbose=None, |
||
2016 | isprivate=None, optionflags=0): |
||
2017 | |||
2018 | warnings.warn("class Tester is deprecated; "
|
||
2019 | "use class doctest.DocTestRunner instead",
|
||
2020 | DeprecationWarning, stacklevel=2) |
||
2021 | if mod is None and globs is None: |
||
2022 | raise TypeError("Tester.__init__: must specify mod or globs") |
||
2023 | if mod is not None and not inspect.ismodule(mod): |
||
2024 | raise TypeError("Tester.__init__: mod must be a module; %r" % |
||
2025 | (mod,)) |
||
2026 | if globs is None: |
||
2027 | globs = mod.__dict__ |
||
2028 | self.globs = globs
|
||
2029 | |||
2030 | self.verbose = verbose
|
||
2031 | self.isprivate = isprivate
|
||
2032 | self.optionflags = optionflags
|
||
2033 | self.testfinder = DocTestFinder(_namefilter=isprivate)
|
||
2034 | self.testrunner = DocTestRunner(verbose=verbose,
|
||
2035 | optionflags=optionflags) |
||
2036 | |||
2037 | def runstring(self, s, name): |
||
2038 | test = DocTestParser().get_doctest(s, self.globs, name, None, None) |
||
2039 | if self.verbose: |
||
2040 | print "Running string", name |
||
2041 | (f,t) = self.testrunner.run(test)
|
||
2042 | if self.verbose: |
||
2043 | print f, "of", t, "examples failed in string", name |
||
2044 | return (f,t)
|
||
2045 | |||
2046 | def rundoc(self, object, name=None, module=None): |
||
2047 | f = t = 0
|
||
2048 | tests = self.testfinder.find(object, name, module=module, |
||
2049 | globs=self.globs)
|
||
2050 | for test in tests: |
||
2051 | (f2, t2) = self.testrunner.run(test)
|
||
2052 | (f,t) = (f+f2, t+t2) |
||
2053 | return (f,t)
|
||
2054 | |||
2055 | def rundict(self, d, name, module=None): |
||
2056 | import types |
||
2057 | m = types.ModuleType(name) |
||
2058 | m.__dict__.update(d) |
||
2059 | if module is None: |
||
2060 | module = False
|
||
2061 | return self.rundoc(m, name, module) |
||
2062 | |||
2063 | def run__test__(self, d, name): |
||
2064 | import types |
||
2065 | m = types.ModuleType(name) |
||
2066 | m.__test__ = d |
||
2067 | return self.rundoc(m, name) |
||
2068 | |||
2069 | def summarize(self, verbose=None): |
||
2070 | return self.testrunner.summarize(verbose) |
||
2071 | |||
2072 | def merge(self, other): |
||
2073 | self.testrunner.merge(other.testrunner)
|
||
2074 | |||
2075 | ######################################################################
|
||
2076 | ## 8. Unittest Support
|
||
2077 | ######################################################################
|
||
2078 | |||
2079 | _unittest_reportflags = 0
|
||
2080 | |||
2081 | def set_unittest_reportflags(flags): |
||
2082 | """Sets the unittest option flags.
|
||
2083 |
|
||
2084 | The old flag is returned so that a runner could restore the old
|
||
2085 | value if it wished to:
|
||
2086 |
|
||
2087 | >>> old = _unittest_reportflags
|
||
2088 | >>> set_unittest_reportflags(REPORT_NDIFF |
|
||
2089 | ... REPORT_ONLY_FIRST_FAILURE) == old
|
||
2090 | True
|
||
2091 |
|
||
2092 | >>> import doctest
|
||
2093 | >>> doctest._unittest_reportflags == (REPORT_NDIFF |
|
||
2094 | ... REPORT_ONLY_FIRST_FAILURE)
|
||
2095 | True
|
||
2096 |
|
||
2097 | Only reporting flags can be set:
|
||
2098 |
|
||
2099 | >>> set_unittest_reportflags(ELLIPSIS)
|
||
2100 | Traceback (most recent call last):
|
||
2101 | ...
|
||
2102 | ValueError: ('Only reporting flags allowed', 8)
|
||
2103 |
|
||
2104 | >>> set_unittest_reportflags(old) == (REPORT_NDIFF |
|
||
2105 | ... REPORT_ONLY_FIRST_FAILURE)
|
||
2106 | True
|
||
2107 | """
|
||
2108 | global _unittest_reportflags
|
||
2109 | |||
2110 | if (flags & REPORTING_FLAGS) != flags:
|
||
2111 | raise ValueError("Only reporting flags allowed", flags) |
||
2112 | old = _unittest_reportflags |
||
2113 | _unittest_reportflags = flags |
||
2114 | return old
|
||
2115 | |||
2116 | |||
2117 | class DocTestCase(unittest.TestCase): |
||
2118 | |||
2119 | def __init__(self, test, optionflags=0, setUp=None, tearDown=None, |
||
2120 | checker=None):
|
||
2121 | |||
2122 | unittest.TestCase.__init__(self)
|
||
2123 | self._dt_optionflags = optionflags
|
||
2124 | self._dt_checker = checker
|
||
2125 | self._dt_test = test
|
||
2126 | self._dt_setUp = setUp
|
||
2127 | self._dt_tearDown = tearDown
|
||
2128 | |||
2129 | def setUp(self): |
||
2130 | test = self._dt_test
|
||
2131 | |||
2132 | if self._dt_setUp is not None: |
||
2133 | self._dt_setUp(test)
|
||
2134 | |||
2135 | def tearDown(self): |
||
2136 | test = self._dt_test
|
||
2137 | |||
2138 | if self._dt_tearDown is not None: |
||
2139 | self._dt_tearDown(test)
|
||
2140 | |||
2141 | test.globs.clear() |
||
2142 | |||
2143 | def runTest(self): |
||
2144 | test = self._dt_test
|
||
2145 | old = sys.stdout |
||
2146 | new = StringIO() |
||
2147 | optionflags = self._dt_optionflags
|
||
2148 | |||
2149 | if not (optionflags & REPORTING_FLAGS): |
||
2150 | # The option flags don't include any reporting flags,
|
||
2151 | # so add the default reporting flags
|
||
2152 | optionflags |= _unittest_reportflags |
||
2153 | |||
2154 | runner = DocTestRunner(optionflags=optionflags, |
||
2155 | checker=self._dt_checker, verbose=False) |
||
2156 | |||
2157 | try:
|
||
2158 | runner.DIVIDER = "-"*70 |
||
2159 | failures, tries = runner.run( |
||
2160 | test, out=new.write, clear_globs=False)
|
||
2161 | finally:
|
||
2162 | sys.stdout = old |
||
2163 | |||
2164 | if failures:
|
||
2165 | raise self.failureException(self.format_failure(new.getvalue())) |
||
2166 | |||
2167 | def format_failure(self, err): |
||
2168 | test = self._dt_test
|
||
2169 | if test.lineno is None: |
||
2170 | lineno = 'unknown line number'
|
||
2171 | else:
|
||
2172 | lineno = '%s' % test.lineno
|
||
2173 | lname = '.'.join(test.name.split('.')[-1:]) |
||
2174 | return ('Failed doctest test for %s\n' |
||
2175 | ' File "%s", line %s, in %s\n\n%s'
|
||
2176 | % (test.name, test.filename, lineno, lname, err) |
||
2177 | ) |
||
2178 | |||
2179 | def debug(self): |
||
2180 | r"""Run the test case without results and without catching exceptions
|
||
2181 |
|
||
2182 | The unit test framework includes a debug method on test cases
|
||
2183 | and test suites to support post-mortem debugging. The test code
|
||
2184 | is run in such a way that errors are not caught. This way a
|
||
2185 | caller can catch the errors and initiate post-mortem debugging.
|
||
2186 |
|
||
2187 | The DocTestCase provides a debug method that raises
|
||
2188 | UnexpectedException errors if there is an unexepcted
|
||
2189 | exception:
|
||
2190 |
|
||
2191 | >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
|
||
2192 | ... {}, 'foo', 'foo.py', 0)
|
||
2193 | >>> case = DocTestCase(test)
|
||
2194 | >>> try:
|
||
2195 | ... case.debug()
|
||
2196 | ... except UnexpectedException, failure:
|
||
2197 | ... pass
|
||
2198 |
|
||
2199 | The UnexpectedException contains the test, the example, and
|
||
2200 | the original exception:
|
||
2201 |
|
||
2202 | >>> failure.test is test
|
||
2203 | True
|
||
2204 |
|
||
2205 | >>> failure.example.want
|
||
2206 | '42\n'
|
||
2207 |
|
||
2208 | >>> exc_info = failure.exc_info
|
||
2209 | >>> raise exc_info[0], exc_info[1], exc_info[2]
|
||
2210 | Traceback (most recent call last):
|
||
2211 | ...
|
||
2212 | KeyError
|
||
2213 |
|
||
2214 | If the output doesn't match, then a DocTestFailure is raised:
|
||
2215 |
|
||
2216 | >>> test = DocTestParser().get_doctest('''
|
||
2217 | ... >>> x = 1
|
||
2218 | ... >>> x
|
||
2219 | ... 2
|
||
2220 | ... ''', {}, 'foo', 'foo.py', 0)
|
||
2221 | >>> case = DocTestCase(test)
|
||
2222 |
|
||
2223 | >>> try:
|
||
2224 | ... case.debug()
|
||
2225 | ... except DocTestFailure, failure:
|
||
2226 | ... pass
|
||
2227 |
|
||
2228 | DocTestFailure objects provide access to the test:
|
||
2229 |
|
||
2230 | >>> failure.test is test
|
||
2231 | True
|
||
2232 |
|
||
2233 | As well as to the example:
|
||
2234 |
|
||
2235 | >>> failure.example.want
|
||
2236 | '2\n'
|
||
2237 |
|
||
2238 | and the actual output:
|
||
2239 |
|
||
2240 | >>> failure.got
|
||
2241 | '1\n'
|
||
2242 |
|
||
2243 | """
|
||
2244 | |||
2245 | self.setUp()
|
||
2246 | runner = DebugRunner(optionflags=self._dt_optionflags,
|
||
2247 | checker=self._dt_checker, verbose=False) |
||
2248 | runner.run(self._dt_test)
|
||
2249 | self.tearDown()
|
||
2250 | |||
2251 | def id(self): |
||
2252 | return self._dt_test.name |
||
2253 | |||
2254 | def __repr__(self): |
||
2255 | name = self._dt_test.name.split('.') |
||
2256 | return "%s (%s)" % (name[-1], '.'.join(name[:-1])) |
||
2257 | |||
2258 | __str__ = __repr__ |
||
2259 | |||
2260 | def shortDescription(self): |
||
2261 | return "Doctest: " + self._dt_test.name |
||
2262 | |||
2263 | def DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None, |
||
2264 | **options): |
||
2265 | """
|
||
2266 | Convert doctest tests for a module to a unittest test suite.
|
||
2267 |
|
||
2268 | This converts each documentation string in a module that
|
||
2269 | contains doctest tests to a unittest test case. If any of the
|
||
2270 | tests in a doc string fail, then the test case fails. An exception
|
||
2271 | is raised showing the name of the file containing the test and a
|
||
2272 | (sometimes approximate) line number.
|
||
2273 |
|
||
2274 | The `module` argument provides the module to be tested. The argument
|
||
2275 | can be either a module or a module name.
|
||
2276 |
|
||
2277 | If no argument is given, the calling module is used.
|
||
2278 |
|
||
2279 | A number of options may be provided as keyword arguments:
|
||
2280 |
|
||
2281 | setUp
|
||
2282 | A set-up function. This is called before running the
|
||
2283 | tests in each file. The setUp function will be passed a DocTest
|
||
2284 | object. The setUp function can access the test globals as the
|
||
2285 | globs attribute of the test passed.
|
||
2286 |
|
||
2287 | tearDown
|
||
2288 | A tear-down function. This is called after running the
|
||
2289 | tests in each file. The tearDown function will be passed a DocTest
|
||
2290 | object. The tearDown function can access the test globals as the
|
||
2291 | globs attribute of the test passed.
|
||
2292 |
|
||
2293 | globs
|
||
2294 | A dictionary containing initial global variables for the tests.
|
||
2295 |
|
||
2296 | optionflags
|
||
2297 | A set of doctest option flags expressed as an integer.
|
||
2298 | """
|
||
2299 | |||
2300 | if test_finder is None: |
||
2301 | test_finder = DocTestFinder() |
||
2302 | |||
2303 | module = _normalize_module(module) |
||
2304 | tests = test_finder.find(module, globs=globs, extraglobs=extraglobs) |
||
2305 | if globs is None: |
||
2306 | globs = module.__dict__ |
||
2307 | if not tests: |
||
2308 | # Why do we want to do this? Because it reveals a bug that might
|
||
2309 | # otherwise be hidden.
|
||
2310 | raise ValueError(module, "has no tests") |
||
2311 | |||
2312 | tests.sort() |
||
2313 | suite = unittest.TestSuite() |
||
2314 | for test in tests: |
||
2315 | if len(test.examples) == 0: |
||
2316 | continue
|
||
2317 | if not test.filename: |
||
2318 | filename = module.__file__ |
||
2319 | if filename[-4:] in (".pyc", ".pyo"): |
||
2320 | filename = filename[:-1]
|
||
2321 | test.filename = filename |
||
2322 | suite.addTest(DocTestCase(test, **options)) |
||
2323 | |||
2324 | return suite
|
||
2325 | |||
2326 | class DocFileCase(DocTestCase): |
||
2327 | |||
2328 | def id(self): |
||
2329 | return '_'.join(self._dt_test.name.split('.')) |
||
2330 | |||
2331 | def __repr__(self): |
||
2332 | return self._dt_test.filename |
||
2333 | __str__ = __repr__ |
||
2334 | |||
2335 | def format_failure(self, err): |
||
2336 | return ('Failed doctest test for %s\n File "%s", line 0\n\n%s' |
||
2337 | % (self._dt_test.name, self._dt_test.filename, err) |
||
2338 | ) |
||
2339 | |||
2340 | def DocFileTest(path, module_relative=True, package=None, |
||
2341 | globs=None, parser=DocTestParser(), **options):
|
||
2342 | if globs is None: |
||
2343 | globs = {} |
||
2344 | |||
2345 | if package and not module_relative: |
||
2346 | raise ValueError("Package may only be specified for module-" |
||
2347 | "relative paths.")
|
||
2348 | |||
2349 | # Relativize the path.
|
||
2350 | if module_relative:
|
||
2351 | package = _normalize_module(package) |
||
2352 | path = _module_relative_path(package, path) |
||
2353 | |||
2354 | # Find the file and read it.
|
||
2355 | name = os.path.basename(path) |
||
2356 | doc = open(path).read()
|
||
2357 | |||
2358 | # Convert it to a test, and wrap it in a DocFileCase.
|
||
2359 | test = parser.get_doctest(doc, globs, name, path, 0)
|
||
2360 | return DocFileCase(test, **options)
|
||
2361 | |||
2362 | def DocFileSuite(*paths, **kw): |
||
2363 | """A unittest suite for one or more doctest files.
|
||
2364 |
|
||
2365 | The path to each doctest file is given as a string; the
|
||
2366 | interpretation of that string depends on the keyword argument
|
||
2367 | "module_relative".
|
||
2368 |
|
||
2369 | A number of options may be provided as keyword arguments:
|
||
2370 |
|
||
2371 | module_relative
|
||
2372 | If "module_relative" is True, then the given file paths are
|
||
2373 | interpreted as os-independent module-relative paths. By
|
||
2374 | default, these paths are relative to the calling module's
|
||
2375 | directory; but if the "package" argument is specified, then
|
||
2376 | they are relative to that package. To ensure os-independence,
|
||
2377 | "filename" should use "/" characters to separate path
|
||
2378 | segments, and may not be an absolute path (i.e., it may not
|
||
2379 | begin with "/").
|
||
2380 |
|
||
2381 | If "module_relative" is False, then the given file paths are
|
||
2382 | interpreted as os-specific paths. These paths may be absolute
|
||
2383 | or relative (to the current working directory).
|
||
2384 |
|
||
2385 | package
|
||
2386 | A Python package or the name of a Python package whose directory
|
||
2387 | should be used as the base directory for module relative paths.
|
||
2388 | If "package" is not specified, then the calling module's
|
||
2389 | directory is used as the base directory for module relative
|
||
2390 | filenames. It is an error to specify "package" if
|
||
2391 | "module_relative" is False.
|
||
2392 |
|
||
2393 | setUp
|
||
2394 | A set-up function. This is called before running the
|
||
2395 | tests in each file. The setUp function will be passed a DocTest
|
||
2396 | object. The setUp function can access the test globals as the
|
||
2397 | globs attribute of the test passed.
|
||
2398 |
|
||
2399 | tearDown
|
||
2400 | A tear-down function. This is called after running the
|
||
2401 | tests in each file. The tearDown function will be passed a DocTest
|
||
2402 | object. The tearDown function can access the test globals as the
|
||
2403 | globs attribute of the test passed.
|
||
2404 |
|
||
2405 | globs
|
||
2406 | A dictionary containing initial global variables for the tests.
|
||
2407 |
|
||
2408 | optionflags
|
||
2409 | A set of doctest option flags expressed as an integer.
|
||
2410 |
|
||
2411 | parser
|
||
2412 | A DocTestParser (or subclass) that should be used to extract
|
||
2413 | tests from the files.
|
||
2414 | """
|
||
2415 | suite = unittest.TestSuite() |
||
2416 | |||
2417 | # We do this here so that _normalize_module is called at the right
|
||
2418 | # level. If it were called in DocFileTest, then this function
|
||
2419 | # would be the caller and we might guess the package incorrectly.
|
||
2420 | if kw.get('module_relative', True): |
||
2421 | kw['package'] = _normalize_module(kw.get('package')) |
||
2422 | |||
2423 | for path in paths: |
||
2424 | suite.addTest(DocFileTest(path, **kw)) |
||
2425 | |||
2426 | return suite
|
||
2427 | |||
2428 | ######################################################################
|
||
2429 | ## 9. Debugging Support
|
||
2430 | ######################################################################
|
||
2431 | |||
2432 | def script_from_examples(s): |
||
2433 | r"""Extract script from text with examples.
|
||
2434 |
|
||
2435 | Converts text with examples to a Python script. Example input is
|
||
2436 | converted to regular code. Example output and all other words
|
||
2437 | are converted to comments:
|
||
2438 |
|
||
2439 | >>> text = '''
|
||
2440 | ... Here are examples of simple math.
|
||
2441 | ...
|
||
2442 | ... Python has super accurate integer addition
|
||
2443 | ...
|
||
2444 | ... >>> 2 + 2
|
||
2445 | ... 5
|
||
2446 | ...
|
||
2447 | ... And very friendly error messages:
|
||
2448 | ...
|
||
2449 | ... >>> 1/0
|
||
2450 | ... To Infinity
|
||
2451 | ... And
|
||
2452 | ... Beyond
|
||
2453 | ...
|
||
2454 | ... You can use logic if you want:
|
||
2455 | ...
|
||
2456 | ... >>> if 0:
|
||
2457 | ... ... blah
|
||
2458 | ... ... blah
|
||
2459 | ... ...
|
||
2460 | ...
|
||
2461 | ... Ho hum
|
||
2462 | ... '''
|
||
2463 |
|
||
2464 | >>> print script_from_examples(text)
|
||
2465 | # Here are examples of simple math.
|
||
2466 | #
|
||
2467 | # Python has super accurate integer addition
|
||
2468 | #
|
||
2469 | 2 + 2
|
||
2470 | # Expected:
|
||
2471 | ## 5
|
||
2472 | #
|
||
2473 | # And very friendly error messages:
|
||
2474 | #
|
||
2475 | 1/0
|
||
2476 | # Expected:
|
||
2477 | ## To Infinity
|
||
2478 | ## And
|
||
2479 | ## Beyond
|
||
2480 | #
|
||
2481 | # You can use logic if you want:
|
||
2482 | #
|
||
2483 | if 0:
|
||
2484 | blah
|
||
2485 | blah
|
||
2486 | #
|
||
2487 | # Ho hum
|
||
2488 | """
|
||
2489 | output = [] |
||
2490 | for piece in DocTestParser().parse(s): |
||
2491 | if isinstance(piece, Example): |
||
2492 | # Add the example's source code (strip trailing NL)
|
||
2493 | output.append(piece.source[:-1])
|
||
2494 | # Add the expected output:
|
||
2495 | want = piece.want |
||
2496 | if want:
|
||
2497 | output.append('# Expected:')
|
||
2498 | output += ['## '+l for l in want.split('\n')[:-1]] |
||
2499 | else:
|
||
2500 | # Add non-example text.
|
||
2501 | output += [_comment_line(l) |
||
2502 | for l in piece.split('\n')[:-1]] |
||
2503 | |||
2504 | # Trim junk on both ends.
|
||
2505 | while output and output[-1] == '#': |
||
2506 | output.pop() |
||
2507 | while output and output[0] == '#': |
||
2508 | output.pop(0)
|
||
2509 | # Combine the output, and return it.
|
||
2510 | return '\n'.join(output) |
||
2511 | |||
2512 | def testsource(module, name): |
||
2513 | """Extract the test sources from a doctest docstring as a script.
|
||
2514 |
|
||
2515 | Provide the module (or dotted name of the module) containing the
|
||
2516 | test to be debugged and the name (within the module) of the object
|
||
2517 | with the doc string with tests to be debugged.
|
||
2518 | """
|
||
2519 | module = _normalize_module(module) |
||
2520 | tests = DocTestFinder().find(module) |
||
2521 | test = [t for t in tests if t.name == name] |
||
2522 | if not test: |
||
2523 | raise ValueError(name, "not found in tests") |
||
2524 | test = test[0]
|
||
2525 | testsrc = script_from_examples(test.docstring) |
||
2526 | return testsrc
|
||
2527 | |||
2528 | def debug_src(src, pm=False, globs=None): |
||
2529 | """Debug a single doctest docstring, in argument `src`'"""
|
||
2530 | testsrc = script_from_examples(src) |
||
2531 | debug_script(testsrc, pm, globs) |
||
2532 | |||
2533 | def debug_script(src, pm=False, globs=None): |
||
2534 | "Debug a test script. `src` is the script, as a string."
|
||
2535 | import pdb |
||
2536 | |||
2537 | # Note that tempfile.NameTemporaryFile() cannot be used. As the
|
||
2538 | # docs say, a file so created cannot be opened by name a second time
|
||
2539 | # on modern Windows boxes, and execfile() needs to open it.
|
||
2540 | srcfilename = tempfile.mktemp(".py", "doctestdebug") |
||
2541 | f = open(srcfilename, 'w') |
||
2542 | f.write(src) |
||
2543 | f.close() |
||
2544 | |||
2545 | try:
|
||
2546 | if globs:
|
||
2547 | globs = globs.copy() |
||
2548 | else:
|
||
2549 | globs = {} |
||
2550 | |||
2551 | if pm:
|
||
2552 | try:
|
||
2553 | execfile(srcfilename, globs, globs)
|
||
2554 | except:
|
||
2555 | print sys.exc_info()[1] |
||
2556 | pdb.post_mortem(sys.exc_info()[2])
|
||
2557 | else:
|
||
2558 | # Note that %r is vital here. '%s' instead can, e.g., cause
|
||
2559 | # backslashes to get treated as metacharacters on Windows.
|
||
2560 | pdb.run("execfile(%r)" % srcfilename, globs, globs)
|
||
2561 | |||
2562 | finally:
|
||
2563 | os.remove(srcfilename) |
||
2564 | |||
2565 | def debug(module, name, pm=False): |
||
2566 | """Debug a single doctest docstring.
|
||
2567 |
|
||
2568 | Provide the module (or dotted name of the module) containing the
|
||
2569 | test to be debugged and the name (within the module) of the object
|
||
2570 | with the docstring with tests to be debugged.
|
||
2571 | """
|
||
2572 | module = _normalize_module(module) |
||
2573 | testsrc = testsource(module, name) |
||
2574 | debug_script(testsrc, pm, module.__dict__) |
||
2575 | |||
2576 | ######################################################################
|
||
2577 | ## 10. Example Usage
|
||
2578 | ######################################################################
|
||
2579 | class _TestClass: |
||
2580 | """
|
||
2581 | A pointless class, for sanity-checking of docstring testing.
|
||
2582 |
|
||
2583 | Methods:
|
||
2584 | square()
|
||
2585 | get()
|
||
2586 |
|
||
2587 | >>> _TestClass(13).get() + _TestClass(-12).get()
|
||
2588 | 1
|
||
2589 | >>> hex(_TestClass(13).square().get())
|
||
2590 | '0xa9'
|
||
2591 | """
|
||
2592 | |||
2593 | def __init__(self, val): |
||
2594 | """val -> _TestClass object with associated value val.
|
||
2595 |
|
||
2596 | >>> t = _TestClass(123)
|
||
2597 | >>> print t.get()
|
||
2598 | 123
|
||
2599 | """
|
||
2600 | |||
2601 | self.val = val
|
||
2602 | |||
2603 | def square(self): |
||
2604 | """square() -> square TestClass's associated value
|
||
2605 |
|
||
2606 | >>> _TestClass(13).square().get()
|
||
2607 | 169
|
||
2608 | """
|
||
2609 | |||
2610 | self.val = self.val ** 2 |
||
2611 | return self |
||
2612 | |||
2613 | def get(self): |
||
2614 | """get() -> return TestClass's associated value.
|
||
2615 |
|
||
2616 | >>> x = _TestClass(-42)
|
||
2617 | >>> print x.get()
|
||
2618 | -42
|
||
2619 | """
|
||
2620 | |||
2621 | return self.val |
||
2622 | |||
2623 | __test__ = {"_TestClass": _TestClass,
|
||
2624 | "string": r""" |
||
2625 | Example of a string object, searched as-is.
|
||
2626 | >>> x = 1; y = 2
|
||
2627 | >>> x + y, x * y
|
||
2628 | (3, 2)
|
||
2629 | """,
|
||
2630 | |||
2631 | "bool-int equivalence": r""" |
||
2632 | In 2.2, boolean expressions displayed
|
||
2633 | 0 or 1. By default, we still accept
|
||
2634 | them. This can be disabled by passing
|
||
2635 | DONT_ACCEPT_TRUE_FOR_1 to the new
|
||
2636 | optionflags argument.
|
||
2637 | >>> 4 == 4
|
||
2638 | 1
|
||
2639 | >>> 4 == 4
|
||
2640 | True
|
||
2641 | >>> 4 > 4
|
||
2642 | 0
|
||
2643 | >>> 4 > 4
|
||
2644 | False
|
||
2645 | """,
|
||
2646 | |||
2647 | "blank lines": r""" |
||
2648 | Blank lines can be marked with <BLANKLINE>:
|
||
2649 | >>> print 'foo\n\nbar\n'
|
||
2650 | foo
|
||
2651 | <BLANKLINE>
|
||
2652 | bar
|
||
2653 | <BLANKLINE>
|
||
2654 | """,
|
||
2655 | |||
2656 | "ellipsis": r""" |
||
2657 | If the ellipsis flag is used, then '...' can be used to
|
||
2658 | elide substrings in the desired output:
|
||
2659 | >>> print range(1000) #doctest: +ELLIPSIS
|
||
2660 | [0, 1, 2, ..., 999]
|
||
2661 | """,
|
||
2662 | |||
2663 | "whitespace normalization": r""" |
||
2664 | If the whitespace normalization flag is used, then
|
||
2665 | differences in whitespace are ignored.
|
||
2666 | >>> print range(30) #doctest: +NORMALIZE_WHITESPACE
|
||
2667 | [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
|
||
2668 | 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,
|
||
2669 | 27, 28, 29]
|
||
2670 | """,
|
||
2671 | } |
||
2672 | |||
2673 | def _test(): |
||
2674 | r = unittest.TextTestRunner() |
||
2675 | r.run(DocTestSuite()) |
||
2676 | |||
2677 | if __name__ == "__main__": |
||
2678 | _test() |