Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Added first stab at model and DB-API unit tests

git-svn-id: http://code.djangoproject.com/svn/django/trunk@336 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit daf8467b37f7aaae0b463b40a2c9d98f1f53c556 1 parent cae7ebe
Adrian Holovaty authored July 29, 2005
2,665  tests/doctest.py
... ...
@@ -0,0 +1,2665 @@
  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
+r"""Module doctest -- a framework for running examples in docstrings.
  10
+
  11
+In simplest use, end each module M to be tested with:
  12
+
  13
+def _test():
  14
+    import doctest
  15
+    doctest.testmod()
  16
+
  17
+if __name__ == "__main__":
  18
+    _test()
  19
+
  20
+Then running the module as a script will cause the examples in the
  21
+docstrings to get executed and verified:
  22
+
  23
+python M.py
  24
+
  25
+This won't display anything unless an example fails, in which case the
  26
+failing example(s) and the cause(s) of the failure(s) are printed to stdout
  27
+(why not stderr? because stderr is a lame hack <0.2 wink>), and the final
  28
+line of output is "Test failed.".
  29
+
  30
+Run it with the -v switch instead:
  31
+
  32
+python M.py -v
  33
+
  34
+and a detailed report of all examples tried is printed to stdout, along
  35
+with assorted summaries at the end.
  36
+
  37
+You can force verbose mode by passing "verbose=True" to testmod, or prohibit
  38
+it by passing "verbose=False".  In either of those cases, sys.argv is not
  39
+examined by testmod.
  40
+
  41
+There are a variety of other ways to run doctests, including integration
  42
+with the unittest framework, and support for running non-Python text
  43
+files containing doctests.  There are also many ways to override parts
  44
+of doctest's default behaviors.  See the Library Reference Manual for
  45
+details.
  46
+"""
  47
+
  48
+__docformat__ = 'reStructuredText en'
  49
+
  50
+__all__ = [
  51
+    # 0, Option Flags
  52
+    'register_optionflag',
  53
+    'DONT_ACCEPT_TRUE_FOR_1',
  54
+    'DONT_ACCEPT_BLANKLINE',
  55
+    'NORMALIZE_WHITESPACE',
  56
+    'ELLIPSIS',
  57
+    'IGNORE_EXCEPTION_DETAIL',
  58
+    'COMPARISON_FLAGS',
  59
+    'REPORT_UDIFF',
  60
+    'REPORT_CDIFF',
  61
+    'REPORT_NDIFF',
  62
+    'REPORT_ONLY_FIRST_FAILURE',
  63
+    'REPORTING_FLAGS',
  64
+    # 1. Utility Functions
  65
+    'is_private',
  66
+    # 2. Example & DocTest
  67
+    'Example',
  68
+    'DocTest',
  69
+    # 3. Doctest Parser
  70
+    'DocTestParser',
  71
+    # 4. Doctest Finder
  72
+    'DocTestFinder',
  73
+    # 5. Doctest Runner
  74
+    'DocTestRunner',
  75
+    'OutputChecker',
  76
+    'DocTestFailure',
  77
+    'UnexpectedException',
  78
+    'DebugRunner',
  79
+    # 6. Test Functions
  80
+    'testmod',
  81
+    'testfile',
  82
+    'run_docstring_examples',
  83
+    # 7. Tester
  84
+    'Tester',
  85
+    # 8. Unittest Support
  86
+    'DocTestSuite',
  87
+    'DocFileSuite',
  88
+    'set_unittest_reportflags',
  89
+    # 9. Debugging Support
  90
+    'script_from_examples',
  91
+    'testsource',
  92
+    'debug_src',
  93
+    'debug',
  94
+]
  95
+
  96
+import __future__
  97
+
  98
+import sys, traceback, inspect, linecache, os, re, types
  99
+import unittest, difflib, pdb, tempfile
  100
+import warnings
  101
+from StringIO import StringIO
  102
+
  103
+# Don't whine about the deprecated is_private function in this
  104
+# module's tests.
  105
+warnings.filterwarnings("ignore", "is_private", DeprecationWarning,
  106
+                        __name__, 0)
  107
+
  108
+# There are 4 basic classes:
  109
+#  - Example: a <source, want> pair, plus an intra-docstring line number.
  110
+#  - DocTest: a collection of examples, parsed from a docstring, plus
  111
+#    info about where the docstring came from (name, filename, lineno).
  112
+#  - DocTestFinder: extracts DocTests from a given object's docstring and
  113
+#    its contained objects' docstrings.
  114
+#  - DocTestRunner: runs DocTest cases, and accumulates statistics.
  115
+#
  116
+# So the basic picture is:
  117
+#
  118
+#                             list of:
  119
+# +------+                   +---------+                   +-------+
  120
+# |object| --DocTestFinder-> | DocTest | --DocTestRunner-> |results|
  121
+# +------+                   +---------+                   +-------+
  122
+#                            | Example |
  123
+#                            |   ...   |
  124
+#                            | Example |
  125
+#                            +---------+
  126
+
  127
+# Option constants.
  128
+
  129
+OPTIONFLAGS_BY_NAME = {}
  130
+def register_optionflag(name):
  131
+    flag = 1 << len(OPTIONFLAGS_BY_NAME)
  132
+    OPTIONFLAGS_BY_NAME[name] = flag
  133
+    return flag
  134
+
  135
+DONT_ACCEPT_TRUE_FOR_1 = register_optionflag('DONT_ACCEPT_TRUE_FOR_1')
  136
+DONT_ACCEPT_BLANKLINE = register_optionflag('DONT_ACCEPT_BLANKLINE')
  137
+NORMALIZE_WHITESPACE = register_optionflag('NORMALIZE_WHITESPACE')
  138
+ELLIPSIS = register_optionflag('ELLIPSIS')
  139
+IGNORE_EXCEPTION_DETAIL = register_optionflag('IGNORE_EXCEPTION_DETAIL')
  140
+
  141
+COMPARISON_FLAGS = (DONT_ACCEPT_TRUE_FOR_1 |
  142
+                    DONT_ACCEPT_BLANKLINE |
  143
+                    NORMALIZE_WHITESPACE |
  144
+                    ELLIPSIS |
  145
+                    IGNORE_EXCEPTION_DETAIL)
  146
+
  147
+REPORT_UDIFF = register_optionflag('REPORT_UDIFF')
  148
+REPORT_CDIFF = register_optionflag('REPORT_CDIFF')
  149
+REPORT_NDIFF = register_optionflag('REPORT_NDIFF')
  150
+REPORT_ONLY_FIRST_FAILURE = register_optionflag('REPORT_ONLY_FIRST_FAILURE')
  151
+
  152
+REPORTING_FLAGS = (REPORT_UDIFF |
  153
+                   REPORT_CDIFF |
  154
+                   REPORT_NDIFF |
  155
+                   REPORT_ONLY_FIRST_FAILURE)
  156
+
  157
+# Special string markers for use in `want` strings:
  158
+BLANKLINE_MARKER = '<BLANKLINE>'
  159
+ELLIPSIS_MARKER = '...'
  160
+
  161
+######################################################################
  162
+## Table of Contents
  163
+######################################################################
  164
+#  1. Utility Functions
  165
+#  2. Example & DocTest -- store test cases
  166
+#  3. DocTest Parser -- extracts examples from strings
  167
+#  4. DocTest Finder -- extracts test cases from objects
  168
+#  5. DocTest Runner -- runs test cases
  169
+#  6. Test Functions -- convenient wrappers for testing
  170
+#  7. Tester Class -- for backwards compatibility
  171
+#  8. Unittest Support
  172
+#  9. Debugging Support
  173
+# 10. Example Usage
  174
+
  175
+######################################################################
  176
+## 1. Utility Functions
  177
+######################################################################
  178
+
  179
+def is_private(prefix, base):
  180
+    """prefix, base -> true iff name prefix + "." + base is "private".
  181
+
  182
+    Prefix may be an empty string, and base does not contain a period.
  183
+    Prefix is ignored (although functions you write conforming to this
  184
+    protocol may make use of it).
  185
+    Return true iff base begins with an (at least one) underscore, but
  186
+    does not both begin and end with (at least) two underscores.
  187
+
  188
+    >>> is_private("a.b", "my_func")
  189
+    False
  190
+    >>> is_private("____", "_my_func")
  191
+    True
  192
+    >>> is_private("someclass", "__init__")
  193
+    False
  194
+    >>> is_private("sometypo", "__init_")
  195
+    True
  196
+    >>> is_private("x.y.z", "_")
  197
+    True
  198
+    >>> is_private("_x.y.z", "__")
  199
+    False
  200
+    >>> is_private("", "")  # senseless but consistent
  201
+    False
  202
+    """
  203
+    warnings.warn("is_private is deprecated; it wasn't useful; "
  204
+                  "examine DocTestFinder.find() lists instead",
  205
+                  DeprecationWarning, stacklevel=2)
  206
+    return base[:1] == "_" and not base[:2] == "__" == base[-2:]
  207
+
  208
+def _extract_future_flags(globs):
  209
+    """
  210
+    Return the compiler-flags associated with the future features that
  211
+    have been imported into the given namespace (globs).
  212
+    """
  213
+    flags = 0
  214
+    for fname in __future__.all_feature_names:
  215
+        feature = globs.get(fname, None)
  216
+        if feature is getattr(__future__, fname):
  217
+            flags |= feature.compiler_flag
  218
+    return flags
  219
+
  220
+def _normalize_module(module, depth=2):
  221
+    """
  222
+    Return the module specified by `module`.  In particular:
  223
+      - If `module` is a module, then return module.
  224
+      - If `module` is a string, then import and return the
  225
+        module with that name.
  226
+      - If `module` is None, then return the calling module.
  227
+        The calling module is assumed to be the module of
  228
+        the stack frame at the given depth in the call stack.
  229
+    """
  230
+    if inspect.ismodule(module):
  231
+        return module
  232
+    elif isinstance(module, (str, unicode)):
  233
+        return __import__(module, globals(), locals(), ["*"])
  234
+    elif module is None:
  235
+        return sys.modules[sys._getframe(depth).f_globals['__name__']]
  236
+    else:
  237
+        raise TypeError("Expected a module, string, or None")
  238
+
  239
+def _indent(s, indent=4):
  240
+    """
  241
+    Add the given number of space characters to the beginning every
  242
+    non-blank line in `s`, and return the result.
  243
+    """
  244
+    # This regexp matches the start of non-blank lines:
  245
+    return re.sub('(?m)^(?!$)', indent*' ', s)
  246
+
  247
+def _exception_traceback(exc_info):
  248
+    """
  249
+    Return a string containing a traceback message for the given
  250
+    exc_info tuple (as returned by sys.exc_info()).
  251
+    """
  252
+    # Get a traceback message.
  253
+    excout = StringIO()
  254
+    exc_type, exc_val, exc_tb = exc_info
  255
+    traceback.print_exception(exc_type, exc_val, exc_tb, file=excout)
  256
+    return excout.getvalue()
  257
+
  258
+# Override some StringIO methods.
  259
+class _SpoofOut(StringIO):
  260
+    def getvalue(self):
  261
+        result = StringIO.getvalue(self)
  262
+        # If anything at all was written, make sure there's a trailing
  263
+        # newline.  There's no way for the expected output to indicate
  264
+        # that a trailing newline is missing.
  265
+        if result and not result.endswith("\n"):
  266
+            result += "\n"
  267
+        # Prevent softspace from screwing up the next test case, in
  268
+        # case they used print with a trailing comma in an example.
  269
+        if hasattr(self, "softspace"):
  270
+            del self.softspace
  271
+        return result
  272
+
  273
+    def truncate(self,   size=None):
  274
+        StringIO.truncate(self, size)
  275
+        if hasattr(self, "softspace"):
  276
+            del self.softspace
  277
+
  278
+# Worst-case linear-time ellipsis matching.
  279
+def _ellipsis_match(want, got):
  280
+    """
  281
+    Essentially the only subtle case:
  282
+    >>> _ellipsis_match('aa...aa', 'aaa')
  283
+    False
  284
+    """
  285
+    if ELLIPSIS_MARKER not in want:
  286
+        return want == got
  287
+
  288
+    # Find "the real" strings.
  289
+    ws = want.split(ELLIPSIS_MARKER)
  290
+    assert len(ws) >= 2
  291
+
  292
+    # Deal with exact matches possibly needed at one or both ends.
  293
+    startpos, endpos = 0, len(got)
  294
+    w = ws[0]
  295
+    if w:   # starts with exact match
  296
+        if got.startswith(w):
  297
+            startpos = len(w)
  298
+            del ws[0]
  299
+        else:
  300
+            return False
  301
+    w = ws[-1]
  302
+    if w:   # ends with exact match
  303
+        if got.endswith(w):
  304
+            endpos -= len(w)
  305
+            del ws[-1]
  306
+        else:
  307
+            return False
  308
+
  309
+    if startpos > endpos:
  310
+        # Exact end matches required more characters than we have, as in
  311
+        # _ellipsis_match('aa...aa', 'aaa')
  312
+        return False
  313
+
  314
+    # For the rest, we only need to find the leftmost non-overlapping
  315
+    # match for each piece.  If there's no overall match that way alone,
  316
+    # there's no overall match period.
  317
+    for w in ws:
  318
+        # w may be '' at times, if there are consecutive ellipses, or
  319
+        # due to an ellipsis at the start or end of `want`.  That's OK.
  320
+        # Search for an empty string succeeds, and doesn't change startpos.
  321
+        startpos = got.find(w, startpos, endpos)
  322
+        if startpos < 0:
  323
+            return False
  324
+        startpos += len(w)
  325
+
  326
+    return True
  327
+
  328
+def _comment_line(line):
  329
+    "Return a commented form of the given line"
  330
+    line = line.rstrip()
  331
+    if line:
  332
+        return '# '+line
  333
+    else:
  334
+        return '#'
  335
+
  336
+class _OutputRedirectingPdb(pdb.Pdb):
  337
+    """
  338
+    A specialized version of the python debugger that redirects stdout
  339
+    to a given stream when interacting with the user.  Stdout is *not*
  340
+    redirected when traced code is executed.
  341
+    """
  342
+    def __init__(self, out):
  343
+        self.__out = out
  344
+        pdb.Pdb.__init__(self)
  345
+
  346
+    def trace_dispatch(self, *args):
  347
+        # Redirect stdout to the given stream.
  348
+        save_stdout = sys.stdout
  349
+        sys.stdout = self.__out
  350
+        # Call Pdb's trace dispatch method.
  351
+        try:
  352
+            return pdb.Pdb.trace_dispatch(self, *args)
  353
+        finally:
  354
+            sys.stdout = save_stdout
  355
+
  356
+# [XX] Normalize with respect to os.path.pardir?
  357
+def _module_relative_path(module, path):
  358
+    if not inspect.ismodule(module):
  359
+        raise TypeError, 'Expected a module: %r' % module
  360
+    if path.startswith('/'):
  361
+        raise ValueError, 'Module-relative files may not have absolute paths'
  362
+
  363
+    # Find the base directory for the path.
  364
+    if hasattr(module, '__file__'):
  365
+        # A normal module/package
  366
+        basedir = os.path.split(module.__file__)[0]
  367
+    elif module.__name__ == '__main__':
  368
+        # An interactive session.
  369
+        if len(sys.argv)>0 and sys.argv[0] != '':
  370
+            basedir = os.path.split(sys.argv[0])[0]
  371
+        else:
  372
+            basedir = os.curdir
  373
+    else:
  374
+        # A module w/o __file__ (this includes builtins)
  375
+        raise ValueError("Can't resolve paths relative to the module " +
  376
+                         module + " (it has no __file__)")
  377
+
  378
+    # Combine the base directory and the path.
  379
+    return os.path.join(basedir, *(path.split('/')))
  380
+
  381
+######################################################################
  382
+## 2. Example & DocTest
  383
+######################################################################
  384
+## - An "example" is a <source, want> pair, where "source" is a
  385
+##   fragment of source code, and "want" is the expected output for
  386
+##   "source."  The Example class also includes information about
  387
+##   where the example was extracted from.
  388
+##
  389
+## - A "doctest" is a collection of examples, typically extracted from
  390
+##   a string (such as an object's docstring).  The DocTest class also
  391
+##   includes information about where the string was extracted from.
  392
+
  393
+class Example:
  394
+    """
  395
+    A single doctest example, consisting of source code and expected
  396
+    output.  `Example` defines the following attributes:
  397
+
  398
+      - source: A single Python statement, always ending with a newline.
  399
+        The constructor adds a newline if needed.
  400
+
  401
+      - want: The expected output from running the source code (either
  402
+        from stdout, or a traceback in case of exception).  `want` ends
  403
+        with a newline unless it's empty, in which case it's an empty
  404
+        string.  The constructor adds a newline if needed.
  405
+
  406
+      - exc_msg: The exception message generated by the example, if
  407
+        the example is expected to generate an exception; or `None` if
  408
+        it is not expected to generate an exception.  This exception
  409
+        message is compared against the return value of
  410
+        `traceback.format_exception_only()`.  `exc_msg` ends with a
  411
+        newline unless it's `None`.  The constructor adds a newline
  412
+        if needed.
  413
+
  414
+      - lineno: The line number within the DocTest string containing
  415
+        this Example where the Example begins.  This line number is
  416
+        zero-based, with respect to the beginning of the DocTest.
  417
+
  418
+      - indent: The example's indentation in the DocTest string.
  419
+        I.e., the number of space characters that preceed the
  420
+        example's first prompt.
  421
+
  422
+      - options: A dictionary mapping from option flags to True or
  423
+        False, which is used to override default options for this
  424
+        example.  Any option flags not contained in this dictionary
  425
+        are left at their default value (as specified by the
  426
+        DocTestRunner's optionflags).  By default, no options are set.
  427
+    """
  428
+    def __init__(self, source, want, exc_msg=None, lineno=0, indent=0,
  429
+                 options=None):
  430
+        # Normalize inputs.
  431
+        if not source.endswith('\n'):
  432
+            source += '\n'
  433
+        if want and not want.endswith('\n'):
  434
+            want += '\n'
  435
+        if exc_msg is not None and not exc_msg.endswith('\n'):
  436
+            exc_msg += '\n'
  437
+        # Store properties.
  438
+        self.source = source
  439
+        self.want = want
  440
+        self.lineno = lineno
  441
+        self.indent = indent
  442
+        if options is None: options = {}
  443
+        self.options = options
  444
+        self.exc_msg = exc_msg
  445
+
  446
+class DocTest:
  447
+    """
  448
+    A collection of doctest examples that should be run in a single
  449
+    namespace.  Each `DocTest` defines the following attributes:
  450
+
  451
+      - examples: the list of examples.
  452
+
  453
+      - globs: The namespace (aka globals) that the examples should
  454
+        be run in.
  455
+
  456
+      - name: A name identifying the DocTest (typically, the name of
  457
+        the object whose docstring this DocTest was extracted from).
  458
+
  459
+      - filename: The name of the file that this DocTest was extracted
  460
+        from, or `None` if the filename is unknown.
  461
+
  462
+      - lineno: The line number within filename where this DocTest
  463
+        begins, or `None` if the line number is unavailable.  This
  464
+        line number is zero-based, with respect to the beginning of
  465
+        the file.
  466
+
  467
+      - docstring: The string that the examples were extracted from,
  468
+        or `None` if the string is unavailable.
  469
+    """
  470
+    def __init__(self, examples, globs, name, filename, lineno, docstring):
  471
+        """
  472
+        Create a new DocTest containing the given examples.  The
  473
+        DocTest's globals are initialized with a copy of `globs`.
  474
+        """
  475
+        assert not isinstance(examples, basestring), \
  476
+               "DocTest no longer accepts str; use DocTestParser instead"
  477
+        self.examples = examples
  478
+        self.docstring = docstring
  479
+        self.globs = globs.copy()
  480
+        self.name = name
  481
+        self.filename = filename
  482
+        self.lineno = lineno
  483
+
  484
+    def __repr__(self):
  485
+        if len(self.examples) == 0:
  486
+            examples = 'no examples'
  487
+        elif len(self.examples) == 1:
  488
+            examples = '1 example'
  489
+        else:
  490
+            examples = '%d examples' % len(self.examples)
  491
+        return ('<DocTest %s from %s:%s (%s)>' %
  492
+                (self.name, self.filename, self.lineno, examples))
  493
+
  494
+
  495
+    # This lets us sort tests by name:
  496
+    def __cmp__(self, other):
  497
+        if not isinstance(other, DocTest):
  498
+            return -1
  499
+        return cmp((self.name, self.filename, self.lineno, id(self)),
  500
+                   (other.name, other.filename, other.lineno, id(other)))
  501
+
  502
+######################################################################
  503
+## 3. DocTestParser
  504
+######################################################################
  505
+
  506
+class DocTestParser:
  507
+    """
  508
+    A class used to parse strings containing doctest examples.
  509
+    """
  510
+    # This regular expression is used to find doctest examples in a
  511
+    # string.  It defines three groups: `source` is the source code
  512
+    # (including leading indentation and prompts); `indent` is the
  513
+    # indentation of the first (PS1) line of the source code; and
  514
+    # `want` is the expected output (including leading indentation).
  515
+    _EXAMPLE_RE = re.compile(r'''
  516
+        # Source consists of a PS1 line followed by zero or more PS2 lines.
  517
+        (?P<source>
  518
+            (?:^(?P<indent> [ ]*) >>>    .*)    # PS1 line
  519
+            (?:\n           [ ]*  \.\.\. .*)*)  # PS2 lines
  520
+        \n?
  521
+        # Want consists of any non-blank lines that do not start with PS1.
  522
+        (?P<want> (?:(?![ ]*$)    # Not a blank line
  523
+                     (?![ ]*>>>)  # Not a line starting with PS1
  524
+                     .*$\n?       # But any other line
  525
+                  )*)
  526
+        ''', re.MULTILINE | re.VERBOSE)
  527
+
  528
+    # A regular expression for handling `want` strings that contain
  529
+    # expected exceptions.  It divides `want` into three pieces:
  530
+    #    - the traceback header line (`hdr`)
  531
+    #    - the traceback stack (`stack`)
  532
+    #    - the exception message (`msg`), as generated by
  533
+    #      traceback.format_exception_only()
  534
+    # `msg` may have multiple lines.  We assume/require that the
  535
+    # exception message is the first non-indented line starting with a word
  536
+    # character following the traceback header line.
  537
+    _EXCEPTION_RE = re.compile(r"""
  538
+        # Grab the traceback header.  Different versions of Python have
  539
+        # said different things on the first traceback line.
  540
+        ^(?P<hdr> Traceback\ \(
  541
+            (?: most\ recent\ call\ last
  542
+            |   innermost\ last
  543
+            ) \) :
  544
+        )
  545
+        \s* $                # toss trailing whitespace on the header.
  546
+        (?P<stack> .*?)      # don't blink: absorb stuff until...
  547
+        ^ (?P<msg> \w+ .*)   #     a line *starts* with alphanum.
  548
+        """, re.VERBOSE | re.MULTILINE | re.DOTALL)
  549
+
  550
+    # A callable returning a true value iff its argument is a blank line
  551
+    # or contains a single comment.
  552
+    _IS_BLANK_OR_COMMENT = re.compile(r'^[ ]*(#.*)?$').match
  553
+
  554
+    def parse(self, string, name='<string>'):
  555
+        """
  556
+        Divide the given string into examples and intervening text,
  557
+        and return them as a list of alternating Examples and strings.
  558
+        Line numbers for the Examples are 0-based.  The optional
  559
+        argument `name` is a name identifying this string, and is only
  560
+        used for error messages.
  561
+        """
  562
+        string = string.expandtabs()
  563
+        # If all lines begin with the same indentation, then strip it.
  564
+        min_indent = self._min_indent(string)
  565
+        if min_indent > 0:
  566
+            string = '\n'.join([l[min_indent:] for l in string.split('\n')])
  567
+
  568
+        output = []
  569
+        charno, lineno = 0, 0
  570
+        # Find all doctest examples in the string:
  571
+        for m in self._EXAMPLE_RE.finditer(string):
  572
+            # Add the pre-example text to `output`.
  573
+            output.append(string[charno:m.start()])
  574
+            # Update lineno (lines before this example)
  575
+            lineno += string.count('\n', charno, m.start())
  576
+            # Extract info from the regexp match.
  577
+            (source, options, want, exc_msg) = \
  578
+                     self._parse_example(m, name, lineno)
  579
+            # Create an Example, and add it to the list.
  580
+            if not self._IS_BLANK_OR_COMMENT(source):
  581
+                output.append( Example(source, want, exc_msg,
  582
+                                    lineno=lineno,
  583
+                                    indent=min_indent+len(m.group('indent')),
  584
+                                    options=options) )
  585
+            # Update lineno (lines inside this example)
  586
+            lineno += string.count('\n', m.start(), m.end())
  587
+            # Update charno.
  588
+            charno = m.end()
  589
+        # Add any remaining post-example text to `output`.
  590
+        output.append(string[charno:])
  591
+        return output
  592
+
  593
+    def get_doctest(self, string, globs, name, filename, lineno):
  594
+        """
  595
+        Extract all doctest examples from the given string, and
  596
+        collect them into a `DocTest` object.
  597
+
  598
+        `globs`, `name`, `filename`, and `lineno` are attributes for
  599
+        the new `DocTest` object.  See the documentation for `DocTest`
  600
+        for more information.
  601
+        """
  602
+        return DocTest(self.get_examples(string, name), globs,
  603
+                       name, filename, lineno, string)
  604
+
  605
+    def get_examples(self, string, name='<string>'):
  606
+        """
  607
+        Extract all doctest examples from the given string, and return
  608
+        them as a list of `Example` objects.  Line numbers are
  609
+        0-based, because it's most common in doctests that nothing
  610
+        interesting appears on the same line as opening triple-quote,
  611
+        and so the first interesting line is called \"line 1\" then.
  612
+
  613
+        The optional argument `name` is a name identifying this
  614
+        string, and is only used for error messages.
  615
+        """
  616
+        return [x for x in self.parse(string, name)
  617
+                if isinstance(x, Example)]
  618
+
  619
+    def _parse_example(self, m, name, lineno):
  620
+        """
  621
+        Given a regular expression match from `_EXAMPLE_RE` (`m`),
  622
+        return a pair `(source, want)`, where `source` is the matched
  623
+        example's source code (with prompts and indentation stripped);
  624
+        and `want` is the example's expected output (with indentation
  625
+        stripped).
  626
+
  627
+        `name` is the string's name, and `lineno` is the line number
  628
+        where the example starts; both are used for error messages.
  629
+        """
  630
+        # Get the example's indentation level.
  631
+        indent = len(m.group('indent'))
  632
+
  633
+        # Divide source into lines; check that they're properly
  634
+        # indented; and then strip their indentation & prompts.
  635
+        source_lines = m.group('source').split('\n')
  636
+        self._check_prompt_blank(source_lines, indent, name, lineno)
  637
+        self._check_prefix(source_lines[1:], ' '*indent + '.', name, lineno)
  638
+        source = '\n'.join([sl[indent+4:] for sl in source_lines])
  639
+
  640
+        # Divide want into lines; check that it's properly indented; and
  641
+        # then strip the indentation.  Spaces before the last newline should
  642
+        # be preserved, so plain rstrip() isn't good enough.
  643
+        want = m.group('want')
  644
+        want_lines = want.split('\n')
  645
+        if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]):
  646
+            del want_lines[-1]  # forget final newline & spaces after it
  647
+        self._check_prefix(want_lines, ' '*indent, name,
  648
+                           lineno + len(source_lines))
  649
+        want = '\n'.join([wl[indent:] for wl in want_lines])
  650
+
  651
+        # If `want` contains a traceback message, then extract it.
  652
+        m = self._EXCEPTION_RE.match(want)
  653
+        if m:
  654
+            exc_msg = m.group('msg')
  655
+        else:
  656
+            exc_msg = None
  657
+
  658
+        # Extract options from the source.
  659
+        options = self._find_options(source, name, lineno)
  660
+
  661
+        return source, options, want, exc_msg
  662
+
  663
+    # This regular expression looks for option directives in the
  664
+    # source code of an example.  Option directives are comments
  665
+    # starting with "doctest:".  Warning: this may give false
  666
+    # positives for string-literals that contain the string
  667
+    # "#doctest:".  Eliminating these false positives would require
  668
+    # actually parsing the string; but we limit them by ignoring any
  669
+    # line containing "#doctest:" that is *followed* by a quote mark.
  670
+    _OPTION_DIRECTIVE_RE = re.compile(r'#\s*doctest:\s*([^\n\'"]*)$',
  671
+                                      re.MULTILINE)
  672
+
  673
+    def _find_options(self, source, name, lineno):
  674
+        """
  675
+        Return a dictionary containing option overrides extracted from
  676
+        option directives in the given source string.
  677
+
  678
+        `name` is the string's name, and `lineno` is the line number
  679
+        where the example starts; both are used for error messages.
  680
+        """
  681
+        options = {}
  682
+        # (note: with the current regexp, this will match at most once:)
  683
+        for m in self._OPTION_DIRECTIVE_RE.finditer(source):
  684
+            option_strings = m.group(1).replace(',', ' ').split()
  685
+            for option in option_strings:
  686
+                if (option[0] not in '+-' or
  687
+                    option[1:] not in OPTIONFLAGS_BY_NAME):
  688
+                    raise ValueError('line %r of the doctest for %s '
  689
+                                     'has an invalid option: %r' %
  690
+                                     (lineno+1, name, option))
  691
+                flag = OPTIONFLAGS_BY_NAME[option[1:]]
  692
+                options[flag] = (option[0] == '+')
  693
+        if options and self._IS_BLANK_OR_COMMENT(source):
  694
+            raise ValueError('line %r of the doctest for %s has an option '
  695
+                             'directive on a line with no example: %r' %
  696
+                             (lineno, name, source))
  697
+        return options
  698
+
  699
+    # This regular expression finds the indentation of every non-blank
  700
+    # line in a string.
  701
+    _INDENT_RE = re.compile('^([ ]*)(?=\S)', re.MULTILINE)
  702
+
  703
+    def _min_indent(self, s):
  704
+        "Return the minimum indentation of any non-blank line in `s`"
  705
+        indents = [len(indent) for indent in self._INDENT_RE.findall(s)]
  706
+        if len(indents) > 0:
  707
+            return min(indents)
  708
+        else:
  709
+            return 0
  710
+
  711
+    def _check_prompt_blank(self, lines, indent, name, lineno):
  712
+        """
  713
+        Given the lines of a source string (including prompts and
  714
+        leading indentation), check to make sure that every prompt is
  715
+        followed by a space character.  If any line is not followed by
  716
+        a space character, then raise ValueError.
  717
+        """
  718
+        for i, line in enumerate(lines):
  719
+            if len(line) >= indent+4 and line[indent+3] != ' ':
  720
+                raise ValueError('line %r of the docstring for %s '
  721
+                                 'lacks blank after %s: %r' %
  722
+                                 (lineno+i+1, name,
  723
+                                  line[indent:indent+3], line))
  724
+
  725
+    def _check_prefix(self, lines, prefix, name, lineno):
  726
+        """
  727
+        Check that every line in the given list starts with the given
  728
+        prefix; if any line does not, then raise a ValueError.
  729
+        """
  730
+        for i, line in enumerate(lines):
  731
+            if line and not line.startswith(prefix):
  732
+                raise ValueError('line %r of the docstring for %s has '
  733
+                                 'inconsistent leading whitespace: %r' %
  734
+                                 (lineno+i+1, name, line))
  735
+
  736
+
  737
+######################################################################
  738
+## 4. DocTest Finder
  739
+######################################################################
  740
+
  741
+class DocTestFinder:
  742
+    """
  743
+    A class used to extract the DocTests that are relevant to a given
  744
+    object, from its docstring and the docstrings of its contained
  745
+    objects.  Doctests can currently be extracted from the following
  746
+    object types: modules, functions, classes, methods, staticmethods,
  747
+    classmethods, and properties.
  748
+    """
  749
+
  750
+    def __init__(self, verbose=False, parser=DocTestParser(),
  751
+                 recurse=True, _namefilter=None, exclude_empty=True):
  752
+        """
  753
+        Create a new doctest finder.
  754
+
  755
+        The optional argument `parser` specifies a class or
  756
+        function that should be used to create new DocTest objects (or
  757
+        objects that implement the same interface as DocTest).  The
  758
+        signature for this factory function should match the signature
  759
+        of the DocTest constructor.
  760
+
  761
+        If the optional argument `recurse` is false, then `find` will
  762
+        only examine the given object, and not any contained objects.
  763
+
  764
+        If the optional argument `exclude_empty` is false, then `find`
  765
+        will include tests for objects with empty docstrings.
  766
+        """
  767
+        self._parser = parser
  768
+        self._verbose = verbose
  769
+        self._recurse = recurse
  770
+        self._exclude_empty = exclude_empty
  771
+        # _namefilter is undocumented, and exists only for temporary backward-
  772
+        # compatibility support of testmod's deprecated isprivate mess.
  773
+        self._namefilter = _namefilter
  774
+
  775
+    def find(self, obj, name=None, module=None, globs=None,
  776
+             extraglobs=None):
  777
+        """
  778
+        Return a list of the DocTests that are defined by the given
  779
+        object's docstring, or by any of its contained objects'
  780
+        docstrings.
  781
+
  782
+        The optional parameter `module` is the module that contains
  783
+        the given object.  If the module is not specified or is None, then
  784
+        the test finder will attempt to automatically determine the
  785
+        correct module.  The object's module is used:
  786
+
  787
+            - As a default namespace, if `globs` is not specified.
  788
+            - To prevent the DocTestFinder from extracting DocTests
  789
+              from objects that are imported from other modules.
  790
+            - To find the name of the file containing the object.
  791
+            - To help find the line number of the object within its
  792
+              file.
  793
+
  794
+        Contained objects whose module does not match `module` are ignored.
  795
+
  796
+        If `module` is False, no attempt to find the module will be made.
  797
+        This is obscure, of use mostly in tests:  if `module` is False, or
  798
+        is None but cannot be found automatically, then all objects are
  799
+        considered to belong to the (non-existent) module, so all contained
  800
+        objects will (recursively) be searched for doctests.
  801
+
  802
+        The globals for each DocTest is formed by combining `globs`
  803
+        and `extraglobs` (bindings in `extraglobs` override bindings
  804
+        in `globs`).  A new copy of the globals dictionary is created
  805
+        for each DocTest.  If `globs` is not specified, then it
  806
+        defaults to the module's `__dict__`, if specified, or {}
  807
+        otherwise.  If `extraglobs` is not specified, then it defaults
  808
+        to {}.
  809
+
  810
+        """
  811
+        # If name was not specified, then extract it from the object.
  812
+        if name is None:
  813
+            name = getattr(obj, '__name__', None)
  814
+            if name is None:
  815
+                raise ValueError("DocTestFinder.find: name must be given "
  816
+                        "when obj.__name__ doesn't exist: %r" %
  817
+                                 (type(obj),))
  818
+
  819
+        # Find the module that contains the given object (if obj is
  820
+        # a module, then module=obj.).  Note: this may fail, in which
  821
+        # case module will be None.
  822
+        if module is False:
  823
+            module = None
  824
+        elif module is None:
  825
+            module = inspect.getmodule(obj)
  826
+
  827
+        # Read the module's source code.  This is used by
  828
+        # DocTestFinder._find_lineno to find the line number for a
  829
+        # given object's docstring.
  830
+        try:
  831
+            file = inspect.getsourcefile(obj) or inspect.getfile(obj)
  832
+            source_lines = linecache.getlines(file)
  833
+            if not source_lines:
  834
+                source_lines = None
  835
+        except TypeError:
  836
+            source_lines = None
  837
+
  838
+        # Initialize globals, and merge in extraglobs.
  839
+        if globs is None:
  840
+            if module is None:
  841
+                globs = {}
  842
+            else:
  843
+                globs = module.__dict__.copy()
  844
+        else:
  845
+            globs = globs.copy()
  846
+        if extraglobs is not None:
  847
+            globs.update(extraglobs)
  848
+
  849
+        # Recursively expore `obj`, extracting DocTests.
  850
+        tests = []
  851
+        self._find(tests, obj, name, module, source_lines, globs, {})
  852
+        return tests
  853
+
  854
+    def _filter(self, obj, prefix, base):
  855
+        """
  856
+        Return true if the given object should not be examined.
  857
+        """
  858
+        return (self._namefilter is not None and
  859
+                self._namefilter(prefix, base))
  860
+
  861
+    def _from_module(self, module, object):
  862
+        """
  863
+        Return true if the given object is defined in the given
  864
+        module.
  865
+        """
  866
+        if module is None:
  867
+            return True
  868
+        elif inspect.isfunction(object):
  869
+            return module.__dict__ is object.func_globals
  870
+        elif inspect.isclass(object):
  871
+            return module.__name__ == object.__module__
  872
+        elif inspect.getmodule(object) is not None:
  873
+            return module is inspect.getmodule(object)
  874
+        elif hasattr(object, '__module__'):
  875
+            return module.__name__ == object.__module__
  876
+        elif isinstance(object, property):
  877
+            return True # [XX] no way not be sure.
  878
+        else:
  879
+            raise ValueError("object must be a class or function")
  880
+
  881
+    def _find(self, tests, obj, name, module, source_lines, globs, seen):
  882
+        """
  883
+        Find tests for the given object and any contained objects, and
  884
+        add them to `tests`.
  885
+        """
  886
+        if self._verbose:
  887
+            print 'Finding tests in %s' % name
  888
+
  889
+        # If we've already processed this object, then ignore it.
  890
+        if id(obj) in seen:
  891
+            return
  892
+        seen[id(obj)] = 1
  893
+
  894
+        # Find a test for this object, and add it to the list of tests.
  895
+        test = self._get_test(obj, name, module, globs, source_lines)
  896
+        if test is not None:
  897
+            tests.append(test)
  898
+
  899
+        # Look for tests in a module's contained objects.
  900
+        if inspect.ismodule(obj) and self._recurse:
  901
+            for valname, val in obj.__dict__.items():
  902
+                # Check if this contained object should be ignored.
  903
+                if self._filter(val, name, valname):
  904
+                    continue
  905
+                valname = '%s.%s' % (name, valname)
  906
+                # Recurse to functions & classes.
  907
+                if ((inspect.isfunction(val) or inspect.isclass(val)) and
  908
+                    self._from_module(module, val)):
  909
+                    self._find(tests, val, valname, module, source_lines,
  910
+                               globs, seen)
  911
+
  912
+        # Look for tests in a module's __test__ dictionary.
  913
+        if inspect.ismodule(obj) and self._recurse:
  914
+            for valname, val in getattr(obj, '__test__', {}).items():
  915
+                if not isinstance(valname, basestring):
  916
+                    raise ValueError("DocTestFinder.find: __test__ keys "
  917
+                                     "must be strings: %r" %
  918
+                                     (type(valname),))
  919
+                if not (inspect.isfunction(val) or inspect.isclass(val) or
  920
+                        inspect.ismethod(val) or inspect.ismodule(val) or
  921
+                        isinstance(val, basestring)):
  922
+                    raise ValueError("DocTestFinder.find: __test__ values "
  923
+                                     "must be strings, functions, methods, "
  924
+                                     "classes, or modules: %r" %
  925
+                                     (type(val),))
  926
+                valname = '%s.__test__.%s' % (name, valname)
  927
+                self._find(tests, val, valname, module, source_lines,
  928
+                           globs, seen)
  929
+
  930
+        # Look for tests in a class's contained objects.
  931
+        if inspect.isclass(obj) and self._recurse:
  932
+            for valname, val in obj.__dict__.items():
  933
+                # Check if this contained object should be ignored.
  934
+                if self._filter(val, name, valname):
  935
+                    continue
  936
+                # Special handling for staticmethod/classmethod.
  937
+                if isinstance(val, staticmethod):
  938
+                    val = getattr(obj, valname)
  939
+                if isinstance(val, classmethod):
  940
+                    val = getattr(obj, valname).im_func
  941
+
  942
+                # Recurse to methods, properties, and nested classes.
  943
+                if ((inspect.isfunction(val) or inspect.isclass(val) or
  944
+                      isinstance(val, property)) and
  945
+                      self._from_module(module, val)):
  946
+                    valname = '%s.%s' % (name, valname)
  947
+                    self._find(tests, val, valname, module, source_lines,
  948
+                               globs, seen)
  949
+
  950
+    def _get_test(self, obj, name, module, globs, source_lines):
  951
+        """
  952
+        Return a DocTest for the given object, if it defines a docstring;
  953
+        otherwise, return None.
  954
+        """
  955
+        # Extract the object's docstring.  If it doesn't have one,
  956
+        # then return None (no test for this object).
  957
+        if isinstance(obj, basestring):
  958
+            docstring = obj
  959
+        else:
  960
+            try:
  961
+                if obj.__doc__ is None:
  962
+                    docstring = ''
  963
+                else:
  964
+                    docstring = obj.__doc__
  965
+                    if not isinstance(docstring, basestring):
  966
+                        docstring = str(docstring)
  967
+            except (TypeError, AttributeError):
  968
+                docstring = ''
  969
+
  970
+        # Find the docstring's location in the file.
  971
+        lineno = self._find_lineno(obj, source_lines)
  972
+
  973
+        # Don't bother if the docstring is empty.
  974
+        if self._exclude_empty and not docstring:
  975
+            return None
  976
+
  977
+        # Return a DocTest for this object.
  978
+        if module is None:
  979
+            filename = None
  980
+        else:
  981
+            filename = getattr(module, '__file__', module.__name__)
  982
+            if filename[-4:] in (".pyc", ".pyo"):
  983
+                filename = filename[:-1]
  984
+        return self._parser.get_doctest(docstring, globs, name,
  985
+                                        filename, lineno)
  986
+
  987
+    def _find_lineno(self, obj, source_lines):
  988
+        """
  989
+        Return a line number of the given object's docstring.  Note:
  990
+        this method assumes that the object has a docstring.
  991
+        """
  992
+        lineno = None
  993
+
  994
+        # Find the line number for modules.
  995
+        if inspect.ismodule(obj):
  996
+            lineno = 0
  997
+
  998
+        # Find the line number for classes.
  999
+        # Note: this could be fooled if a class is defined multiple
  1000
+        # times in a single file.
  1001
+        if inspect.isclass(obj):
  1002
+            if source_lines is None:
  1003
+                return None
  1004
+            pat = re.compile(r'^\s*class\s*%s\b' %
  1005
+                             getattr(obj, '__name__', '-'))
  1006
+            for i, line in enumerate(source_lines):
  1007
+                if pat.match(line):
  1008
+                    lineno = i
  1009
+                    break
  1010
+
  1011
+        # Find the line number for functions & methods.
  1012
+        if inspect.ismethod(obj): obj = obj.im_func
  1013
+        if inspect.isfunction(obj): obj = obj.func_code
  1014
+        if inspect.istraceback(obj): obj = obj.tb_frame
  1015
+        if inspect.isframe(obj): obj = obj.f_code
  1016
+        if inspect.iscode(obj):
  1017
+            lineno = getattr(obj, 'co_firstlineno', None)-1
  1018
+
  1019
+        # Find the line number where the docstring starts.  Assume
  1020
+        # that it's the first line that begins with a quote mark.
  1021
+        # Note: this could be fooled by a multiline function
  1022
+        # signature, where a continuation line begins with a quote
  1023
+        # mark.
  1024
+        if lineno is not None:
  1025
+            if source_lines is None:
  1026
+                return lineno+1
  1027
+            pat = re.compile('(^|.*:)\s*\w*("|\')')
  1028
+            for lineno in range(lineno, len(source_lines)):
  1029
+                if pat.match(source_lines[lineno]):
  1030
+                    return lineno
  1031
+
  1032
+        # We couldn't find the line number.
  1033
+        return None
  1034
+
  1035
+######################################################################
  1036
+## 5. DocTest Runner
  1037
+######################################################################
  1038
+
  1039
+class DocTestRunner:
  1040
+    """
  1041
+    A class used to run DocTest test cases, and accumulate statistics.
  1042
+    The `run` method is used to process a single DocTest case.  It
  1043
+    returns a tuple `(f, t)`, where `t` is the number of test cases
  1044
+    tried, and `f` is the number of test cases that failed.
  1045
+
  1046
+        >>> tests = DocTestFinder().find(_TestClass)
  1047
+        >>> runner = DocTestRunner(verbose=False)
  1048
+        >>> for test in tests:
  1049
+        ...     print runner.run(test)
  1050
+        (0, 2)
  1051
+        (0, 1)
  1052
+        (0, 2)
  1053
+        (0, 2)
  1054
+
  1055
+    The `summarize` method prints a summary of all the test cases that
  1056
+    have been run by the runner, and returns an aggregated `(f, t)`
  1057
+    tuple:
  1058
+
  1059
+        >>> runner.summarize(verbose=1)
  1060
+        4 items passed all tests:
  1061
+           2 tests in _TestClass
  1062
+           2 tests in _TestClass.__init__
  1063
+           2 tests in _TestClass.get
  1064
+           1 tests in _TestClass.square
  1065
+        7 tests in 4 items.
  1066
+        7 passed and 0 failed.
  1067
+        Test passed.
  1068
+        (0, 7)
  1069
+
  1070
+    The aggregated number of tried examples and failed examples is
  1071
+    also available via the `tries` and `failures` attributes:
  1072
+
  1073
+        >>> runner.tries
  1074
+        7
  1075
+        >>> runner.failures
  1076
+        0
  1077
+
  1078
+    The comparison between expected outputs and actual outputs is done
  1079
+    by an `OutputChecker`.  This comparison may be customized with a
  1080
+    number of option flags; see the documentation for `testmod` for
  1081
+    more information.  If the option flags are insufficient, then the
  1082
+    comparison may also be customized by passing a subclass of
  1083
+    `OutputChecker` to the constructor.
  1084
+
  1085
+    The test runner's display output can be controlled in two ways.
  1086
+    First, an output function (`out) can be passed to
  1087
+    `TestRunner.run`; this function will be called with strings that
  1088
+    should be displayed.  It defaults to `sys.stdout.write`.  If
  1089
+    capturing the output is not sufficient, then the display output
  1090
+    can be also customized by subclassing DocTestRunner, and
  1091
+    overriding the methods `report_start`, `report_success`,
  1092
+    `report_unexpected_exception`, and `report_failure`.
  1093
+    """
  1094
+    # This divider string is used to separate failure messages, and to
  1095
+    # separate sections of the summary.
  1096
+    DIVIDER = "*" * 70
  1097
+
  1098
+    def __init__(self, checker=None, verbose=None, optionflags=0):
  1099
+        """
  1100
+        Create a new test runner.
  1101
+
  1102
+        Optional keyword arg `checker` is the `OutputChecker` that
  1103
+        should be used to compare the expected outputs and actual
  1104
+        outputs of doctest examples.
  1105
+
  1106
+        Optional keyword arg 'verbose' prints lots of stuff if true,
  1107
+        only failures if false; by default, it's true iff '-v' is in
  1108
+        sys.argv.
  1109
+
  1110
+        Optional argument `optionflags` can be used to control how the
  1111
+        test runner compares expected output to actual output, and how
  1112
+        it displays failures.  See the documentation for `testmod` for
  1113
+        more information.
  1114
+        """
  1115
+        self._checker = checker or OutputChecker()
  1116
+        if verbose is None:
  1117
+            verbose = '-v' in sys.argv
  1118
+        self._verbose = verbose
  1119
+        self.optionflags = optionflags
  1120
+        self.original_optionflags = optionflags
  1121
+
  1122
+        # Keep track of the examples we've run.
  1123
+        self.tries = 0
  1124
+        self.failures = 0
  1125
+        self._name2ft = {}
  1126
+
  1127
+        # Create a fake output target for capturing doctest output.
  1128
+        self._fakeout = _SpoofOut()
  1129
+
  1130
+    #/////////////////////////////////////////////////////////////////
  1131
+    # Reporting methods
  1132
+    #/////////////////////////////////////////////////////////////////
  1133
+
  1134
+    def report_start(self, out, test, example):
  1135
+        """
  1136
+        Report that the test runner is about to process the given
  1137
+        example.  (Only displays a message if verbose=True)
  1138
+        """
  1139
+        if self._verbose:
  1140
+            if example.want:
  1141
+                out('Trying:\n' + _indent(example.source) +
  1142
+                    'Expecting:\n' + _indent(example.want))
  1143