Statistics
| Branch: | Revision:

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