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