2
# Released to the public domain 16-Jan-2001, by Tim Peters (tim@python.org).
3
# Major enhancements and refactoring by:
7
# Provided as-is; use at your own risk; no warranty; no promises; enjoy!
9
r"""Module doctest -- a framework for running examples in docstrings.
11
In simplest use, end each module M to be tested with:
17
if __name__ == "__main__":
20
Then running the module as a script will cause the examples in the
21
docstrings to get executed and verified:
25
This won't display anything unless an example fails, in which case the
26
failing example(s) and the cause(s) of the failure(s) are printed to stdout
27
(why not stderr? because stderr is a lame hack <0.2 wink>), and the final
28
line of output is "Test failed.".
30
Run it with the -v switch instead:
34
and a detailed report of all examples tried is printed to stdout, along
35
with assorted summaries at the end.
37
You can force verbose mode by passing "verbose=True" to testmod, or prohibit
38
it by passing "verbose=False". In either of those cases, sys.argv is not
41
There are a variety of other ways to run doctests, including integration
42
with the unittest framework, and support for running non-Python text
43
files containing doctests. There are also many ways to override parts
44
of doctest's default behaviors. See the Library Reference Manual for
48
__docformat__ = 'reStructuredText en'
52
'register_optionflag',
53
'DONT_ACCEPT_TRUE_FOR_1',
54
'DONT_ACCEPT_BLANKLINE',
55
'NORMALIZE_WHITESPACE',
58
'IGNORE_EXCEPTION_DETAIL',
63
'REPORT_ONLY_FIRST_FAILURE',
65
# 1. Utility Functions
66
# 2. Example & DocTest
77
'UnexpectedException',
82
'run_docstring_examples',
88
'set_unittest_reportflags',
89
# 9. Debugging Support
90
'script_from_examples',
98
import sys, traceback, inspect, linecache, os, re
99
import unittest, difflib, pdb, tempfile
101
from StringIO import StringIO
102
from collections import namedtuple
104
TestResults = namedtuple('TestResults', 'failed attempted')
106
# There are 4 basic classes:
107
# - Example: a <source, want> pair, plus an intra-docstring line number.
108
# - DocTest: a collection of examples, parsed from a docstring, plus
109
# info about where the docstring came from (name, filename, lineno).
110
# - DocTestFinder: extracts DocTests from a given object's docstring and
111
# its contained objects' docstrings.
112
# - DocTestRunner: runs DocTest cases, and accumulates statistics.
114
# So the basic picture is:
117
# +------+ +---------+ +-------+
118
# |object| --DocTestFinder-> | DocTest | --DocTestRunner-> |results|
119
# +------+ +---------+ +-------+
127
OPTIONFLAGS_BY_NAME = {}
128
def register_optionflag(name):
129
# Create a new flag unless `name` is already known.
130
return OPTIONFLAGS_BY_NAME.setdefault(name, 1 << len(OPTIONFLAGS_BY_NAME))
132
DONT_ACCEPT_TRUE_FOR_1 = register_optionflag('DONT_ACCEPT_TRUE_FOR_1')
133
DONT_ACCEPT_BLANKLINE = register_optionflag('DONT_ACCEPT_BLANKLINE')
134
NORMALIZE_WHITESPACE = register_optionflag('NORMALIZE_WHITESPACE')
135
ELLIPSIS = register_optionflag('ELLIPSIS')
136
SKIP = register_optionflag('SKIP')
137
IGNORE_EXCEPTION_DETAIL = register_optionflag('IGNORE_EXCEPTION_DETAIL')
139
COMPARISON_FLAGS = (DONT_ACCEPT_TRUE_FOR_1 |
140
DONT_ACCEPT_BLANKLINE |
141
NORMALIZE_WHITESPACE |
144
IGNORE_EXCEPTION_DETAIL)
146
REPORT_UDIFF = register_optionflag('REPORT_UDIFF')
147
REPORT_CDIFF = register_optionflag('REPORT_CDIFF')
148
REPORT_NDIFF = register_optionflag('REPORT_NDIFF')
149
REPORT_ONLY_FIRST_FAILURE = register_optionflag('REPORT_ONLY_FIRST_FAILURE')
151
REPORTING_FLAGS = (REPORT_UDIFF |
154
REPORT_ONLY_FIRST_FAILURE)
156
# Special string markers for use in `want` strings:
157
BLANKLINE_MARKER = '<BLANKLINE>'
158
ELLIPSIS_MARKER = '...'
160
######################################################################
162
######################################################################
163
# 1. Utility Functions
164
# 2. Example & DocTest -- store test cases
165
# 3. DocTest Parser -- extracts examples from strings
166
# 4. DocTest Finder -- extracts test cases from objects
167
# 5. DocTest Runner -- runs test cases
168
# 6. Test Functions -- convenient wrappers for testing
169
# 7. Tester Class -- for backwards compatibility
170
# 8. Unittest Support
171
# 9. Debugging Support
174
######################################################################
175
## 1. Utility Functions
176
######################################################################
178
def _extract_future_flags(globs):
180
Return the compiler-flags associated with the future features that
181
have been imported into the given namespace (globs).
184
for fname in __future__.all_feature_names:
185
feature = globs.get(fname, None)
186
if feature is getattr(__future__, fname):
187
flags |= feature.compiler_flag
190
def _normalize_module(module, depth=2):
192
Return the module specified by `module`. In particular:
193
- If `module` is a module, then return module.
194
- If `module` is a string, then import and return the
195
module with that name.
196
- If `module` is None, then return the calling module.
197
The calling module is assumed to be the module of
198
the stack frame at the given depth in the call stack.
200
if inspect.ismodule(module):
202
elif isinstance(module, (str, unicode)):
203
return __import__(module, globals(), locals(), ["*"])
205
return sys.modules[sys._getframe(depth).f_globals['__name__']]
207
raise TypeError("Expected a module, string, or None")
209
def _load_testfile(filename, package, module_relative):
211
package = _normalize_module(package, 3)
212
filename = _module_relative_path(package, filename)
213
if hasattr(package, '__loader__'):
214
if hasattr(package.__loader__, 'get_data'):
215
file_contents = package.__loader__.get_data(filename)
216
# get_data() opens files as 'rb', so one must do the equivalent
217
# conversion as universal newlines would do.
218
return file_contents.replace(os.linesep, '\n'), filename
219
with open(filename) as f:
220
return f.read(), filename
222
# Use sys.stdout encoding for ouput.
223
_encoding = getattr(sys.__stdout__, 'encoding', None) or 'utf-8'
225
def _indent(s, indent=4):
227
Add the given number of space characters to the beginning of
228
every non-blank line in `s`, and return the result.
229
If the string `s` is Unicode, it is encoded using the stdout
230
encoding and the `backslashreplace` error handler.
232
if isinstance(s, unicode):
233
s = s.encode(_encoding, 'backslashreplace')
234
# This regexp matches the start of non-blank lines:
235
return re.sub('(?m)^(?!$)', indent*' ', s)
237
def _exception_traceback(exc_info):
239
Return a string containing a traceback message for the given
240
exc_info tuple (as returned by sys.exc_info()).
242
# Get a traceback message.
244
exc_type, exc_val, exc_tb = exc_info
245
traceback.print_exception(exc_type, exc_val, exc_tb, file=excout)
246
return excout.getvalue()
248
# Override some StringIO methods.
249
class _SpoofOut(StringIO):
251
result = StringIO.getvalue(self)
252
# If anything at all was written, make sure there's a trailing
253
# newline. There's no way for the expected output to indicate
254
# that a trailing newline is missing.
255
if result and not result.endswith("\n"):
257
# Prevent softspace from screwing up the next test case, in
258
# case they used print with a trailing comma in an example.
259
if hasattr(self, "softspace"):
263
def truncate(self, size=None):
264
StringIO.truncate(self, size)
265
if hasattr(self, "softspace"):
268
# Reset it to an empty string, to make sure it's not unicode.
271
# Worst-case linear-time ellipsis matching.
272
def _ellipsis_match(want, got):
274
Essentially the only subtle case:
275
>>> _ellipsis_match('aa...aa', 'aaa')
278
if ELLIPSIS_MARKER not in want:
281
# Find "the real" strings.
282
ws = want.split(ELLIPSIS_MARKER)
285
# Deal with exact matches possibly needed at one or both ends.
286
startpos, endpos = 0, len(got)
288
if w: # starts with exact match
289
if got.startswith(w):
295
if w: # ends with exact match
302
if startpos > endpos:
303
# Exact end matches required more characters than we have, as in
304
# _ellipsis_match('aa...aa', 'aaa')
307
# For the rest, we only need to find the leftmost non-overlapping
308
# match for each piece. If there's no overall match that way alone,
309
# there's no overall match period.
311
# w may be '' at times, if there are consecutive ellipses, or
312
# due to an ellipsis at the start or end of `want`. That's OK.
313
# Search for an empty string succeeds, and doesn't change startpos.
314
startpos = got.find(w, startpos, endpos)
321
def _comment_line(line):
322
"Return a commented form of the given line"
329
class _OutputRedirectingPdb(pdb.Pdb):
331
A specialized version of the python debugger that redirects stdout
332
to a given stream when interacting with the user. Stdout is *not*
333
redirected when traced code is executed.
335
def __init__(self, out):
337
self.__debugger_used = False
338
pdb.Pdb.__init__(self, stdout=out)
339
# still use input() to get user input
340
self.use_rawinput = 1
342
def set_trace(self, frame=None):
343
self.__debugger_used = True
345
frame = sys._getframe().f_back
346
pdb.Pdb.set_trace(self, frame)
348
def set_continue(self):
349
# Calling set_continue unconditionally would break unit test
350
# coverage reporting, as Bdb.set_continue calls sys.settrace(None).
351
if self.__debugger_used:
352
pdb.Pdb.set_continue(self)
354
def trace_dispatch(self, *args):
355
# Redirect stdout to the given stream.
356
save_stdout = sys.stdout
357
sys.stdout = self.__out
358
# Call Pdb's trace dispatch method.
360
return pdb.Pdb.trace_dispatch(self, *args)
362
sys.stdout = save_stdout
364
# [XX] Normalize with respect to os.path.pardir?
365
def _module_relative_path(module, path):
366
if not inspect.ismodule(module):
367
raise TypeError, 'Expected a module: %r' % module
368
if path.startswith('/'):
369
raise ValueError, 'Module-relative files may not have absolute paths'
371
# Find the base directory for the path.
372
if hasattr(module, '__file__'):
373
# A normal module/package
374
basedir = os.path.split(module.__file__)[0]
375
elif module.__name__ == '__main__':
376
# An interactive session.
377
if len(sys.argv)>0 and sys.argv[0] != '':
378
basedir = os.path.split(sys.argv[0])[0]
382
# A module w/o __file__ (this includes builtins)
383
raise ValueError("Can't resolve paths relative to the module " +
384
module + " (it has no __file__)")
386
# Combine the base directory and the path.
387
return os.path.join(basedir, *(path.split('/')))
389
######################################################################
390
## 2. Example & DocTest
391
######################################################################
392
## - An "example" is a <source, want> pair, where "source" is a
393
## fragment of source code, and "want" is the expected output for
394
## "source." The Example class also includes information about
395
## where the example was extracted from.
397
## - A "doctest" is a collection of examples, typically extracted from
398
## a string (such as an object's docstring). The DocTest class also
399
## includes information about where the string was extracted from.
403
A single doctest example, consisting of source code and expected
404
output. `Example` defines the following attributes:
406
- source: A single Python statement, always ending with a newline.
407
The constructor adds a newline if needed.
409
- want: The expected output from running the source code (either
410
from stdout, or a traceback in case of exception). `want` ends
411
with a newline unless it's empty, in which case it's an empty
412
string. The constructor adds a newline if needed.
414
- exc_msg: The exception message generated by the example, if
415
the example is expected to generate an exception; or `None` if
416
it is not expected to generate an exception. This exception
417
message is compared against the return value of
418
`traceback.format_exception_only()`. `exc_msg` ends with a
419
newline unless it's `None`. The constructor adds a newline
422
- lineno: The line number within the DocTest string containing
423
this Example where the Example begins. This line number is
424
zero-based, with respect to the beginning of the DocTest.
426
- indent: The example's indentation in the DocTest string.
427
I.e., the number of space characters that preceed the
428
example's first prompt.
430
- options: A dictionary mapping from option flags to True or
431
False, which is used to override default options for this
432
example. Any option flags not contained in this dictionary
433
are left at their default value (as specified by the
434
DocTestRunner's optionflags). By default, no options are set.
436
def __init__(self, source, want, exc_msg=None, lineno=0, indent=0,
439
if not source.endswith('\n'):
441
if want and not want.endswith('\n'):
443
if exc_msg is not None and not exc_msg.endswith('\n'):
450
if options is None: options = {}
451
self.options = options
452
self.exc_msg = exc_msg
456
A collection of doctest examples that should be run in a single
457
namespace. Each `DocTest` defines the following attributes:
459
- examples: the list of examples.
461
- globs: The namespace (aka globals) that the examples should
464
- name: A name identifying the DocTest (typically, the name of
465
the object whose docstring this DocTest was extracted from).
467
- filename: The name of the file that this DocTest was extracted
468
from, or `None` if the filename is unknown.
470
- lineno: The line number within filename where this DocTest
471
begins, or `None` if the line number is unavailable. This
472
line number is zero-based, with respect to the beginning of
475
- docstring: The string that the examples were extracted from,
476
or `None` if the string is unavailable.
478
def __init__(self, examples, globs, name, filename, lineno, docstring):
480
Create a new DocTest containing the given examples. The
481
DocTest's globals are initialized with a copy of `globs`.
483
assert not isinstance(examples, basestring), \
484
"DocTest no longer accepts str; use DocTestParser instead"
485
self.examples = examples
486
self.docstring = docstring
487
self.globs = globs.copy()
489
self.filename = filename
493
if len(self.examples) == 0:
494
examples = 'no examples'
495
elif len(self.examples) == 1:
496
examples = '1 example'
498
examples = '%d examples' % len(self.examples)
499
return ('<DocTest %s from %s:%s (%s)>' %
500
(self.name, self.filename, self.lineno, examples))
503
# This lets us sort tests by name:
504
def __cmp__(self, other):
505
if not isinstance(other, DocTest):
507
return cmp((self.name, self.filename, self.lineno, id(self)),
508
(other.name, other.filename, other.lineno, id(other)))
510
######################################################################
512
######################################################################
516
A class used to parse strings containing doctest examples.
518
# This regular expression is used to find doctest examples in a
519
# string. It defines three groups: `source` is the source code
520
# (including leading indentation and prompts); `indent` is the
521
# indentation of the first (PS1) line of the source code; and
522
# `want` is the expected output (including leading indentation).
523
_EXAMPLE_RE = re.compile(r'''
524
# Source consists of a PS1 line followed by zero or more PS2 lines.
526
(?:^(?P<indent> [ ]*) >>> .*) # PS1 line
527
(?:\n [ ]* \.\.\. .*)*) # PS2 lines
529
# Want consists of any non-blank lines that do not start with PS1.
530
(?P<want> (?:(?![ ]*$) # Not a blank line
531
(?![ ]*>>>) # Not a line starting with PS1
532
.*$\n? # But any other line
534
''', re.MULTILINE | re.VERBOSE)
536
# A regular expression for handling `want` strings that contain
537
# expected exceptions. It divides `want` into three pieces:
538
# - the traceback header line (`hdr`)
539
# - the traceback stack (`stack`)
540
# - the exception message (`msg`), as generated by
541
# traceback.format_exception_only()
542
# `msg` may have multiple lines. We assume/require that the
543
# exception message is the first non-indented line starting with a word
544
# character following the traceback header line.
545
_EXCEPTION_RE = re.compile(r"""
546
# Grab the traceback header. Different versions of Python have
547
# said different things on the first traceback line.
548
^(?P<hdr> Traceback\ \(
549
(?: most\ recent\ call\ last
553
\s* $ # toss trailing whitespace on the header.
554
(?P<stack> .*?) # don't blink: absorb stuff until...
555
^ (?P<msg> \w+ .*) # a line *starts* with alphanum.
556
""", re.VERBOSE | re.MULTILINE | re.DOTALL)
558
# A callable returning a true value iff its argument is a blank line
559
# or contains a single comment.
560
_IS_BLANK_OR_COMMENT = re.compile(r'^[ ]*(#.*)?$').match
562
def parse(self, string, name='<string>'):
564
Divide the given string into examples and intervening text,
565
and return them as a list of alternating Examples and strings.
566
Line numbers for the Examples are 0-based. The optional
567
argument `name` is a name identifying this string, and is only
568
used for error messages.
570
string = string.expandtabs()
571
# If all lines begin with the same indentation, then strip it.
572
min_indent = self._min_indent(string)
574
string = '\n'.join([l[min_indent:] for l in string.split('\n')])
577
charno, lineno = 0, 0
578
# Find all doctest examples in the string:
579
for m in self._EXAMPLE_RE.finditer(string):
580
# Add the pre-example text to `output`.
581
output.append(string[charno:m.start()])
582
# Update lineno (lines before this example)
583
lineno += string.count('\n', charno, m.start())
584
# Extract info from the regexp match.
585
(source, options, want, exc_msg) = \
586
self._parse_example(m, name, lineno)
587
# Create an Example, and add it to the list.
588
if not self._IS_BLANK_OR_COMMENT(source):
589
output.append( Example(source, want, exc_msg,
591
indent=min_indent+len(m.group('indent')),
593
# Update lineno (lines inside this example)
594
lineno += string.count('\n', m.start(), m.end())
597
# Add any remaining post-example text to `output`.
598
output.append(string[charno:])
601
def get_doctest(self, string, globs, name, filename, lineno):
603
Extract all doctest examples from the given string, and
604
collect them into a `DocTest` object.
606
`globs`, `name`, `filename`, and `lineno` are attributes for
607
the new `DocTest` object. See the documentation for `DocTest`
608
for more information.
610
return DocTest(self.get_examples(string, name), globs,
611
name, filename, lineno, string)
613
def get_examples(self, string, name='<string>'):
615
Extract all doctest examples from the given string, and return
616
them as a list of `Example` objects. Line numbers are
617
0-based, because it's most common in doctests that nothing
618
interesting appears on the same line as opening triple-quote,
619
and so the first interesting line is called \"line 1\" then.
621
The optional argument `name` is a name identifying this
622
string, and is only used for error messages.
624
return [x for x in self.parse(string, name)
625
if isinstance(x, Example)]
627
def _parse_example(self, m, name, lineno):
629
Given a regular expression match from `_EXAMPLE_RE` (`m`),
630
return a pair `(source, want)`, where `source` is the matched
631
example's source code (with prompts and indentation stripped);
632
and `want` is the example's expected output (with indentation
635
`name` is the string's name, and `lineno` is the line number
636
where the example starts; both are used for error messages.
638
# Get the example's indentation level.
639
indent = len(m.group('indent'))
641
# Divide source into lines; check that they're properly
642
# indented; and then strip their indentation & prompts.
643
source_lines = m.group('source').split('\n')
644
self._check_prompt_blank(source_lines, indent, name, lineno)
645
self._check_prefix(source_lines[1:], ' '*indent + '.', name, lineno)
646
source = '\n'.join([sl[indent+4:] for sl in source_lines])
648
# Divide want into lines; check that it's properly indented; and
649
# then strip the indentation. Spaces before the last newline should
650
# be preserved, so plain rstrip() isn't good enough.
651
want = m.group('want')
652
want_lines = want.split('\n')
653
if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]):
654
del want_lines[-1] # forget final newline & spaces after it
655
self._check_prefix(want_lines, ' '*indent, name,
656
lineno + len(source_lines))
657
want = '\n'.join([wl[indent:] for wl in want_lines])
659
# If `want` contains a traceback message, then extract it.
660
m = self._EXCEPTION_RE.match(want)
662
exc_msg = m.group('msg')
666
# Extract options from the source.
667
options = self._find_options(source, name, lineno)
669
return source, options, want, exc_msg
671
# This regular expression looks for option directives in the
672
# source code of an example. Option directives are comments
673
# starting with "doctest:". Warning: this may give false
674
# positives for string-literals that contain the string
675
# "#doctest:". Eliminating these false positives would require
676
# actually parsing the string; but we limit them by ignoring any
677
# line containing "#doctest:" that is *followed* by a quote mark.
678
_OPTION_DIRECTIVE_RE = re.compile(r'#\s*doctest:\s*([^\n\'"]*)$',
681
def _find_options(self, source, name, lineno):
683
Return a dictionary containing option overrides extracted from
684
option directives in the given source string.
686
`name` is the string's name, and `lineno` is the line number
687
where the example starts; both are used for error messages.
690
# (note: with the current regexp, this will match at most once:)
691
for m in self._OPTION_DIRECTIVE_RE.finditer(source):
692
option_strings = m.group(1).replace(',', ' ').split()
693
for option in option_strings:
694
if (option[0] not in '+-' or
695
option[1:] not in OPTIONFLAGS_BY_NAME):
696
raise ValueError('line %r of the doctest for %s '
697
'has an invalid option: %r' %
698
(lineno+1, name, option))
699
flag = OPTIONFLAGS_BY_NAME[option[1:]]
700
options[flag] = (option[0] == '+')
701
if options and self._IS_BLANK_OR_COMMENT(source):
702
raise ValueError('line %r of the doctest for %s has an option '
703
'directive on a line with no example: %r' %
704
(lineno, name, source))
707
# This regular expression finds the indentation of every non-blank
709
_INDENT_RE = re.compile('^([ ]*)(?=\S)', re.MULTILINE)
711
def _min_indent(self, s):
712
"Return the minimum indentation of any non-blank line in `s`"
713
indents = [len(indent) for indent in self._INDENT_RE.findall(s)]
719
def _check_prompt_blank(self, lines, indent, name, lineno):
721
Given the lines of a source string (including prompts and
722
leading indentation), check to make sure that every prompt is
723
followed by a space character. If any line is not followed by
724
a space character, then raise ValueError.
726
for i, line in enumerate(lines):
727
if len(line) >= indent+4 and line[indent+3] != ' ':
728
raise ValueError('line %r of the docstring for %s '
729
'lacks blank after %s: %r' %
731
line[indent:indent+3], line))
733
def _check_prefix(self, lines, prefix, name, lineno):
735
Check that every line in the given list starts with the given
736
prefix; if any line does not, then raise a ValueError.
738
for i, line in enumerate(lines):
739
if line and not line.startswith(prefix):
740
raise ValueError('line %r of the docstring for %s has '
741
'inconsistent leading whitespace: %r' %
742
(lineno+i+1, name, line))
745
######################################################################
747
######################################################################
751
A class used to extract the DocTests that are relevant to a given
752
object, from its docstring and the docstrings of its contained
753
objects. Doctests can currently be extracted from the following
754
object types: modules, functions, classes, methods, staticmethods,
755
classmethods, and properties.
758
def __init__(self, verbose=False, parser=DocTestParser(),
759
recurse=True, exclude_empty=True):
761
Create a new doctest finder.
763
The optional argument `parser` specifies a class or
764
function that should be used to create new DocTest objects (or
765
objects that implement the same interface as DocTest). The
766
signature for this factory function should match the signature
767
of the DocTest constructor.
769
If the optional argument `recurse` is false, then `find` will
770
only examine the given object, and not any contained objects.
772
If the optional argument `exclude_empty` is false, then `find`
773
will include tests for objects with empty docstrings.
775
self._parser = parser
776
self._verbose = verbose
777
self._recurse = recurse
778
self._exclude_empty = exclude_empty
780
def find(self, obj, name=None, module=None, globs=None, extraglobs=None):
782
Return a list of the DocTests that are defined by the given
783
object's docstring, or by any of its contained objects'
786
The optional parameter `module` is the module that contains
787
the given object. If the module is not specified or is None, then
788
the test finder will attempt to automatically determine the
789
correct module. The object's module is used:
791
- As a default namespace, if `globs` is not specified.
792
- To prevent the DocTestFinder from extracting DocTests
793
from objects that are imported from other modules.
794
- To find the name of the file containing the object.
795
- To help find the line number of the object within its
798
Contained objects whose module does not match `module` are ignored.
800
If `module` is False, no attempt to find the module will be made.
801
This is obscure, of use mostly in tests: if `module` is False, or
802
is None but cannot be found automatically, then all objects are
803
considered to belong to the (non-existent) module, so all contained
804
objects will (recursively) be searched for doctests.
806
The globals for each DocTest is formed by combining `globs`
807
and `extraglobs` (bindings in `extraglobs` override bindings
808
in `globs`). A new copy of the globals dictionary is created
809
for each DocTest. If `globs` is not specified, then it
810
defaults to the module's `__dict__`, if specified, or {}
811
otherwise. If `extraglobs` is not specified, then it defaults
815
# If name was not specified, then extract it from the object.
817
name = getattr(obj, '__name__', None)
819
raise ValueError("DocTestFinder.find: name must be given "
820
"when obj.__name__ doesn't exist: %r" %
823
# Find the module that contains the given object (if obj is
824
# a module, then module=obj.). Note: this may fail, in which
825
# case module will be None.
829
module = inspect.getmodule(obj)
831
# Read the module's source code. This is used by
832
# DocTestFinder._find_lineno to find the line number for a
833
# given object's docstring.
835
file = inspect.getsourcefile(obj) or inspect.getfile(obj)
836
if module is not None:
837
# Supply the module globals in case the module was
838
# originally loaded via a PEP 302 loader and
839
# file is not a valid filesystem path
840
source_lines = linecache.getlines(file, module.__dict__)
842
# No access to a loader, so assume it's a normal
844
source_lines = linecache.getlines(file)
850
# Initialize globals, and merge in extraglobs.
855
globs = module.__dict__.copy()
858
if extraglobs is not None:
859
globs.update(extraglobs)
860
if '__name__' not in globs:
861
globs['__name__'] = '__main__' # provide a default module name
863
# Recursively expore `obj`, extracting DocTests.
865
self._find(tests, obj, name, module, source_lines, globs, {})
866
# Sort the tests by alpha order of names, for consistency in
867
# verbose-mode output. This was a feature of doctest in Pythons
868
# <= 2.3 that got lost by accident in 2.4. It was repaired in
873
def _from_module(self, module, object):
875
Return true if the given object is defined in the given
880
elif inspect.getmodule(object) is not None:
881
return module is inspect.getmodule(object)
882
elif inspect.isfunction(object):
883
return module.__dict__ is object.func_globals
884
elif inspect.isclass(object):
885
return module.__name__ == object.__module__
886
elif hasattr(object, '__module__'):
887
return module.__name__ == object.__module__
888
elif isinstance(object, property):
889
return True # [XX] no way not be sure.
891
raise ValueError("object must be a class or function")
893
def _find(self, tests, obj, name, module, source_lines, globs, seen):
895
Find tests for the given object and any contained objects, and
899
print 'Finding tests in %s' % name
901
# If we've already processed this object, then ignore it.
906
# Find a test for this object, and add it to the list of tests.
907
test = self._get_test(obj, name, module, globs, source_lines)
911
# Look for tests in a module's contained objects.
912
if inspect.ismodule(obj) and self._recurse:
913
for valname, val in obj.__dict__.items():
914
valname = '%s.%s' % (name, valname)
915
# Recurse to functions & classes.
916
if ((inspect.isfunction(val) or inspect.isclass(val)) and
917
self._from_module(module, val)):
918
self._find(tests, val, valname, module, source_lines,
921
# Look for tests in a module's __test__ dictionary.
922
if inspect.ismodule(obj) and self._recurse:
923
for valname, val in getattr(obj, '__test__', {}).items():
924
if not isinstance(valname, basestring):
925
raise ValueError("DocTestFinder.find: __test__ keys "
926
"must be strings: %r" %
928
if not (inspect.isfunction(val) or inspect.isclass(val) or
929
inspect.ismethod(val) or inspect.ismodule(val) or
930
isinstance(val, basestring)):
931
raise ValueError("DocTestFinder.find: __test__ values "
932
"must be strings, functions, methods, "
933
"classes, or modules: %r" %
935
valname = '%s.__test__.%s' % (name, valname)
936
self._find(tests, val, valname, module, source_lines,
939
# Look for tests in a class's contained objects.
940
if inspect.isclass(obj) and self._recurse:
941
for valname, val in obj.__dict__.items():
942
# Special handling for staticmethod/classmethod.
943
if isinstance(val, staticmethod):
944
val = getattr(obj, valname)
945
if isinstance(val, classmethod):
946
val = getattr(obj, valname).im_func
948
# Recurse to methods, properties, and nested classes.
949
if ((inspect.isfunction(val) or inspect.isclass(val) or
950
isinstance(val, property)) and
951
self._from_module(module, val)):
952
valname = '%s.%s' % (name, valname)
953
self._find(tests, val, valname, module, source_lines,
956
def _get_test(self, obj, name, module, globs, source_lines):
958
Return a DocTest for the given object, if it defines a docstring;
959
otherwise, return None.
961
# Extract the object's docstring. If it doesn't have one,
962
# then return None (no test for this object).
963
if isinstance(obj, basestring):
967
if obj.__doc__ is None:
970
docstring = obj.__doc__
971
if not isinstance(docstring, basestring):
972
docstring = str(docstring)
973
except (TypeError, AttributeError):
976
# Find the docstring's location in the file.
977
lineno = self._find_lineno(obj, source_lines)
979
# Don't bother if the docstring is empty.
980
if self._exclude_empty and not docstring:
983
# Return a DocTest for this object.
987
filename = getattr(module, '__file__', module.__name__)
988
if filename[-4:] in (".pyc", ".pyo"):
989
filename = filename[:-1]
990
return self._parser.get_doctest(docstring, globs, name,
993
def _find_lineno(self, obj, source_lines):
995
Return a line number of the given object's docstring. Note:
996
this method assumes that the object has a docstring.
1000
# Find the line number for modules.
1001
if inspect.ismodule(obj):
1004
# Find the line number for classes.
1005
# Note: this could be fooled if a class is defined multiple
1006
# times in a single file.
1007
if inspect.isclass(obj):
1008
if source_lines is None:
1010
pat = re.compile(r'^\s*class\s*%s\b' %
1011
getattr(obj, '__name__', '-'))
1012
for i, line in enumerate(source_lines):
1017
# Find the line number for functions & methods.
1018
if inspect.ismethod(obj): obj = obj.im_func
1019
if inspect.isfunction(obj): obj = obj.func_code
1020
if inspect.istraceback(obj): obj = obj.tb_frame
1021
if inspect.isframe(obj): obj = obj.f_code
1022
if inspect.iscode(obj):
1023
lineno = getattr(obj, 'co_firstlineno', None)-1
1025
# Find the line number where the docstring starts. Assume
1026
# that it's the first line that begins with a quote mark.
1027
# Note: this could be fooled by a multiline function
1028
# signature, where a continuation line begins with a quote
1030
if lineno is not None:
1031
if source_lines is None:
1033
pat = re.compile('(^|.*:)\s*\w*("|\')')
1034
for lineno in range(lineno, len(source_lines)):
1035
if pat.match(source_lines[lineno]):
1038
# We couldn't find the line number.
1041
######################################################################
1042
## 5. DocTest Runner
1043
######################################################################
1045
class DocTestRunner:
1047
A class used to run DocTest test cases, and accumulate statistics.
1048
The `run` method is used to process a single DocTest case. It
1049
returns a tuple `(f, t)`, where `t` is the number of test cases
1050
tried, and `f` is the number of test cases that failed.
1052
>>> tests = DocTestFinder().find(_TestClass)
1053
>>> runner = DocTestRunner(verbose=False)
1054
>>> tests.sort(key = lambda test: test.name)
1055
>>> for test in tests:
1056
... print test.name, '->', runner.run(test)
1057
_TestClass -> TestResults(failed=0, attempted=2)
1058
_TestClass.__init__ -> TestResults(failed=0, attempted=2)
1059
_TestClass.get -> TestResults(failed=0, attempted=2)
1060
_TestClass.square -> TestResults(failed=0, attempted=1)
1062
The `summarize` method prints a summary of all the test cases that
1063
have been run by the runner, and returns an aggregated `(f, t)`
1066
>>> runner.summarize(verbose=1)
1067
4 items passed all tests:
1068
2 tests in _TestClass
1069
2 tests in _TestClass.__init__
1070
2 tests in _TestClass.get
1071
1 tests in _TestClass.square
1073
7 passed and 0 failed.
1075
TestResults(failed=0, attempted=7)
1077
The aggregated number of tried examples and failed examples is
1078
also available via the `tries` and `failures` attributes:
1085
The comparison between expected outputs and actual outputs is done
1086
by an `OutputChecker`. This comparison may be customized with a
1087
number of option flags; see the documentation for `testmod` for
1088
more information. If the option flags are insufficient, then the
1089
comparison may also be customized by passing a subclass of
1090
`OutputChecker` to the constructor.
1092
The test runner's display output can be controlled in two ways.
1093
First, an output function (`out) can be passed to
1094
`TestRunner.run`; this function will be called with strings that
1095
should be displayed. It defaults to `sys.stdout.write`. If
1096
capturing the output is not sufficient, then the display output
1097
can be also customized by subclassing DocTestRunner, and
1098
overriding the methods `report_start`, `report_success`,
1099
`report_unexpected_exception`, and `report_failure`.
1101
# This divider string is used to separate failure messages, and to
1102
# separate sections of the summary.
1105
def __init__(self, checker=None, verbose=None, optionflags=0):
1107
Create a new test runner.
1109
Optional keyword arg `checker` is the `OutputChecker` that
1110
should be used to compare the expected outputs and actual
1111
outputs of doctest examples.
1113
Optional keyword arg 'verbose' prints lots of stuff if true,
1114
only failures if false; by default, it's true iff '-v' is in
1117
Optional argument `optionflags` can be used to control how the
1118
test runner compares expected output to actual output, and how
1119
it displays failures. See the documentation for `testmod` for
1122
self._checker = checker or OutputChecker()
1124
verbose = '-v' in sys.argv
1125
self._verbose = verbose
1126
self.optionflags = optionflags
1127
self.original_optionflags = optionflags
1129
# Keep track of the examples we've run.
1134
# Create a fake output target for capturing doctest output.
1135
self._fakeout = _SpoofOut()
1137
#/////////////////////////////////////////////////////////////////
1139
#/////////////////////////////////////////////////////////////////
1141
def report_start(self, out, test, example):
1143
Report that the test runner is about to process the given
1144
example. (Only displays a message if verbose=True)
1148
out('Trying:\n' + _indent(example.source) +
1149
'Expecting:\n' + _indent(example.want))
1151
out('Trying:\n' + _indent(example.source) +
1152
'Expecting nothing\n')
1154
def report_success(self, out, test, example, got):
1156
Report that the given example ran successfully. (Only
1157
displays a message if verbose=True)
1162
def report_failure(self, out, test, example, got):
1164
Report that the given example failed.
1166
out(self._failure_header(test, example) +
1167
self._checker.output_difference(example, got, self.optionflags))
1169
def report_unexpected_exception(self, out, test, example, exc_info):
1171
Report that the given example raised an unexpected exception.
1173
out(self._failure_header(test, example) +
1174
'Exception raised:\n' + _indent(_exception_traceback(exc_info)))
1176
def _failure_header(self, test, example):
1177
out = [self.DIVIDER]
1179
if test.lineno is not None and example.lineno is not None:
1180
lineno = test.lineno + example.lineno + 1
1183
out.append('File "%s", line %s, in %s' %
1184
(test.filename, lineno, test.name))
1186
out.append('Line %s, in %s' % (example.lineno+1, test.name))
1187
out.append('Failed example:')
1188
source = example.source
1189
out.append(_indent(source))
1190
return '\n'.join(out)
1192
#/////////////////////////////////////////////////////////////////
1194
#/////////////////////////////////////////////////////////////////
1196
def __run(self, test, compileflags, out):
1198
Run the examples in `test`. Write the outcome of each example
1199
with one of the `DocTestRunner.report_*` methods, using the
1200
writer function `out`. `compileflags` is the set of compiler
1201
flags that should be used to execute examples. Return a tuple
1202
`(f, t)`, where `t` is the number of examples tried, and `f`
1203
is the number of examples that failed. The examples are run
1204
in the namespace `test.globs`.
1206
# Keep track of the number of failures and tries.
1207
failures = tries = 0
1209
# Save the option flags (since option directives can be used
1211
original_optionflags = self.optionflags
1213
SUCCESS, FAILURE, BOOM = range(3) # `outcome` state
1215
check = self._checker.check_output
1217
# Process each example.
1218
for examplenum, example in enumerate(test.examples):
1220
# If REPORT_ONLY_FIRST_FAILURE is set, then suppress
1221
# reporting after the first failure.
1222
quiet = (self.optionflags & REPORT_ONLY_FIRST_FAILURE and
1225
# Merge in the example's options.
1226
self.optionflags = original_optionflags
1228
for (optionflag, val) in example.options.items():
1230
self.optionflags |= optionflag
1232
self.optionflags &= ~optionflag
1234
# If 'SKIP' is set, then skip this example.
1235
if self.optionflags & SKIP:
1238
# Record that we started this example.
1241
self.report_start(out, test, example)
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)
1248
# Run the example in the given context (globs), and record
1249
# any exception that gets raised. (But don't intercept
1250
# keyboard interrupts.)
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 ====
1257
except KeyboardInterrupt:
1260
exception = sys.exc_info()
1261
self.debugger.set_continue() # ==== Example Finished ====
1263
got = self._fakeout.getvalue() # the actual output
1264
self._fakeout.truncate(0)
1265
outcome = FAILURE # guilty until proved innocent or insane
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):
1273
# The example raised an exception: check if it was expected.
1275
exc_info = sys.exc_info()
1276
exc_msg = traceback.format_exception_only(*exc_info[:2])[-1]
1278
got += _exception_traceback(exc_info)
1280
# If `example.exc_msg` is None, then we weren't expecting
1282
if example.exc_msg is None:
1285
# We expected an exception: see whether it matches.
1286
elif check(example.exc_msg, exc_msg, self.optionflags):
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(1), m2.group(1),
1297
# Report the outcome.
1298
if outcome is SUCCESS:
1300
self.report_success(out, test, example, got)
1301
elif outcome is FAILURE:
1303
self.report_failure(out, test, example, got)
1305
elif outcome is BOOM:
1307
self.report_unexpected_exception(out, test, example,
1311
assert False, ("unknown outcome", outcome)
1313
# Restore the option flags (in case they were modified)
1314
self.optionflags = original_optionflags
1316
# Record and return the number of failures and tries.
1317
self.__record_outcome(test, failures, tries)
1318
return TestResults(failures, tries)
1320
def __record_outcome(self, test, f, t):
1322
Record the fact that the given DocTest (`test`) generated `f`
1323
failures out of `t` tried examples.
1325
f2, t2 = self._name2ft.get(test.name, (0,0))
1326
self._name2ft[test.name] = (f+f2, t+t2)
1330
__LINECACHE_FILENAME_RE = re.compile(r'<doctest '
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
source = example.source
1338
if isinstance(source, unicode):
1339
source = source.encode('ascii', 'backslashreplace')
1340
return source.splitlines(True)
1342
return self.save_linecache_getlines(filename, module_globals)
1344
def run(self, test, compileflags=None, out=None, clear_globs=True):
1346
Run the examples in `test`, and display the results using the
1347
writer function `out`.
1349
The examples are run in the namespace `test.globs`. If
1350
`clear_globs` is true (the default), then this namespace will
1351
be cleared after the test runs, to help with garbage
1352
collection. If you would like to examine the namespace after
1353
the test completes, then use `clear_globs=False`.
1355
`compileflags` gives the set of flags that should be used by
1356
the Python compiler when running the examples. If not
1357
specified, then it will default to the set of future-import
1358
flags that apply to `globs`.
1360
The output of each example is checked using
1361
`DocTestRunner.check_output`, and the results are formatted by
1362
the `DocTestRunner.report_*` methods.
1366
if compileflags is None:
1367
compileflags = _extract_future_flags(test.globs)
1369
save_stdout = sys.stdout
1371
out = save_stdout.write
1372
sys.stdout = self._fakeout
1374
# Patch pdb.set_trace to restore sys.stdout during interactive
1375
# debugging (so it's not still redirected to self._fakeout).
1376
# Note that the interactive output will go to *our*
1377
# save_stdout, even if that's not the real sys.stdout; this
1378
# allows us to write test cases for the set_trace behavior.
1379
save_set_trace = pdb.set_trace
1380
self.debugger = _OutputRedirectingPdb(save_stdout)
1381
self.debugger.reset()
1382
pdb.set_trace = self.debugger.set_trace
1384
# Patch linecache.getlines, so we can see the example's source
1385
# when we're inside the debugger.
1386
self.save_linecache_getlines = linecache.getlines
1387
linecache.getlines = self.__patched_linecache_getlines
1389
# Make sure sys.displayhook just prints the value to stdout
1390
save_displayhook = sys.displayhook
1391
sys.displayhook = sys.__displayhook__
1394
return self.__run(test, compileflags, out)
1396
sys.stdout = save_stdout
1397
pdb.set_trace = save_set_trace
1398
linecache.getlines = self.save_linecache_getlines
1399
sys.displayhook = save_displayhook
1403
#/////////////////////////////////////////////////////////////////
1405
#/////////////////////////////////////////////////////////////////
1406
def summarize(self, verbose=None):
1408
Print a summary of all the test cases that have been run by
1409
this DocTestRunner, and return a tuple `(f, t)`, where `f` is
1410
the total number of failed examples, and `t` is the total
1411
number of tried examples.
1413
The optional `verbose` argument controls how detailed the
1414
summary is. If the verbosity is not specified, then the
1415
DocTestRunner's verbosity is used.
1418
verbose = self._verbose
1423
for x in self._name2ft.items():
1429
notests.append(name)
1431
passed.append( (name, t) )
1436
print len(notests), "items had no tests:"
1438
for thing in notests:
1441
print len(passed), "items passed all tests:"
1443
for thing, count in passed:
1444
print " %3d tests in %s" % (count, thing)
1447
print len(failed), "items had failures:"
1449
for thing, (f, t) in failed:
1450
print " %3d of %3d in %s" % (f, t, thing)
1452
print totalt, "tests in", len(self._name2ft), "items."
1453
print totalt - totalf, "passed and", totalf, "failed."
1455
print "***Test Failed***", totalf, "failures."
1457
print "Test passed."
1458
return TestResults(totalf, totalt)
1460
#/////////////////////////////////////////////////////////////////
1461
# Backward compatibility cruft to maintain doctest.master.
1462
#/////////////////////////////////////////////////////////////////
1463
def merge(self, other):
1465
for name, (f, t) in other._name2ft.items():
1467
# Don't print here by default, since doing
1468
# so breaks some of the buildbots
1469
#print "*** DocTestRunner.merge: '" + name + "' in both" \
1470
# " testers; summing outcomes."
1476
class OutputChecker:
1478
A class used to check the whether the actual output from a doctest
1479
example matches the expected output. `OutputChecker` defines two
1480
methods: `check_output`, which compares a given pair of outputs,
1481
and returns true if they match; and `output_difference`, which
1482
returns a string describing the differences between two outputs.
1484
def check_output(self, want, got, optionflags):
1486
Return True iff the actual output from an example (`got`)
1487
matches the expected output (`want`). These strings are
1488
always considered to match if they are identical; but
1489
depending on what option flags the test runner is using,
1490
several non-exact match types are also possible. See the
1491
documentation for `TestRunner` for more information about
1494
# Handle the common case first, for efficiency:
1495
# if they're string-identical, always return true.
1499
# The values True and False replaced 1 and 0 as the return
1500
# value for boolean comparisons in Python 2.3.
1501
if not (optionflags & DONT_ACCEPT_TRUE_FOR_1):
1502
if (got,want) == ("True\n", "1\n"):
1504
if (got,want) == ("False\n", "0\n"):
1507
# <BLANKLINE> can be used as a special sequence to signify a
1508
# blank line, unless the DONT_ACCEPT_BLANKLINE flag is used.
1509
if not (optionflags & DONT_ACCEPT_BLANKLINE):
1510
# Replace <BLANKLINE> in want with a blank line.
1511
want = re.sub('(?m)^%s\s*?$' % re.escape(BLANKLINE_MARKER),
1513
# If a line in got contains only spaces, then remove the
1515
got = re.sub('(?m)^\s*?$', '', got)
1519
# This flag causes doctest to ignore any differences in the
1520
# contents of whitespace strings. Note that this can be used
1521
# in conjunction with the ELLIPSIS flag.
1522
if optionflags & NORMALIZE_WHITESPACE:
1523
got = ' '.join(got.split())
1524
want = ' '.join(want.split())
1528
# The ELLIPSIS flag says to let the sequence "..." in `want`
1529
# match any substring in `got`.
1530
if optionflags & ELLIPSIS:
1531
if _ellipsis_match(want, got):
1534
# We didn't find any match; return false.
1537
# Should we do a fancy diff?
1538
def _do_a_fancy_diff(self, want, got, optionflags):
1539
# Not unless they asked for a fancy diff.
1540
if not optionflags & (REPORT_UDIFF |
1545
# If expected output uses ellipsis, a meaningful fancy diff is
1546
# too hard ... or maybe not. In two real-life failures Tim saw,
1547
# a diff was a major help anyway, so this is commented out.
1548
# [todo] _ellipsis_match() knows which pieces do and don't match,
1549
# and could be the basis for a kick-ass diff in this case.
1550
##if optionflags & ELLIPSIS and ELLIPSIS_MARKER in want:
1553
# ndiff does intraline difference marking, so can be useful even
1554
# for 1-line differences.
1555
if optionflags & REPORT_NDIFF:
1558
# The other diff types need at least a few lines to be helpful.
1559
return want.count('\n') > 2 and got.count('\n') > 2
1561
def output_difference(self, example, got, optionflags):
1563
Return a string describing the differences between the
1564
expected output for a given example (`example`) and the actual
1565
output (`got`). `optionflags` is the set of option flags used
1566
to compare `want` and `got`.
1569
# If <BLANKLINE>s are being used, then replace blank lines
1570
# with <BLANKLINE> in the actual output string.
1571
if not (optionflags & DONT_ACCEPT_BLANKLINE):
1572
got = re.sub('(?m)^[ ]*(?=\n)', BLANKLINE_MARKER, got)
1574
# Check if we should use diff.
1575
if self._do_a_fancy_diff(want, got, optionflags):
1576
# Split want & got into lines.
1577
want_lines = want.splitlines(True) # True == keep line ends
1578
got_lines = got.splitlines(True)
1579
# Use difflib to find their differences.
1580
if optionflags & REPORT_UDIFF:
1581
diff = difflib.unified_diff(want_lines, got_lines, n=2)
1582
diff = list(diff)[2:] # strip the diff header
1583
kind = 'unified diff with -expected +actual'
1584
elif optionflags & REPORT_CDIFF:
1585
diff = difflib.context_diff(want_lines, got_lines, n=2)
1586
diff = list(diff)[2:] # strip the diff header
1587
kind = 'context diff with expected followed by actual'
1588
elif optionflags & REPORT_NDIFF:
1589
engine = difflib.Differ(charjunk=difflib.IS_CHARACTER_JUNK)
1590
diff = list(engine.compare(want_lines, got_lines))
1591
kind = 'ndiff with -expected +actual'
1593
assert 0, 'Bad diff option'
1594
# Remove trailing whitespace on diff output.
1595
diff = [line.rstrip() + '\n' for line in diff]
1596
return 'Differences (%s):\n' % kind + _indent(''.join(diff))
1598
# If we're not using diff, then simply list the expected
1599
# output followed by the actual output.
1601
return 'Expected:\n%sGot:\n%s' % (_indent(want), _indent(got))
1603
return 'Expected:\n%sGot nothing\n' % _indent(want)
1605
return 'Expected nothing\nGot:\n%s' % _indent(got)
1607
return 'Expected nothing\nGot nothing\n'
1609
class DocTestFailure(Exception):
1610
"""A DocTest example has failed in debugging mode.
1612
The exception instance has variables:
1614
- test: the DocTest object being run
1616
- example: the Example object that failed
1618
- got: the actual output
1620
def __init__(self, test, example, got):
1622
self.example = example
1626
return str(self.test)
1628
class UnexpectedException(Exception):
1629
"""A DocTest example has encountered an unexpected exception
1631
The exception instance has variables:
1633
- test: the DocTest object being run
1635
- example: the Example object that failed
1637
- exc_info: the exception info
1639
def __init__(self, test, example, exc_info):
1641
self.example = example
1642
self.exc_info = exc_info
1645
return str(self.test)
1647
class DebugRunner(DocTestRunner):
1648
r"""Run doc tests but raise an exception as soon as there is a failure.
1650
If an unexpected exception occurs, an UnexpectedException is raised.
1651
It contains the test, the example, and the original exception:
1653
>>> runner = DebugRunner(verbose=False)
1654
>>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
1655
... {}, 'foo', 'foo.py', 0)
1657
... runner.run(test)
1658
... except UnexpectedException, failure:
1661
>>> failure.test is test
1664
>>> failure.example.want
1667
>>> exc_info = failure.exc_info
1668
>>> raise exc_info[0], exc_info[1], exc_info[2]
1669
Traceback (most recent call last):
1673
We wrap the original exception to give the calling application
1674
access to the test and example information.
1676
If the output doesn't match, then a DocTestFailure is raised:
1678
>>> test = DocTestParser().get_doctest('''
1682
... ''', {}, 'foo', 'foo.py', 0)
1685
... runner.run(test)
1686
... except DocTestFailure, failure:
1689
DocTestFailure objects provide access to the test:
1691
>>> failure.test is test
1694
As well as to the example:
1696
>>> failure.example.want
1699
and the actual output:
1704
If a failure or error occurs, the globals are left intact:
1706
>>> del test.globs['__builtins__']
1710
>>> test = DocTestParser().get_doctest('''
1712
... >>> raise KeyError
1713
... ''', {}, 'foo', 'foo.py', 0)
1715
>>> runner.run(test)
1716
Traceback (most recent call last):
1718
UnexpectedException: <DocTest foo from foo.py:0 (2 examples)>
1720
>>> del test.globs['__builtins__']
1724
But the globals are cleared if there is no error:
1726
>>> test = DocTestParser().get_doctest('''
1728
... ''', {}, 'foo', 'foo.py', 0)
1730
>>> runner.run(test)
1731
TestResults(failed=0, attempted=1)
1738
def run(self, test, compileflags=None, out=None, clear_globs=True):
1739
r = DocTestRunner.run(self, test, compileflags, out, False)
1744
def report_unexpected_exception(self, out, test, example, exc_info):
1745
raise UnexpectedException(test, example, exc_info)
1747
def report_failure(self, out, test, example, got):
1748
raise DocTestFailure(test, example, got)
1750
######################################################################
1751
## 6. Test Functions
1752
######################################################################
1753
# These should be backwards compatible.
1755
# For backward compatibility, a global instance of a DocTestRunner
1756
# class, updated by testmod.
1759
def testmod(m=None, name=None, globs=None, verbose=None,
1760
report=True, optionflags=0, extraglobs=None,
1761
raise_on_error=False, exclude_empty=False):
1762
"""m=None, name=None, globs=None, verbose=None, report=True,
1763
optionflags=0, extraglobs=None, raise_on_error=False,
1766
Test examples in docstrings in functions and classes reachable
1767
from module m (or the current module if m is not supplied), starting
1770
Also test examples reachable from dict m.__test__ if it exists and is
1771
not None. m.__test__ maps names to functions, classes and strings;
1772
function and class docstrings are tested even if the name is private;
1773
strings are tested directly, as if they were docstrings.
1775
Return (#failures, #tests).
1777
See help(doctest) for an overview.
1779
Optional keyword arg "name" gives the name of the module; by default
1782
Optional keyword arg "globs" gives a dict to be used as the globals
1783
when executing examples; by default, use m.__dict__. A copy of this
1784
dict is actually used for each docstring, so that each docstring's
1785
examples start with a clean slate.
1787
Optional keyword arg "extraglobs" gives a dictionary that should be
1788
merged into the globals that are used to execute examples. By
1789
default, no extra globals are used. This is new in 2.4.
1791
Optional keyword arg "verbose" prints lots of stuff if true, prints
1792
only failures if false; by default, it's true iff "-v" is in sys.argv.
1794
Optional keyword arg "report" prints a summary at the end when true,
1795
else prints nothing at the end. In verbose mode, the summary is
1796
detailed, else very brief (in fact, empty if all tests passed).
1798
Optional keyword arg "optionflags" or's together module constants,
1799
and defaults to 0. This is new in 2.3. Possible values (see the
1802
DONT_ACCEPT_TRUE_FOR_1
1803
DONT_ACCEPT_BLANKLINE
1804
NORMALIZE_WHITESPACE
1807
IGNORE_EXCEPTION_DETAIL
1811
REPORT_ONLY_FIRST_FAILURE
1813
Optional keyword arg "raise_on_error" raises an exception on the
1814
first unexpected exception or failure. This allows failures to be
1815
post-mortem debugged.
1817
Advanced tomfoolery: testmod runs methods of a local instance of
1818
class doctest.Tester, then merges the results into (or creates)
1819
global Tester instance doctest.master. Methods of doctest.master
1820
can be called directly too, if you want to do something unusual.
1821
Passing report=0 to testmod is especially useful then, to delay
1822
displaying a summary. Invoke doctest.master.summarize(verbose)
1823
when you're done fiddling.
1827
# If no module was given, then use __main__.
1829
# DWA - m will still be None if this wasn't invoked from the command
1830
# line, in which case the following TypeError is about as good an error
1831
# as we should expect
1832
m = sys.modules.get('__main__')
1834
# Check that we were actually given a module.
1835
if not inspect.ismodule(m):
1836
raise TypeError("testmod: module required; %r" % (m,))
1838
# If no name was given, then use the module's name.
1842
# Find, parse, and run all tests in the given module.
1843
finder = DocTestFinder(exclude_empty=exclude_empty)
1846
runner = DebugRunner(verbose=verbose, optionflags=optionflags)
1848
runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1850
for test in finder.find(m, name, globs=globs, extraglobs=extraglobs):
1859
master.merge(runner)
1861
return TestResults(runner.failures, runner.tries)
1863
def testfile(filename, module_relative=True, name=None, package=None,
1864
globs=None, verbose=None, report=True, optionflags=0,
1865
extraglobs=None, raise_on_error=False, parser=DocTestParser(),
1868
Test examples in the given file. Return (#failures, #tests).
1870
Optional keyword arg "module_relative" specifies how filenames
1871
should be interpreted:
1873
- If "module_relative" is True (the default), then "filename"
1874
specifies a module-relative path. By default, this path is
1875
relative to the calling module's directory; but if the
1876
"package" argument is specified, then it is relative to that
1877
package. To ensure os-independence, "filename" should use
1878
"/" characters to separate path segments, and should not
1879
be an absolute path (i.e., it may not begin with "/").
1881
- If "module_relative" is False, then "filename" specifies an
1882
os-specific path. The path may be absolute or relative (to
1883
the current working directory).
1885
Optional keyword arg "name" gives the name of the test; by default
1886
use the file's basename.
1888
Optional keyword argument "package" is a Python package or the
1889
name of a Python package whose directory should be used as the
1890
base directory for a module relative filename. If no package is
1891
specified, then the calling module's directory is used as the base
1892
directory for module relative filenames. It is an error to
1893
specify "package" if "module_relative" is False.
1895
Optional keyword arg "globs" gives a dict to be used as the globals
1896
when executing examples; by default, use {}. A copy of this dict
1897
is actually used for each docstring, so that each docstring's
1898
examples start with a clean slate.
1900
Optional keyword arg "extraglobs" gives a dictionary that should be
1901
merged into the globals that are used to execute examples. By
1902
default, no extra globals are used.
1904
Optional keyword arg "verbose" prints lots of stuff if true, prints
1905
only failures if false; by default, it's true iff "-v" is in sys.argv.
1907
Optional keyword arg "report" prints a summary at the end when true,
1908
else prints nothing at the end. In verbose mode, the summary is
1909
detailed, else very brief (in fact, empty if all tests passed).
1911
Optional keyword arg "optionflags" or's together module constants,
1912
and defaults to 0. Possible values (see the docs for details):
1914
DONT_ACCEPT_TRUE_FOR_1
1915
DONT_ACCEPT_BLANKLINE
1916
NORMALIZE_WHITESPACE
1919
IGNORE_EXCEPTION_DETAIL
1923
REPORT_ONLY_FIRST_FAILURE
1925
Optional keyword arg "raise_on_error" raises an exception on the
1926
first unexpected exception or failure. This allows failures to be
1927
post-mortem debugged.
1929
Optional keyword arg "parser" specifies a DocTestParser (or
1930
subclass) that should be used to extract tests from the files.
1932
Optional keyword arg "encoding" specifies an encoding that should
1933
be used to convert the file to unicode.
1935
Advanced tomfoolery: testmod runs methods of a local instance of
1936
class doctest.Tester, then merges the results into (or creates)
1937
global Tester instance doctest.master. Methods of doctest.master
1938
can be called directly too, if you want to do something unusual.
1939
Passing report=0 to testmod is especially useful then, to delay
1940
displaying a summary. Invoke doctest.master.summarize(verbose)
1941
when you're done fiddling.
1945
if package and not module_relative:
1946
raise ValueError("Package may only be specified for module-"
1949
# Relativize the path
1950
text, filename = _load_testfile(filename, package, module_relative)
1952
# If no name was given, then use the file's name.
1954
name = os.path.basename(filename)
1956
# Assemble the globals.
1960
globs = globs.copy()
1961
if extraglobs is not None:
1962
globs.update(extraglobs)
1963
if '__name__' not in globs:
1964
globs['__name__'] = '__main__'
1967
runner = DebugRunner(verbose=verbose, optionflags=optionflags)
1969
runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1971
if encoding is not None:
1972
text = text.decode(encoding)
1974
# Read the file, convert it to a test, and run it.
1975
test = parser.get_doctest(text, globs, name, filename, 0)
1984
master.merge(runner)
1986
return TestResults(runner.failures, runner.tries)
1988
def run_docstring_examples(f, globs, verbose=False, name="NoName",
1989
compileflags=None, optionflags=0):
1991
Test examples in the given object's docstring (`f`), using `globs`
1992
as globals. Optional argument `name` is used in failure messages.
1993
If the optional argument `verbose` is true, then generate output
1994
even if there are no failures.
1996
`compileflags` gives the set of flags that should be used by the
1997
Python compiler when running the examples. If not specified, then
1998
it will default to the set of future-import flags that apply to
2001
Optional keyword arg `optionflags` specifies options for the
2002
testing and output. See the documentation for `testmod` for more
2005
# Find, parse, and run all tests in the given module.
2006
finder = DocTestFinder(verbose=verbose, recurse=False)
2007
runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
2008
for test in finder.find(f, name, globs=globs):
2009
runner.run(test, compileflags=compileflags)
2011
######################################################################
2013
######################################################################
2014
# This is provided only for backwards compatibility. It's not
2015
# actually used in any way.
2018
def __init__(self, mod=None, globs=None, verbose=None, optionflags=0):
2020
warnings.warn("class Tester is deprecated; "
2021
"use class doctest.DocTestRunner instead",
2022
DeprecationWarning, stacklevel=2)
2023
if mod is None and globs is None:
2024
raise TypeError("Tester.__init__: must specify mod or globs")
2025
if mod is not None and not inspect.ismodule(mod):
2026
raise TypeError("Tester.__init__: mod must be a module; %r" %
2029
globs = mod.__dict__
2032
self.verbose = verbose
2033
self.optionflags = optionflags
2034
self.testfinder = DocTestFinder()
2035
self.testrunner = DocTestRunner(verbose=verbose,
2036
optionflags=optionflags)
2038
def runstring(self, s, name):
2039
test = DocTestParser().get_doctest(s, self.globs, name, None, None)
2041
print "Running string", name
2042
(f,t) = self.testrunner.run(test)
2044
print f, "of", t, "examples failed in string", name
2045
return TestResults(f,t)
2047
def rundoc(self, object, name=None, module=None):
2049
tests = self.testfinder.find(object, name, module=module,
2052
(f2, t2) = self.testrunner.run(test)
2053
(f,t) = (f+f2, t+t2)
2054
return TestResults(f,t)
2056
def rundict(self, d, name, module=None):
2058
m = types.ModuleType(name)
2059
m.__dict__.update(d)
2062
return self.rundoc(m, name, module)
2064
def run__test__(self, d, name):
2066
m = types.ModuleType(name)
2068
return self.rundoc(m, name)
2070
def summarize(self, verbose=None):
2071
return self.testrunner.summarize(verbose)
2073
def merge(self, other):
2074
self.testrunner.merge(other.testrunner)
2076
######################################################################
2077
## 8. Unittest Support
2078
######################################################################
2080
_unittest_reportflags = 0
2082
def set_unittest_reportflags(flags):
2083
"""Sets the unittest option flags.
2085
The old flag is returned so that a runner could restore the old
2086
value if it wished to:
2089
>>> old = doctest._unittest_reportflags
2090
>>> doctest.set_unittest_reportflags(REPORT_NDIFF |
2091
... REPORT_ONLY_FIRST_FAILURE) == old
2094
>>> doctest._unittest_reportflags == (REPORT_NDIFF |
2095
... REPORT_ONLY_FIRST_FAILURE)
2098
Only reporting flags can be set:
2100
>>> doctest.set_unittest_reportflags(ELLIPSIS)
2101
Traceback (most recent call last):
2103
ValueError: ('Only reporting flags allowed', 8)
2105
>>> doctest.set_unittest_reportflags(old) == (REPORT_NDIFF |
2106
... REPORT_ONLY_FIRST_FAILURE)
2109
global _unittest_reportflags
2111
if (flags & REPORTING_FLAGS) != flags:
2112
raise ValueError("Only reporting flags allowed", flags)
2113
old = _unittest_reportflags
2114
_unittest_reportflags = flags
2118
class DocTestCase(unittest.TestCase):
2120
def __init__(self, test, optionflags=0, setUp=None, tearDown=None,
2123
unittest.TestCase.__init__(self)
2124
self._dt_optionflags = optionflags
2125
self._dt_checker = checker
2126
self._dt_test = test
2127
self._dt_setUp = setUp
2128
self._dt_tearDown = tearDown
2131
test = self._dt_test
2133
if self._dt_setUp is not None:
2134
self._dt_setUp(test)
2137
test = self._dt_test
2139
if self._dt_tearDown is not None:
2140
self._dt_tearDown(test)
2145
test = self._dt_test
2148
optionflags = self._dt_optionflags
2150
if not (optionflags & REPORTING_FLAGS):
2151
# The option flags don't include any reporting flags,
2152
# so add the default reporting flags
2153
optionflags |= _unittest_reportflags
2155
runner = DocTestRunner(optionflags=optionflags,
2156
checker=self._dt_checker, verbose=False)
2159
runner.DIVIDER = "-"*70
2160
failures, tries = runner.run(
2161
test, out=new.write, clear_globs=False)
2166
raise self.failureException(self.format_failure(new.getvalue()))
2168
def format_failure(self, err):
2169
test = self._dt_test
2170
if test.lineno is None:
2171
lineno = 'unknown line number'
2173
lineno = '%s' % test.lineno
2174
lname = '.'.join(test.name.split('.')[-1:])
2175
return ('Failed doctest test for %s\n'
2176
' File "%s", line %s, in %s\n\n%s'
2177
% (test.name, test.filename, lineno, lname, err)
2181
r"""Run the test case without results and without catching exceptions
2183
The unit test framework includes a debug method on test cases
2184
and test suites to support post-mortem debugging. The test code
2185
is run in such a way that errors are not caught. This way a
2186
caller can catch the errors and initiate post-mortem debugging.
2188
The DocTestCase provides a debug method that raises
2189
UnexpectedException errors if there is an unexpected
2192
>>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
2193
... {}, 'foo', 'foo.py', 0)
2194
>>> case = DocTestCase(test)
2197
... except UnexpectedException, failure:
2200
The UnexpectedException contains the test, the example, and
2201
the original exception:
2203
>>> failure.test is test
2206
>>> failure.example.want
2209
>>> exc_info = failure.exc_info
2210
>>> raise exc_info[0], exc_info[1], exc_info[2]
2211
Traceback (most recent call last):
2215
If the output doesn't match, then a DocTestFailure is raised:
2217
>>> test = DocTestParser().get_doctest('''
2221
... ''', {}, 'foo', 'foo.py', 0)
2222
>>> case = DocTestCase(test)
2226
... except DocTestFailure, failure:
2229
DocTestFailure objects provide access to the test:
2231
>>> failure.test is test
2234
As well as to the example:
2236
>>> failure.example.want
2239
and the actual output:
2247
runner = DebugRunner(optionflags=self._dt_optionflags,
2248
checker=self._dt_checker, verbose=False)
2249
runner.run(self._dt_test, clear_globs=False)
2253
return self._dt_test.name
2256
name = self._dt_test.name.split('.')
2257
return "%s (%s)" % (name[-1], '.'.join(name[:-1]))
2261
def shortDescription(self):
2262
return "Doctest: " + self._dt_test.name
2264
class SkipDocTestCase(DocTestCase):
2266
DocTestCase.__init__(self, None)
2269
self.skipTest("DocTestSuite will not work with -O2 and above")
2271
def test_skip(self):
2274
def shortDescription(self):
2275
return "Skipping tests from %s" % module.__name__
2277
def DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None,
2280
Convert doctest tests for a module to a unittest test suite.
2282
This converts each documentation string in a module that
2283
contains doctest tests to a unittest test case. If any of the
2284
tests in a doc string fail, then the test case fails. An exception
2285
is raised showing the name of the file containing the test and a
2286
(sometimes approximate) line number.
2288
The `module` argument provides the module to be tested. The argument
2289
can be either a module or a module name.
2291
If no argument is given, the calling module is used.
2293
A number of options may be provided as keyword arguments:
2296
A set-up function. This is called before running the
2297
tests in each file. The setUp function will be passed a DocTest
2298
object. The setUp function can access the test globals as the
2299
globs attribute of the test passed.
2302
A tear-down function. This is called after running the
2303
tests in each file. The tearDown function will be passed a DocTest
2304
object. The tearDown function can access the test globals as the
2305
globs attribute of the test passed.
2308
A dictionary containing initial global variables for the tests.
2311
A set of doctest option flags expressed as an integer.
2314
if test_finder is None:
2315
test_finder = DocTestFinder()
2317
module = _normalize_module(module)
2318
tests = test_finder.find(module, globs=globs, extraglobs=extraglobs)
2320
if not tests and sys.flags.optimize >=2:
2321
# Skip doctests when running with -O2
2322
suite = unittest.TestSuite()
2323
suite.addTest(SkipDocTestCase())
2326
# Why do we want to do this? Because it reveals a bug that might
2327
# otherwise be hidden.
2328
raise ValueError(module, "has no tests")
2331
suite = unittest.TestSuite()
2334
if len(test.examples) == 0:
2336
if not test.filename:
2337
filename = module.__file__
2338
if filename[-4:] in (".pyc", ".pyo"):
2339
filename = filename[:-1]
2340
test.filename = filename
2341
suite.addTest(DocTestCase(test, **options))
2345
class DocFileCase(DocTestCase):
2348
return '_'.join(self._dt_test.name.split('.'))
2351
return self._dt_test.filename
2354
def format_failure(self, err):
2355
return ('Failed doctest test for %s\n File "%s", line 0\n\n%s'
2356
% (self._dt_test.name, self._dt_test.filename, err)
2359
def DocFileTest(path, module_relative=True, package=None,
2360
globs=None, parser=DocTestParser(),
2361
encoding=None, **options):
2365
globs = globs.copy()
2367
if package and not module_relative:
2368
raise ValueError("Package may only be specified for module-"
2371
# Relativize the path.
2372
doc, path = _load_testfile(path, package, module_relative)
2374
if "__file__" not in globs:
2375
globs["__file__"] = path
2377
# Find the file and read it.
2378
name = os.path.basename(path)
2380
# If an encoding is specified, use it to convert the file to unicode
2381
if encoding is not None:
2382
doc = doc.decode(encoding)
2384
# Convert it to a test, and wrap it in a DocFileCase.
2385
test = parser.get_doctest(doc, globs, name, path, 0)
2386
return DocFileCase(test, **options)
2388
def DocFileSuite(*paths, **kw):
2389
"""A unittest suite for one or more doctest files.
2391
The path to each doctest file is given as a string; the
2392
interpretation of that string depends on the keyword argument
2395
A number of options may be provided as keyword arguments:
2398
If "module_relative" is True, then the given file paths are
2399
interpreted as os-independent module-relative paths. By
2400
default, these paths are relative to the calling module's
2401
directory; but if the "package" argument is specified, then
2402
they are relative to that package. To ensure os-independence,
2403
"filename" should use "/" characters to separate path
2404
segments, and may not be an absolute path (i.e., it may not
2407
If "module_relative" is False, then the given file paths are
2408
interpreted as os-specific paths. These paths may be absolute
2409
or relative (to the current working directory).
2412
A Python package or the name of a Python package whose directory
2413
should be used as the base directory for module relative paths.
2414
If "package" is not specified, then the calling module's
2415
directory is used as the base directory for module relative
2416
filenames. It is an error to specify "package" if
2417
"module_relative" is False.
2420
A set-up function. This is called before running the
2421
tests in each file. The setUp function will be passed a DocTest
2422
object. The setUp function can access the test globals as the
2423
globs attribute of the test passed.
2426
A tear-down function. This is called after running the
2427
tests in each file. The tearDown function will be passed a DocTest
2428
object. The tearDown function can access the test globals as the
2429
globs attribute of the test passed.
2432
A dictionary containing initial global variables for the tests.
2435
A set of doctest option flags expressed as an integer.
2438
A DocTestParser (or subclass) that should be used to extract
2439
tests from the files.
2442
An encoding that will be used to convert the files to unicode.
2444
suite = unittest.TestSuite()
2446
# We do this here so that _normalize_module is called at the right
2447
# level. If it were called in DocFileTest, then this function
2448
# would be the caller and we might guess the package incorrectly.
2449
if kw.get('module_relative', True):
2450
kw['package'] = _normalize_module(kw.get('package'))
2453
suite.addTest(DocFileTest(path, **kw))
2457
######################################################################
2458
## 9. Debugging Support
2459
######################################################################
2461
def script_from_examples(s):
2462
r"""Extract script from text with examples.
2464
Converts text with examples to a Python script. Example input is
2465
converted to regular code. Example output and all other words
2466
are converted to comments:
2469
... Here are examples of simple math.
2471
... Python has super accurate integer addition
2476
... And very friendly error messages:
2483
... You can use logic if you want:
2493
>>> print script_from_examples(text)
2494
# Here are examples of simple math.
2496
# Python has super accurate integer addition
2502
# And very friendly error messages:
2510
# You can use logic if you want:
2520
for piece in DocTestParser().parse(s):
2521
if isinstance(piece, Example):
2522
# Add the example's source code (strip trailing NL)
2523
output.append(piece.source[:-1])
2524
# Add the expected output:
2527
output.append('# Expected:')
2528
output += ['## '+l for l in want.split('\n')[:-1]]
2530
# Add non-example text.
2531
output += [_comment_line(l)
2532
for l in piece.split('\n')[:-1]]
2534
# Trim junk on both ends.
2535
while output and output[-1] == '#':
2537
while output and output[0] == '#':
2539
# Combine the output, and return it.
2540
# Add a courtesy newline to prevent exec from choking (see bug #1172785)
2541
return '\n'.join(output) + '\n'
2543
def testsource(module, name):
2544
"""Extract the test sources from a doctest docstring as a script.
2546
Provide the module (or dotted name of the module) containing the
2547
test to be debugged and the name (within the module) of the object
2548
with the doc string with tests to be debugged.
2550
module = _normalize_module(module)
2551
tests = DocTestFinder().find(module)
2552
test = [t for t in tests if t.name == name]
2554
raise ValueError(name, "not found in tests")
2556
testsrc = script_from_examples(test.docstring)
2559
def debug_src(src, pm=False, globs=None):
2560
"""Debug a single doctest docstring, in argument `src`'"""
2561
testsrc = script_from_examples(src)
2562
debug_script(testsrc, pm, globs)
2564
def debug_script(src, pm=False, globs=None):
2565
"Debug a test script. `src` is the script, as a string."
2568
# Note that tempfile.NameTemporaryFile() cannot be used. As the
2569
# docs say, a file so created cannot be opened by name a second time
2570
# on modern Windows boxes, and execfile() needs to open it.
2571
srcfilename = tempfile.mktemp(".py", "doctestdebug")
2572
f = open(srcfilename, 'w')
2578
globs = globs.copy()
2584
execfile(srcfilename, globs, globs)
2586
print sys.exc_info()[1]
2587
pdb.post_mortem(sys.exc_info()[2])
2589
# Note that %r is vital here. '%s' instead can, e.g., cause
2590
# backslashes to get treated as metacharacters on Windows.
2591
pdb.run("execfile(%r)" % srcfilename, globs, globs)
2594
os.remove(srcfilename)
2596
def debug(module, name, pm=False):
2597
"""Debug a single doctest docstring.
2599
Provide the module (or dotted name of the module) containing the
2600
test to be debugged and the name (within the module) of the object
2601
with the docstring with tests to be debugged.
2603
module = _normalize_module(module)
2604
testsrc = testsource(module, name)
2605
debug_script(testsrc, pm, module.__dict__)
2607
######################################################################
2608
## 10. Example Usage
2609
######################################################################
2612
A pointless class, for sanity-checking of docstring testing.
2618
>>> _TestClass(13).get() + _TestClass(-12).get()
2620
>>> hex(_TestClass(13).square().get())
2624
def __init__(self, val):
2625
"""val -> _TestClass object with associated value val.
2627
>>> t = _TestClass(123)
2635
"""square() -> square TestClass's associated value
2637
>>> _TestClass(13).square().get()
2641
self.val = self.val ** 2
2645
"""get() -> return TestClass's associated value.
2647
>>> x = _TestClass(-42)
2654
__test__ = {"_TestClass": _TestClass,
2656
Example of a string object, searched as-is.
2662
"bool-int equivalence": r"""
2663
In 2.2, boolean expressions displayed
2664
0 or 1. By default, we still accept
2665
them. This can be disabled by passing
2666
DONT_ACCEPT_TRUE_FOR_1 to the new
2667
optionflags argument.
2679
Blank lines can be marked with <BLANKLINE>:
2680
>>> print 'foo\n\nbar\n'
2688
If the ellipsis flag is used, then '...' can be used to
2689
elide substrings in the desired output:
2690
>>> print range(1000) #doctest: +ELLIPSIS
2694
"whitespace normalization": r"""
2695
If the whitespace normalization flag is used, then
2696
differences in whitespace are ignored.
2697
>>> print range(30) #doctest: +NORMALIZE_WHITESPACE
2698
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
2699
15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,
2706
testfiles = [arg for arg in sys.argv[1:] if arg and arg[0] != '-']
2708
name = os.path.basename(sys.argv[0])
2709
if '__loader__' in globals(): # python -m
2710
name, _ = os.path.splitext(name)
2711
print("usage: {0} [-v] file ...".format(name))
2713
for filename in testfiles:
2714
if filename.endswith(".py"):
2715
# It is a module -- insert its dir into sys.path and try to
2716
# import it. If it is part of a package, that possibly
2717
# won't work because of package imports.
2718
dirname, filename = os.path.split(filename)
2719
sys.path.insert(0, dirname)
2720
m = __import__(filename[:-3])
2722
failures, _ = testmod(m)
2724
failures, _ = testfile(filename, module_relative=False)
2730
if __name__ == "__main__":
added
removed
gui/kivy/tools/.buildozer/android/platform/python-for-android/dist/kivy/python-install/lib/python2.7/doctest.py
