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